hiberius/whatsapp-receptionist

Purpose and Runtime

WhatsApp Receptionist is a self-hostable, multi-tenant AI receptionist for Italian businesses. It receives WhatsApp text/voice messages, uses AI and tenant knowledge to respond or book Google Calendar appointments, and escalates conversations to human operators. It is a Next.js 15 App Router application running React 19, TypeScript, and Node 22.

Primary HTTP/UI entry points are the public site and route tree in src/app/page.tsx, tenant APIs in src/app/api/, inbound WhatsApp webhook handling in src/app/api/webhook/whatsapp/route.ts, and scheduled internal job routes in src/app/api/internal/jobs/.

Presentation, Identity, and Tenant Boundary

Route groups separate public marketing, authentication, tenant dashboard, and super-admin surfaces. Dashboard layouts enforce authenticated tenant access; admin is distinct and explicitly incomplete for cross-tenant data access.

• src/app/(auth)/layout.tsx

• src/app/(dashboard)/layout.tsx

• src/app/(admin)/layout.tsx

• src/middleware.ts

Supabase Auth supplies SSR-aware sessions. Server business services use a service-role client, so application-level tenant_id filtering is currently material; database RLS exists but is not exercised by normal server calls.

API-to-Domain Layer

Next Route Handlers are the transport boundary: they validate/authenticate requests and delegate business behavior to src/server/, which must not be imported by client components. Dashboard client forms use the internal API rather than directly accessing server services.

• src/app/api/conversations/[conversationId]/messages/route.ts

• src/app/api/settings/services/route.ts

• src/server/conversations/operator-messages.ts

• src/server/settings/tenant-settings.ts

Shared API parsing, JSON responses, session guards, rate limits, logging, and request security sit beneath this boundary.

WhatsApp Conversation Pipeline

The WhatsApp webhook verifies incoming provider events, resolves the claimed tenant number, persists/processes conversation state, and routes message handling. Auto-replies may be suppressed by opt-out, usage limits, escalation state, or guardrails. Outbound messages are staged in a durable outbox and sent by a cron job with retry/dead-letter behavior, decoupling provider delivery from most request paths.

• src/app/api/webhook/whatsapp/route.ts

• src/server/whatsapp/service.ts

• src/server/whatsapp/auto-reply.ts

• src/server/whatsapp/outbox.ts

• src/app/api/internal/jobs/whatsapp-outbox/route.ts

360dialog is the WhatsApp Business provider; per-tenant credentials are encrypted at rest. Voice messages flow through media handling and ElevenLabs transcription.

AI, Knowledge, and Booking

Reply orchestration builds tenant-specific context and prompts, classifies intent, retrieves semantic knowledge, generates an Anthropic Claude response, and invokes structured booking extraction/bridge when appropriate. Tenant-editable persona text is composed inside non-overridable safety rules. The booking service checks business hours/services and creates protected appointments; calendar integration synchronizes with Google Calendar.

• src/server/ai/reply-orchestrator.ts

• src/server/ai/intent-router.ts

• src/server/ai/booking-bridge.ts

• src/server/knowledge-base/documents.ts

• src/server/appointments/booking.ts

• src/server/calendar/google.ts

Persistence, Integrations, and Compliance

Supabase Postgres is the system of record for tenants, conversations, appointments, credentials, usage, audit data, and vector-backed knowledge; SQL migrations define schemas, constraints, and RLS. Google OAuth state is tenant-bound and signed; stored credentials are encrypted. Stripe controls subscription checkout, portal, and webhook lifecycle, with Italian SDI invoicing integration.

• supabase/migrations/202604240001_initial_backend_mvp.sql

• src/server/integrations/google-calendar-oauth.ts

• src/server/integrations/credential-encryption.ts

• src/server/billing/stripe-billing.ts

• src/app/api/webhook/stripe/route.ts

GDPR export, deletion, and retention are domain services invoked by tenant APIs and authenticated jobs.

Operations and Background Work

Vercel-hosted cron routes execute reminders, data retention/deletion, WhatsApp delivery/template/voice work, and health monitoring. Health checks probe critical external dependencies. Resend delivers operational and escalation mail; Upstash Redis supplies endpoint-specific rate limiting; Pino emits PII-redacted structured logs.

• vercel.json

• src/app/api/internal/jobs/appointment-reminders/route.ts

• src/app/api/internal/jobs/data-retention/route.ts

• src/server/monitoring/health-watchdog.ts

• src/lib/health/checks.ts