elevenlabs-webhook-nodejs 1.0.0

package/docs/architecture/14-META-BUSINESS-API.md

@@ -0,0 +1,454 @@
+# Meta Business API Integration
+
+> WhatsApp Business Cloud API + Instagram Messenger Platform
+> Last updated: 2026-04-02
+
+---
+
+## 1. Overview
+
+Meta Business API is the **sole WhatsApp and Instagram provider** in the NestJS rewrite. It replaces both Baileys (unofficial) and Twilio, providing a single official integration for all messaging.
+
+Meta Business API provides:
+
+- **WhatsApp Business Cloud API** -- send and receive WhatsApp messages via the official API
+- **Instagram Messenger Platform** -- send and receive Instagram DMs
+- **Shared Webhook** -- a single webhook endpoint handles both channels
+
+There is no Baileys fallback. All tenants use Meta Business API exclusively.
+
+### Setup Requirements
+
+1. **Meta Developer App** -- registered at developers.facebook.com
+2. **WhatsApp Business Account (WABA)** -- one per tenant or shared
+3. **Phone Number** -- verified business phone number
+4. **Instagram Business Account** -- linked to a Facebook Page
+5. **Webhook Verification** -- GET endpoint with `hub.verify_token` challenge
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `META_APP_ID` | Meta app ID |
+| `META_APP_SECRET` | Meta app secret |
+| `META_VERIFY_TOKEN` | Webhook verification token (chosen by us) |
+| `META_API_VERSION` | API version (e.g., `v21.0`) |
+| `META_TOKEN_ENCRYPTION_KEY` | AES-256-GCM key for encrypting per-tenant access tokens |
+
+Per-tenant access tokens are stored encrypted in the `ClinicMetaConnection` table, following the same pattern as Google Calendar token encryption.
+
+---
+
+## 2. WhatsApp Business Cloud API
+
+### 2.1 Send Message (Text)
+
+```
+POST https://graph.facebook.com/{version}/{phone_number_id}/messages
+Authorization: Bearer {access_token}
+
+{
+  "messaging_product": "whatsapp",
+  "to": "905551234567",
+  "type": "text",
+  "text": { "body": "Hello from AI assistant" }
+}
+```
+
+### 2.2 Send Template Message
+
+Template messages are required for initiating conversations outside the 24-hour customer service window. When a patient has not sent a message in the last 24 hours, only pre-approved templates can be used.
+
+```
+POST https://graph.facebook.com/{version}/{phone_number_id}/messages
+{
+  "messaging_product": "whatsapp",
+  "to": "905551234567",
+  "type": "template",
+  "template": {
+    "name": "appointment_reminder",
+    "language": { "code": "tr" },
+    "components": [
+      {
+        "type": "body",
+        "parameters": [
+          { "type": "text", "text": "Ayse Yilmaz" },
+          { "type": "text", "text": "15 Nisan 2026 09:00" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+This replaces the Twilio template message integration. Template management UI is a P2 feature (Section 19.21 of the migration reference).
+
+### 2.3 Send Media
+
+```
+POST https://graph.facebook.com/{version}/{phone_number_id}/messages
+{
+  "messaging_product": "whatsapp",
+  "to": "905551234567",
+  "type": "image",
+  "image": { "link": "https://minio.example.com/signed-url..." }
+}
+```
+
+Media types: `image`, `video`, `audio`, `document`. All media files are served via MinIO signed URLs (1-hour TTL). Never public URLs.
+
+### 2.4 Send Interactive Message
+
+Buttons and list messages for structured patient interactions:
+
+```json
+{
+  "messaging_product": "whatsapp",
+  "to": "905551234567",
+  "type": "interactive",
+  "interactive": {
+    "type": "button",
+    "body": { "text": "Randevunuzu onaylıyor musunuz?" },
+    "action": {
+      "buttons": [
+        { "type": "reply", "reply": { "id": "confirm", "title": "Evet" } },
+        { "type": "reply", "reply": { "id": "cancel", "title": "Hayir" } }
+      ]
+    }
+  }
+}
+```
+
+### 2.5 Message Types Supported
+
+| Type | Description |
+|------|-------------|
+| `text` | Plain text messages |
+| `image` | Photos (URL or media ID) |
+| `video` | Video files |
+| `audio` | Voice messages |
+| `document` | File attachments (PDF, etc.) |
+| `location` | GPS coordinates |
+| `template` | Pre-approved templates (required for 24h window rule) |
+| `interactive` | Buttons and list messages |
+
+### 2.6 The 24-Hour Window Rule
+
+Meta enforces a customer service window:
+
+- **Within 24 hours** of the customer's last message: any message type can be sent freely
+- **Outside 24 hours**: only pre-approved template messages are allowed
+- Template messages must be submitted for Meta review and approved before use
+- Appointment reminders, follow-ups, and re-engagement all require templates
+
+The AI agent operates within the 24-hour window. Automated reminders and notifications use template messages.
+
+### 2.7 Webhook Payload (Incoming Message)
+
+```json
+{
+  "object": "whatsapp_business_account",
+  "entry": [{
+    "id": "WABA_ID",
+    "changes": [{
+      "value": {
+        "messaging_product": "whatsapp",
+        "metadata": {
+          "phone_number_id": "...",
+          "display_phone_number": "..."
+        },
+        "contacts": [{
+          "wa_id": "905551234567",
+          "profile": { "name": "Ayse" }
+        }],
+        "messages": [{
+          "id": "wamid.xxx",
+          "from": "905551234567",
+          "timestamp": "1711700000",
+          "type": "text",
+          "text": { "body": "Hello" }
+        }]
+      },
+      "field": "messages"
+    }]
+  }]
+}
+```
+
+The `contacts` array provides the sender's WhatsApp display name. The `metadata.phone_number_id` identifies which clinic phone number received the message, used for clinic routing (see Section 7 below).
+
+---
+
+## 3. Instagram Messenger Platform
+
+### 3.1 Send Message
+
+```
+POST https://graph.facebook.com/{version}/me/messages
+Authorization: Bearer {page_access_token}
+
+{
+  "recipient": { "id": "INSTAGRAM_SCOPED_USER_ID" },
+  "message": { "text": "Hello from AI assistant" }
+}
+```
+
+Instagram uses page-scoped user IDs. The sender ID from the webhook is specific to the connected Instagram business account.
+
+### 3.2 Webhook Payload (Incoming DM)
+
+```json
+{
+  "object": "instagram",
+  "entry": [{
+    "id": "INSTAGRAM_BUSINESS_ACCOUNT_ID",
+    "messaging": [{
+      "sender": { "id": "USER_ID" },
+      "recipient": { "id": "PAGE_ID" },
+      "timestamp": 1711700000,
+      "message": {
+        "mid": "msg_id",
+        "text": "Hello"
+      }
+    }]
+  }]
+}
+```
+
+Instagram messages follow the same AI agent flow as WhatsApp but are tagged with `ChatChannel.instagram` in the database.
+
+---
+
+## 4. Webhook Controller
+
+A single controller handles verification and incoming messages for both WhatsApp and Instagram.
+
+### 4.1 GET Verification (hub.challenge)
+
+Meta sends a GET request to verify webhook ownership during setup:
+
+```typescript
+@Controller('webhooks/meta')
+export class MetaWebhookController {
+
+  @Get()
+  verify(@Query() query) {
+    if (query['hub.verify_token'] === META_VERIFY_TOKEN) {
+      return query['hub.challenge'];  // Return the challenge as-is
+    }
+    throw new ForbiddenException();
+  }
+}
+```
+
+### 4.2 POST Handler -- Detect Channel and Emit Events
+
+```typescript
+@Post()
+async handleWebhook(@Body() body, @Headers() headers) {
+  // Verify signature (HMAC-SHA256 with META_APP_SECRET)
+  this.verifySignature(headers['x-hub-signature-256'], body);
+
+  if (body.object === 'whatsapp_business_account') {
+    // WhatsApp message -- extract and emit
+    for (const entry of body.entry) {
+      for (const change of entry.changes) {
+        if (change.field === 'messages' && change.value.messages) {
+          this.eventEmitter.emit('meta.whatsapp.message', {
+            wabaId: entry.id,
+            phoneNumberId: change.value.metadata.phone_number_id,
+            contacts: change.value.contacts,
+            messages: change.value.messages,
+          });
+        }
+      }
+    }
+  } else if (body.object === 'instagram') {
+    // Instagram DM -- extract and emit
+    for (const entry of body.entry) {
+      for (const messaging of entry.messaging) {
+        this.eventEmitter.emit('meta.instagram.message', {
+          pageId: entry.id,
+          senderId: messaging.sender.id,
+          message: messaging.message,
+          timestamp: messaging.timestamp,
+        });
+      }
+    }
+  }
+
+  return 'EVENT_RECEIVED';  // Always respond 200 immediately
+}
+```
+
+The webhook handler does **not** process messages inline. It emits events via `@nestjs/event-emitter`, and the WhatsApp module subscribes to handle them. This follows the architecture rule: modules communicate via EventEmitter, never direct service imports across module boundaries.
+
+### 4.3 Webhook Signature Verification
+
+Every incoming POST is verified with HMAC-SHA256:
+
+```typescript
+private verifySignature(signature: string, rawBody: Buffer): void {
+  const expected = 'sha256=' + createHmac('sha256', META_APP_SECRET)
+    .update(rawBody)
+    .digest('hex');
+
+  if (!timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
+    throw new ForbiddenException('Invalid webhook signature');
+  }
+}
+```
+
+---
+
+## 5. ClinicMetaConnection Table
+
+Each clinic can have **multiple** Meta Business connections (1:many). This enables a single clinic to have separate WhatsApp numbers and Instagram accounts (e.g., one for appointments, one for marketing).
+
+```prisma
+model ClinicMetaConnection {
+  meta_id                        String    @id @default(uuid())
+  meta_clinic_id                 String    // FK to Clinic (NOT unique -- 1:many)
+  meta_type                      String    // 'whatsapp' | 'instagram'
+  meta_label                     String?   // Human-readable label (e.g., "Appointments", "Marketing")
+  meta_is_active                 Boolean   @default(true)
+  meta_waba_id                   String?   // WhatsApp Business Account ID
+  meta_phone_number_id           String?   // Meta phone number ID
+  meta_display_phone             String?   // Human-readable phone number
+  meta_encrypted_access_token    String?   // AES-256-GCM encrypted (covers both page tokens and WABA tokens)
+  meta_instagram_page_id         String?
+  meta_connected_at              DateTime?
+  meta_created_at                DateTime  @default(now())
+  meta_updated_at                DateTime  @updatedAt
+
+  clinic Clinic @relation(fields: [meta_clinic_id], references: [clinic_id], onDelete: Cascade)
+
+  @@map("clinic_meta_connections")
+}
+```
+
+Key changes from the previous design:
+- `meta_clinic_id` is **not** unique -- a clinic can have multiple connections.
+- `meta_type` distinguishes WhatsApp vs Instagram connections.
+- `meta_label` and `meta_is_active` allow managing multiple connections per clinic.
+- `meta_encrypted_page_token` merged into `meta_encrypted_access_token` -- a single encrypted token field covers both WhatsApp and Instagram access tokens.
+- `meta_instagram_connected` boolean removed -- presence of an `instagram` type connection indicates connectivity.
+
+Access tokens are encrypted at rest with `META_TOKEN_ENCRYPTION_KEY` using the shared `EncryptionService`. Tokens are decrypted only when making API calls and are never stored in plaintext.
+
+---
+
+## 6. Channel Strategy
+
+### 6.1 Meta = Sole Provider
+
+Meta Business API is the **only messaging provider**. There is no Baileys fallback. All tenants use Meta exclusively for:
+
+- Standard AI conversations (appointment booking, patient questions)
+- Template messages (reminders, notifications, re-engagement)
+- Instagram DM support
+- Operator-in-the-loop workflows (media handled via Meta media download API + MinIO)
+- Official API with no risk of account bans
+
+### 6.2 ChatChannel Enum
+
+```typescript
+enum ChatChannel {
+  whatsapp    // WhatsApp message (via Meta Business API)
+  instagram   // Instagram DM (via Meta Business API)
+}
+```
+
+Stored on `WhatsAppChat.chat_channel` to distinguish message source. Both channels flow through the same AI agent pipeline.
+
+---
+
+## 7. Clinic Routing via Phone Number
+
+When a Meta webhook arrives, the system determines which clinic the message belongs to:
+
+```
+Incoming webhook
+  -> Extract phone_number_id from payload metadata
+  -> PhoneNumber table lookup: WHERE phone_external_account_id = phone_number_id
+                                AND phone_purpose = 'whatsapp'
+  -> PhoneNumber.phone_clinic_id -> Clinic
+  -> Clinic settings (agent, calendar, operator config)
+  -> Route to AI agent for that clinic
+```
+
+For Instagram:
+
+```
+Incoming webhook
+  -> Extract instagram_page_id from payload
+  -> ClinicMetaConnection lookup: WHERE meta_instagram_page_id = page_id
+  -> ClinicMetaConnection.meta_clinic_id -> Clinic
+  -> Route to AI agent for that clinic
+```
+
+---
+
+## 8. NestJS Module Structure
+
+```
+src/integrations/meta-business/
+  meta-business.module.ts       # MetaBusinessModule -- exports services
+  meta-whatsapp.service.ts      # WhatsApp Cloud API client (send text, template, media, interactive)
+  meta-instagram.service.ts     # Instagram Messenger client (send message)
+  meta-webhook.service.ts       # Shared webhook payload parser and signature verifier
+
+src/webhooks/
+  meta-webhook.controller.ts    # GET verification + POST handler (emits events)
+```
+
+`MetaWhatsAppService` and `MetaInstagramService` are exported from `MetaBusinessModule` and consumed directly by the WhatsApp module. There is no `BridgeService` abstraction -- Meta is the sole provider.
+
+---
+
+## 9. New Endpoints
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/whatsapp/meta/connect` | JWT (Admin) | Start Meta Business setup flow -- store WABA ID, phone number ID, encrypted token |
+| GET | `/whatsapp/meta/status` | JWT (Admin, Manager, Viewer) | Connection status for the current clinic |
+| POST | `/whatsapp/meta/disconnect` | JWT (Admin) | Disconnect Meta Business, clear tokens |
+| POST | `/whatsapp/instagram/connect` | JWT (Admin) | Connect Instagram account to clinic |
+| GET | `/whatsapp/instagram/status` | JWT (Admin, Manager, Viewer) | Instagram connection status |
+| POST | `/whatsapp/instagram/disconnect` | JWT (Admin) | Disconnect Instagram |
+| GET | `/webhooks/meta` | None | Webhook verification (hub.challenge response) |
+| POST | `/webhooks/meta` | None (HMAC-verified) | Incoming messages -- WhatsApp + Instagram |
+
+---
+
+## 10. Migration Notes
+
+### What Changes from Current System
+
+| Aspect | Current (Fastify) | Target (NestJS) |
+|--------|-------------------|-----------------|
+| WhatsApp provider | Baileys only (unofficial) | Meta Business API (sole provider) |
+| Notification messages | Twilio templates | Meta template messages |
+| Instagram | Not supported | Meta Messenger Platform |
+| Token storage | N/A | AES-256-GCM encrypted in `ClinicMetaConnection` |
+| Webhook format | Baileys/Unipile format | Meta webhook format (different payload structure) |
+| 24-hour window | Not applicable (Baileys) | Enforced by Meta -- must use templates outside window |
+| Connection model | 1:1 per clinic | 1:many per clinic (`meta_type` + `meta_label`) |
+
+### MetaWhatsAppService (Direct Usage)
+
+`MetaWhatsAppService` is used directly -- there is no `BridgeService` abstraction since Meta is the sole provider:
+
+```typescript
+async sendMessage(phoneNumberId: string, recipientPhone: string, text: string) {
+  const token = await this.getDecryptedToken(phoneNumberId);
+  return this.metaApi.post(`/${phoneNumberId}/messages`, {
+    messaging_product: 'whatsapp',
+    to: recipientPhone,
+    type: 'text',
+    text: { body: text },
+  }, { headers: { Authorization: `Bearer ${token}` } });
+}
+```
+
+The same pattern applies to `sendImage`, `sendMedia`, `sendTemplate`, and all other messaging operations.