Connect an agent to WhatsApp
People message a WhatsApp Business number and the agent answers in the chat, using the same prompt, knowledge bases and tools it uses everywhere else. Every person gets their own conversation, and the agent remembers them the next time they write.
The WhatsApp channel is in beta and enabled per workspace. Until it is enabled the channel does not appear in your dashboard at all. Ask your account contact to turn it on.
Two ways in
A WhatsApp Business number reaches your agent one of two ways. Both give the same channel; they differ in whose number it is and what you set up.
Pick the first unless your number is already on WhatsApp. A number that is already registered with WhatsApp cannot be registered again without leaving it first.
On a phone number of yours
Connect the channel
In the dashboard, go to Channels, choose Connect a WhatsApp number, and pick A phone number of yours. Choose the number from your own numbers - one bought or imported here, not already on WhatsApp - and give the channel a name.
Attach the agent
On the agent you want answering, open its Channels tab and attach this WhatsApp channel. A front door with no agent behind it has nowhere to send a message.
Register the number
Registration for WhatsApp Business runs through Meta’s own signup inside our carrier’s portal, and it asks for an admin of your Meta Business Manager to sign in. Book a short call with us: you sign in, choose or create the WhatsApp Business Account, and the number is verified by a code sent to it. Nothing is pasted anywhere, and no token of yours is held by us.
The channel page carries the inbound URL we point the account’s webhook at; keep it handy for the call.
Your number keeps doing everything it did: calls still ring the agent, texts still arrive. WhatsApp is added beside them, and a person who calls, texts and WhatsApps the number is one thread to the agent.
On your own Meta app
You configure the app in your own Meta developer account and give us two secrets from it: a permanent access token, and the app’s App Secret. Both stay under your control; revoke them from your own Meta account and the channel stops.
Connect the channel
In the dashboard, go to Channels, choose Connect a WhatsApp number, pick Your own Meta app, and give the channel a name.
Saving it opens the channel’s page with a Finish setup in your Meta app panel. It carries the two things you cannot assemble by hand: this channel’s own callback URL, and the verify token Meta’s webhook check is answered with.
Attach the agent
On the agent you want answering, open its Channels tab and attach this WhatsApp channel. Meta’s verification later is routed to that agent, so it fails until one is attached.
Create a Meta app and add WhatsApp to it
At developers.facebook.com/apps, create an app of type Business and add the WhatsApp product. Add your business number, or start on the test number Meta gives you.
Generate a permanent access token
In Business Manager, under System users, create a system user, assign it the app and the WhatsApp Business Account, and generate a token with the whatsapp_business_messaging and whatsapp_business_management permissions. In the dashboard here, go to Credentials and save it as a Bearer token credential.
Copy the App Secret
From the app’s App settings → Basic, copy the App Secret. Save it as a Shared secret credential. Every callback from Meta is verified against it.
Fill in the channel
On the channel page, enter the phone number ID and the number from the app’s WhatsApp product page, and paste the two credential ids. Events for any other number on the app are ignored.
Try it
Message the number on WhatsApp:
The reply comes back in the same chat. On your own Meta app the ticks turn blue and a typing indicator shows while the agent works; on a number of ours the reply is the first thing you see.
A reply longer than one WhatsApp message is sent as several. A picture the agent makes - a chart of your data, say - arrives as a picture.
Restrict who can message the number
Anyone who knows the number can write to it. For an internal agent, or one meant for a known set of people, open the channel in the dashboard and list their phone numbers under Who may message this channel, one per line, with the country code (+41 79 123 45 67).
Only listed numbers get an answer. A message from anyone else is ignored silently: it is not answered, not counted, and not kept. Leave the list empty to open the number to everyone.
The same list is on the API as allowed_senders on the channel:
Set the list before the number goes live if the agent should never answer a stranger: the number is reachable the moment it is registered.
What the agent reads, and what it ignores
A picture, a document or a voice note is read. Send a photo or a PDF with a question and the message reaches the agent with whatever you typed; the file is kept in your workspace and the agent opens it. A voice note is kept as a file and named to the agent, which cannot yet listen to it.
The agent ignores what is not a person speaking to it: reactions, delivery statuses, and anything Meta marks as unsupported.
Every chat is one person. Unlike a Slack channel, a WhatsApp chat has exactly one human in it, so the agent attaches that person’s identity to the conversation and per-person memory works on every message. The person is recorded as a contact by their phone number, asserted_by: channel: WhatsApp vouches that the account holds that number, but it is a WhatsApp account rather than a user in your own system, so it stays its own contact until you link or merge it with the person you already know - by a value your systems already hold.
Limits worth knowing
- Replies only, for now. The agent answers messages people send it. WhatsApp allows a free-form message only within 24 hours of the person’s last message, which a reply always is; reaching a person first needs an approved template, which the channel does not send yet.
- One person per chat. Groups are not supported.
- 4096 characters per message. Longer replies are split.
- Markdown is rendered into WhatsApp’s own markup. Bold, italics, lists and code come through; a heading becomes a bold line and a table a monospace block, because WhatsApp has no other way to show them.
Troubleshooting
Meta says the callback URL could not be verified
Two causes, in this order. Nothing attached: verification is routed to the agent behind the channel, so an unattached channel answers “not found”. Otherwise the verify token - it has to be the one on the channel page, exactly.
The URL verified but the agent never answers
On your own Meta app, check the app is in Live mode. A Development-mode app verifies the URL, accepts the subscription and sends no message webhooks for a real number, and there is nothing on our side to see. Then check the messages field is subscribed, and that the phone number ID on the channel page matches the number the message went to: events for any other number on the app are dropped without a reply.
The reply was refused with a 24-hour window error
A free-form message reaches a person only within 24 hours of their last message to the number. A reply to a message is always inside it; a message sent later is not, and needs a template.
The agent answered twice
Report it. Meta retries a webhook it did not get a 200 for, for up to a week and in no particular order, and duplicate answers should be impossible: every message carries an id we record before doing any work.