WhatsApp

The WhatsApp adapter integrates with the WhatsApp Cloud API (Meta) so agents can send and receive messages through your verified business number.

Prerequisites

• A Meta for Developers account
• A WhatsApp Business Account (WABA) — free tier available for development
• A verified phone number for WhatsApp Business
• A publicly accessible Snippbot URL with HTTPS

Setup

1. Create a Meta App

   Go to developers.facebook.com → My Apps → Create App.

   Select Business type, then add the WhatsApp product.

2. Collect credentials

   From the WhatsApp product page:

   • Phone Number ID: WhatsApp → API Setup → Phone Number ID
   • Access Token: WhatsApp → API Setup → Temporary or Permanent Access Token

   Note

   The temporary access token expires in 24 hours. For production, generate a permanent token from a System User in Business Settings.

3. Configure the webhook

   In WhatsApp → Configuration → Webhook:

   • Callback URL: https://your-snippbot-url.com/webhook/whatsapp
   • Verify Token: any string you choose (e.g., snippbot-verify-123)
   • Subscribed Fields: messages

   Click Verify and Save.

4. Store credentials in Snippbot

   Go to Settings → Channels → WhatsApp and enter:

   • Phone Number ID — your WhatsApp Business phone number ID
   • Access Token — the permanent or temporary access token from Meta
   • Verify Token — the same string you entered in Meta’s webhook configuration. This is used by the adapter to verify webhook registration requests from Meta, but must be configured separately in the Snippbot UI (it is not stored as a platform credential).

5. Start the adapter

   snippbot channel start whatsapp

6. Create a channel binding

   In Settings → Channels → WhatsApp → Bindings, click Add Binding:

   • Channel ID: your WhatsApp Business phone number (e.g., +1234567890)
   • Agent: which agent responds
   • Access mode: open / allowlist / admin_only

How it works

The WhatsApp Cloud API delivers messages as HTTP webhooks. The adapter:

1. Receives a webhook POST from Meta with the message payload
2. Verifies the signature using HMAC-SHA256 (X-Hub-Signature-256)
3. Normalizes the message into Snippbot’s internal format
4. Routes to the bound agent
5. Sends the response via the WhatsApp Cloud API

Message types

The adapter handles:

• Text messages — standard chat messages
• Image/document attachments — passed as file context to the agent

Outbound responses are sent as text messages. Formatted output uses WhatsApp’s supported text styles:

• *bold*, _italic_, ~strikethrough~, `code`

Webhook verification

Meta verifies your webhook by sending a GET request with:

• hub.mode=subscribe
• hub.verify_token=<your token>
• hub.challenge=<random string>

The adapter responds with the challenge if the token matches. This happens automatically — no manual action required.

Access control

Mode	Who can message the bot
open	Any WhatsApp user who messages your number
allowlist	Only approved phone numbers
admin_only	Only admin users in the binding

For personal/team use, set allowlist and add your own number.

Limitations

• WhatsApp Business API allows only one phone number per WABA on the free tier
• Meta requires a 24-hour message window — bots can only reply within 24 hours of the last user message (or use approved templates for outbound)
• Phone numbers must be verified by Meta

Troubleshooting

Webhook verification failed

The adapter must be running before you save the webhook URL in Meta’s portal:

snippbot channel status whatsapp

Messages not delivering

1. Check the access token hasn’t expired (temporary tokens last 24 hours)
2. Verify the phone number is active in your WABA
3. Check adapter logs: snippbot channel logs whatsapp

Signature verification errors

Ensure the X-Hub-Signature-256 header is being forwarded correctly through your reverse proxy. Nginx may need:

proxy_pass_request_headers on;