One shared inbox, intelligent AI replies, automated lead qualification, and a pipeline built around conversations. Built on the official Meta WhatsApp Business Cloud API.
Meta app secret — webhook HMAC and Embedded Signup code exchange. Server only
WHATSAPP_ES_CONFIG_ID
Facebook Login for Business configuration ID for Embedded Signup
WHATSAPP_API_VERSION
Graph API version. Defaults to v19.0; Meta recommends v25.0 for Embedded Signup
WHATSAPP_REGISTER_PIN
Optional 6-digit 2FA PIN used to register newly onboarded numbers. Registration is skipped when unset
ENCRYPTION_KEY
AES-256-GCM key for secrets at rest (access tokens, app secrets)
PUSHER_APP_ID / PUSHER_KEY / PUSHER_SECRET
Pusher real-time
NEXT_PUBLIC_APP_URL
http://localhost:3000
WHATSAPP_APP_SECRET must never be exposed to the browser. The app ID and the
Embedded Signup config ID reach the client through /api/integrations/whatsapp/config,
which is authenticated and returns no secrets — do not add NEXT_PUBLIC_* copies.
WhatsApp Embedded Signup (Meta onboarding)
Customers connect WhatsApp through Meta's official
Embedded Signup flow
rather than by pasting credentials. Settings → WhatsApp (and each card on
/businesses) shows a Continue with Facebook button that runs Meta's dialog;
the result is verified server-side and saved as a WhatsAppIntegration of the
business — one row per connected number, so a business can connect several.
One-time Meta app setup
In the Meta app, add the WhatsApp product and complete App Review for
advanced access to whatsapp_business_management and whatsapp_business_messaging.
Create a Facebook Login for Business configuration from the template
"WhatsApp Embedded Signup Configuration With 60 Expiration Token", and copy the
configuration ID into WHATSAPP_ES_CONFIG_ID.
Set the app's webhook callback to <NEXT_PUBLIC_APP_URL>/api/webhook/whatsapp
with WHATSAPP_VERIFY_TOKEN as the verify token. Embedded Signup subscribes each
customer's WABA to this app, so every customer's traffic arrives at that one URL,
signed with WHATSAPP_APP_SECRET. Customers never configure a webhook themselves.
What happens on connect
Step
Where
Graph call
Customer authorises, picks WABA + number
Meta's dialog
Facebook Login for Business
Exchange the 30-second code for a business token
/api/integrations/whatsapp/connect
GET /oauth/access_token
Confirm which WABAs the token really covers
same
GET /debug_token → granular_scopes[].target_ids
Confirm the phone number is on that WABA
same
GET /<WABA_ID>/phone_numbers
Point the customer's WABA at our webhook
same
POST /<WABA_ID>/subscribed_apps
Register the number for Cloud API
same
POST /<PHONE_NUMBER_ID>/register
The waba_id and phone_number_id the browser reports are treated as hints and
re-derived from Meta before anything is written — see selectWaba() /
selectPhoneNumber() in lib/whatsappEmbeddedSignup.ts and the tests in
tests/whatsapp-embedded-signup.test.ts.
Manual credential entry is still available under Settings → WhatsApp → Manual setup
for workspaces that predate this flow and for deployments whose Meta app is not yet
approved. Hand-entered credentials are mirrored into a WhatsAppIntegration row
whenever they are saved, so they behave like any other connected number.
Multiple numbers per business
WhatsAppIntegration is the runtime source of truth (lib/whatsappIntegrations.ts,
rules in lib/whatsappIntegrationRules.ts):
Path
Which number
Inbound webhook
metadata.phone_number_id → its active WhatsAppIntegration → tenant + business. A disconnected number is ignored. Numbers with no row fall back to the legacy Business/TenantSettings lookup.
Conversations
One thread per contact per number; Conversation.whatsappIntegrationId records it.
The conversation's own number (resolveConversationWhatsAppCreds). If that number is disconnected the send is refused — never re-sent from a different number.
Campaigns, templates
The business's default number (resolveWhatsAppCreds), then legacy credentials.
Test / Disconnect
Per number (integrationId). Disconnect keeps the row (inactive, token wiped) and promotes the next number to default.
Guarantees: a phone_number_id is globally unique (unique index; concurrent
connects of the same number get a 409), and a business has at most one default
(row lock + partial unique index).
Deploying the multi-number change
Apply prisma/migrations/20260918120000_whatsapp_integrations/migration.sql
(idempotent; safe on a database that already has the table from db push).
It refuses to run if two rows share a phoneNumberId.
prisma db push does not know the partial "one default per business" index and
may drop it — re-apply the migration file afterwards.
npm run db:backfill-whatsapp -- --dry-run, review, then npm run db:backfill-whatsapp
to mirror existing hand-entered numbers and attach their conversations.
hooks/useLeads.ts — useCreateLead(), useUpdateLeadStage() with optimistic update
CRITICAL RULE — every Prisma query:
// Never forget tenantId or you will leak data across workspaces
const leads = await prisma.lead.findMany({
where: { tenantId: session.user.tenantId }
});
Data Model Quick Reference
Lead stages:NEW_LEAD → CONTACTED → QUALIFIED → PROPOSAL_SENT → NEGOTIATION → WON | LOST
