Connect WhatsApp Business Cloud API to Your AI Agent

Which WhatsApp Do You Want?

There are two completely different ways to put an agent on WhatsApp, and picking the wrong one costs an afternoon.

• QR-linked WhatsApp. You scan a code from the dashboard and the agent rides your existing WhatsApp account as a linked device. Two minutes, no Meta account, no business verification. This is the tile in Connect Platforms and it is what most people want.
• WhatsApp Business Cloud API — this page. A separate business number registered with Meta, an app in the Meta developer console, access tokens and a webhook. It takes real setup and it is the right answer when you are running a business line, need message templates, or want the agent independent of anyone's personal phone.

If you just want to chat with your agent on WhatsApp, use the QR route and skip this page entirely.

What You Need

• A Meta developer account and a Business account.
• A phone number for the business line that is not already registered to a normal WhatsApp account.
• A public HTTPS endpoint. Meta pushes incoming messages to a webhook, so it has to be able to reach your agent. Cloudflare Tunnel is the easiest option — free, no port forwarding, no domain needed. Contact support and we can help arrange a reachable endpoint for your instance.

Create the Meta App

1. In the Meta developer console, create an app and add the WhatsApp product to it.
2. From the API Setup screen, collect the phone number ID and a temporary access token. The test number Meta gives you is enough to prove the setup works before you register your real number.
3. Note your WhatsApp Business Account ID and App ID as well. Messaging works without them, but they are useful later for analytics.

Get a Permanent Token

The token on the API Setup screen expires within hours, which is fine for a first test and useless in production. For a token that lasts, create a system user in Business Settings, give it access to your WhatsApp Business Account, and generate a permanent token for it. Store that one — you cannot view it again.

Configure Hermes

Run the built-in setup from your instance's Web Terminal:

hermes whatsapp-cloud

It walks through the credentials and the webhook. You will be asked for the phone number ID, the access token, and a verify token you invent yourself — the last one is just a shared string Meta echoes back when it first calls your webhook, so any random value works as long as you paste the same one on both sides.

Point Meta at Your Webhook

Back in the Meta console, set the webhook callback URL to your public endpoint and paste the same verify token. Meta calls the URL immediately to verify it — if that check fails, the URL is not reachable or the token does not match. Then subscribe to the messages field, or your agent will be verified but never receive anything.

Test It

Send a message to the business number from a normal WhatsApp account and wait for the reply. Note the 24-hour rule: outside a 24-hour window since the customer's last message, Meta only allows pre-approved template messages, so a delayed free-form reply will silently fail to deliver. That surprises people more than anything else on this page.

Troubleshooting

• Webhook verification fails. The endpoint is not publicly reachable, or the verify token differs between Meta and your config.
• Verified but no messages arrive. You have not subscribed to the messages field.
• It worked for a few hours then stopped. You are still on the temporary token. Switch to a permanent system-user token.
• Replies to older conversations vanish. That is the 24-hour window — you need an approved template to reopen it.

Need a Hand?

Contact support from your dashboard. The Meta side has to be done by you because it is tied to your business identity, but we can set up the agent side and help with the endpoint. Never paste an access token into chat.