WhatsApp API Integration Blueprint

User GuideDashboard

Integration Architecture

The WhatsApp Business OS connects to the WhatsApp Cloud API (Meta) to turn generated config packs into live, two-way WhatsApp conversations. The architecture has four layers:

Meta WhatsApp Cloud API

Transport: send/receive messages, template approvals, status webhooks

Webhook Layer (whatsappEventHub)

Verify signature, verify-token handshake, route by event type

Resolution Layer

whatsappTenantResolver + whatsappPersonaResolver + whatsappSessionManager

WhatsApp OS Core

Persona detection, scoring, evolution, regeneration, activity engine

Persistence

WhatsAppConversationLog + WhatsAppPersonaProfile + WhatsAppConfig

The OS generates and optimizes the configuration (greeting, templates, quick replies); the WhatsApp API handles the transport (sending/receiving actual messages). This separation lets the OS stay autonomous while Meta owns delivery.

Credentials & Secrets

The following secrets are already provisioned in the app and power the integration:

SecretPurpose
WHATSAPP_BUSINESS_TOKENBearer token for outbound API calls + webhook HMAC secret
WHATSAPP_PHONE_NUMBER_IDThe sender phone number ID (path param for /messages)
WHATSAPP_VERIFY_TOKENShared secret for the webhook subscription handshake
TWILIO_WHATSAPP_FROMTwilio WhatsApp sender (fallback channel)

The verify token must match exactly between the Meta app dashboard and the WHATSAPP_VERIFY_TOKEN secret. Webhook subscription fails silently if they differ.

Inbound Webhook Flow

Meta pushes message + status events to your webhook endpoint. The flow is:

1

Meta → Webhook

POST to /functions/whatsappEventHub with X-Hub-Signature-256 header.

2

Verify Signature

Recompute HMAC-SHA256 of the raw body using WHATSAPP_BUSINESS_TOKEN; reject on mismatch.

3

Verify Token (GET)

Meta calls the same endpoint with hub.verify_token on subscription — echo hub.challenge back.

4

Route by Type

whatsappEventHub classifies: message, status, template_status, reaction.

5

Resolve Tenant & Persona

whatsappTenantResolver + whatsappPersonaResolver map the phone number to a tenant + WhatsAppPersonaProfile.

6

Persist + Emit

Store in WhatsAppConversationLog; emit an event to the Activity Engine for suggestion generation.

7

Auto-Reply

If a quick-reply keyword matches, the session manager sends the mapped response back via the API.

Webhook subscription fields
Required subscription fields:
  messages
  message_template_status_update
  message_template_quality_update
  phone_number_quality_update
  account_update

Outbound Messaging

Outbound messages are sent via the Cloud API using the configured phone number ID. Two message types:

Template Messages

Used for proactive outreach (requires Meta-approved template). Maps directly to the templates array in each WhatsAppConfig version.

Text Messages

Free-form replies within the 24-hour customer service window. Used by the auto-reply quick-reply matcher.

Send a template message (POST /v21.0/{phone_id}/messages)
{
  "messaging_product": "whatsapp",
  "to": "<customer E.164>",
  "type": "template",
  "template": {
    "name": "application_ack",
    "language": { "code": "en" },
    "components": [
      { "type": "body", "parameters": [
        { "type": "text", "text": "Maria" },
        { "type": "text", "text": "Housemaid" }
      ]}
    ]
  }
}

The WhatsApp OS already generates the name, language, and body for every template — so sending is just a parameter substitution. Component parameters map to {{1}}, {{2}} placeholders.

Template Management Lifecycle

WhatsApp message templates must be submitted to Meta for approval before use. The OS produces the template definitions; the integration handles the lifecycle:

1

Generate

whatsappOsEngine builds template objects per persona category (name, category, language, body).

2

Submit to Meta

POST /v21.0/{waba_id}/message_templates with each template's name, category, language, and components.

3

Await Approval

Meta reviews (minutes to hours). Status flows: PENDING → APPROVED / REJECTED.

4

Status Sync

message_template_status_update webhooks update the template status; store on the WhatsAppConfig.

5

Send

Only APPROVED templates can be sent. Rejected templates need a content fix + resubmit.

6

Quality Monitoring

message_template_quality_update webhooks flag templates paused by Meta for low quality — feed back into regeneration.

OS Layer Mapping

Each OS component maps to a concrete WhatsApp API capability:

OS ComponentWhatsApp API Capability
Greeting MessageBusiness greeting (set via Meta dashboard)
Away MessageAuto-reply outside hours (Meta dashboard)
Quick RepliesInteractive button messages (type: button)
LabelsChat labels (organize inbox, no API send)
CatalogWhatsApp Commerce catalog items
TemplatesMessage templates (POST /message_templates)
Autonomy BrainDecides when to regenerate / suggest
Activity EngineConsumes message + status webhooks

Security & Rate Limits

  • Webhook signature verification — every inbound POST is HMAC-SHA256 verified against WHATSAPP_BUSINESS_TOKEN; unverified requests are rejected with 401.
  • Verify token handshake — the GET subscription handshake only succeeds when hub.verify_token matches WHATSAPP_VERIFY_TOKEN.
  • 24-hour window — free-form text replies only within 24h of the last inbound customer message; outside that, only approved templates are allowed.
  • Rate limits — Cloud API allows 80 messages/sec per phone number; burst protection backs off automatically.
  • Tenant isolation — inbound messages are resolved to a tenant via the recipient phone number; RLS ensures one tenant never sees another's conversations.
  • PII handling — message bodies are stored in WhatsAppConversationLog but never logged to the activity engine in plaintext; only aggregate stats feed the brain.

Implementation Roadmap

P1 — Connect

Complete
  • Secrets provisioned
  • whatsappEventHub webhook endpoint live
  • Verify-token handshake wired

P2 — Send

Complete
  • whatsappSessionManager sends templates
  • Quick-reply auto-reply matcher
  • Outbound status logging

P3 — Templates

In Progress
  • Bulk submit OS-generated templates to Meta
  • Sync approval status back to configs
  • Quality-update feedback loop

P4 — Intelligence

Planned
  • Brain-driven auto-send of optimal templates
  • Friction-triggered proactive check-ins
  • Persona-aware escalation routing

P5 — Scale

Planned
  • Per-tenant phone number provisioning
  • Shared WABA multi-brand routing
  • Conversation analytics export to BI