Connect the agent to WhatsApp through the Meta Cloud API or Twilio.
Roberty supports two providers for the WhatsApp integration:
- Meta Cloud API (recommended) — straight to Meta, with nobody in between.
- Twilio — for organisations already on Twilio's infrastructure.
Reach it through the Settings icon → Integrations tab → the WhatsApp card.
Turning the integration on
Turn on the toggle in the WhatsApp card. The configuration fields appear once it is on.
Turning the toggle on is not enough. While the fields below (Phone Number ID, Access Token, App Secret and Verify Token, for the Meta Cloud API) are empty, the integration shows as "on" but Meta's webhook always fails verification — that is the most common cause of "The callback URL or verify token couldn't be validated" in the Meta for Developers panel. Fill in all four fields and wait for the save indicator before clicking Verify and Save at Meta.
How it works
- The provider sends a webhook when a message arrives.
- Roberty validates the signature (where there is one) and resolves the agent.
- The agent runs and the answer goes back through the provider's outbound API.
The base endpoint is:
https://agent-backend.roberty.app/integrations/whatsapp/<AGENT_ID>
Use Copy ID at the top of the Integrations tab to get the AGENT_ID.
Provider
Choose the provider that sends the messages:
| Provider | When to use it |
|---|---|
| Meta Cloud API | A direct integration with WhatsApp Business through Meta — recommended for most cases |
| Twilio | When your organisation already uses Twilio for messaging |
Provider: Meta Cloud API
The configuration fields
| Field | What it is |
|---|---|
| Phone Number ID | The identifier of the phone number registered at Meta |
| Access Token | A permanent access token generated in the Meta Developer Portal |
| App Secret | The Meta application's app secret (it enables HMAC validation of the requests) |
| Verify Token | A verification string — it must match the one configured in Meta's webhook |
Prerequisites
- An account at Meta for Developers.
- A Business app with the WhatsApp product enabled.
- A test (or production) phone number attached to the app.
1. Configure the agent in Roberty first
Before going to Meta, fill in all four fields here. That avoids the handshake error, because Meta only validates the webhook if the Verify Token is already saved on the agent when you click "Verify and Save" on Meta's side.
| Field | Where to find it at Meta | Official tutorial (direct link to the section) |
|---|---|---|
| Phone Number ID | The app's panel → WhatsApp → API Setup. It appears under the number selected in "From". | Get Started — Step 3. Send and receive messages |
| Access Token (permanent) | Do not use the temporary token shown on the "API Setup" screen (it expires in 24h). Generate a permanent one: Business Settings → Users → System users → create a system user → Generate new token, with the whatsapp_business_messaging and whatsapp_business_management permissions and expiry Never. Then attach that user to the WhatsApp Business account under Accounts → WhatsApp accounts → Add people. | Get Started — Step 5. Create a system user and generate a permanent access token |
| App Secret | The app's panel → Settings → Basic → the "App Secret" field → Show (it asks for your password). | App Dashboard — App Secret |
| Verify Token | This does not come from Meta — it is a string you choose yourself (generated with openssl rand -hex 24, for instance). It must be identical on both sides: here in Roberty and in the "Verify token" field of Meta's webhook (the next step). | Webhooks — Verification Requests |
Fill in all four and wait for the Studio's save indicator before going on.
2. Configure the webhook at Meta
In the app's panel, under WhatsApp → Configuration → Webhook:
- Callback URL:
https://agent-backend.roberty.app/integrations/whatsapp/<AGENT_ID> - Verify Token: paste exactly the value you already saved in Roberty's Verify Token field.
- Click Verify and Save. Roberty answers the challenge automatically as long as the Verify Token matches what is configured on the agent.
Then, under Webhook fields, subscribe to at least messages.
Security validation
With App Secret configured, Meta sends the X-Hub-Signature-256: sha256=<hmac> header, and Roberty recomputes HMAC-SHA256(appSecret, rawBody) and compares with timingSafeEqual.
With App Secret blank, that validation is off — not advisable in production.
Provider: Twilio
The configuration fields
| Field | What it is |
|---|---|
| Account SID | Your Twilio account's SID |
| Auth Token | Your Twilio account's auth token |
Prerequisites
- A Twilio account with a WhatsApp number enabled (sandbox, or an approved sender).
- A configured sending number (
whatsapp:+14155238886, for instance).
1. Configure the webhook at Twilio
In the Twilio console, under Messaging → Settings → WhatsApp Senders (or in the sandbox), set:
- When a message comes in:
https://agent-backend.roberty.app/integrations/whatsapp/<AGENT_ID>(method POST). - Content-Type:
application/x-www-form-urlencoded(Twilio's default).
2. Configure the agent in Roberty
Choose the Twilio provider and fill in Account SID and Auth Token.
The current version does not validate the X-Twilio-Signature header. We recommend restricting the endpoint by IP, or using a dedicated route per agent and not publishing the AGENT_ID.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| Meta says "The callback URL or verify token couldn't be validated", even with the WhatsApp toggle on in Roberty | The Phone Number ID / Access Token / App Secret / Verify Token fields are empty in Roberty — turning the toggle on fills nothing in. Fill in all four (see the table above), wait for the save, and only then click Verify and Save at Meta. |
| Meta's handshake fails (even with the fields filled in) | The agent's verifyToken does not match what was entered in the webhook exactly — check for a stray space or line break when pasting on either side. |
401 Invalid signature (Meta) | The appSecret is wrong, or the raw body was not preserved. |
| The message arrives but the agent does not answer | The wrong provider is configured (Meta receiving Twilio's form-encoded payload, for instance). |
| Twilio delivers the message twice | Twilio redelivers on a timeout. |