Skip to main content
The WhatsApp adapter uses Meta’s WhatsApp Business Cloud API. Meta delivers messages to a webhook the gateway serves, so the endpoint must be reachable over HTTPS from the internet, and every delivery is checked against your app secret.

​
Set it up

1

Prepare the Meta app

In Meta for Developers, create an app with the WhatsApp product. Note the access token, the phone number ID of the number that will answer, and the app’s App Secret (App settings → Basic). Choose a verify token of your own: any string you will type in both places.
2

Configure ChatCLI

3

Start the gateway

4

Register the webhook

In the app’s WhatsApp configuration, set the callback URL to the public HTTPS address that reaches CHATCLI_WHATSAPP_ADDR and CHATCLI_WHATSAPP_PATH, for example https://bot.example.com/whatsapp/webhook, and the verify token to the same string. Meta checks it right away, so the gateway must already be running. Then subscribe the webhook to the messages field.

​
Environment variables

​
Who can reach the bot

Deliveries without a valid signature are refused, so only Meta can feed the webhook. Past that, anyone who messages the business number reaches the agent, which runs with its tools and shell.
There is no sender allow-list on WhatsApp. Use a number that only the intended people know, and harden the agent with security mode before exposing it.

​
Messages

  • Handled message types: text, audio (voice notes) and images. Video, documents, stickers, locations, reactions and interactive messages are ignored.
  • Voice: the audio is downloaded through the Graph API and transcribed before the agent runs.
  • Images: the image reaches the model with a default instruction to describe it; the caption you type with an image is not read, so send the question as a separate message.
  • Image replies are uploaded to WhatsApp and sent with the reply text as the caption; on failure the text is sent alone.
  • Each sender is one conversation, keyed by phone number.

​
Limits

  • A reply is cut at 3500 characters and ends with ….
  • WhatsApp only accepts free-form messages within 24 hours of the person’s last message. A proactive message outside that window fails, since the gateway does not send templates.
  • Meta retries a delivery it did not see acknowledged in time; a retried delivery is processed again.

​
Troubleshooting

The gateway must be running and reachable at the URL, and CHATCLI_WHATSAPP_VERIFY_TOKEN must match the token typed in Meta’s dashboard. With the variable unset, verification is refused with 403.
Set CHATCLI_WHATSAPP_APP_SECRET: without it every delivery is refused with 401. ~/.chatcli/gateway.log shows a “rejected an inbound delivery with no valid signature” line for each one. Also check that the webhook is subscribed to the messages field.

​
See also

Chat gateway

How messages run, voice, images, continuity and the other channels.

Proactive messaging

Send messages first with @send, within WhatsApp’s 24-hour window.