How a message travels
- A customer writes to your WhatsApp number.
- We store it in the inbox and send it to your webhook as
message.received. - Your agent decides what to say.
- Your platform calls
POST /api/v1/conversations/{conversationId}/reply. - We send it on WhatsApp and add it to the thread as the agent’s reply.
Set it up
1
Connect your WhatsApp number
On WhatsApp, connect your own WhatsApp Business Account — a new one or
one you already have. Then choose an agent for the number. The agent is
where these conversations are filed, and its webhooks are where the
messages go. Its own prompt is not used.
2
Choose External Agents
In the number’s agent picker, choose External Agents. The agent you
picked in the previous step stays behind it. The number then shows these
same steps, with links. Only admins can change it; choosing an agent again
hands the number back to ThinnestAI.
3
Create an API key
Settings → API keys. Send it on every call as
Authorization: Bearer ta_live_…. See authentication.4
Add a webhook
On that agent’s Actions page, add your platform’s HTTPS address and
tick A customer sent a WhatsApp message. Or create it through the
webhooks API with
"events": ["message.received"].
It must be ticked by name — an endpoint set to receive every event does
not get it, so your Slack or helpdesk webhooks are not flooded.
Keep the signing secret — it is shown once.5
Reply
Call
POST /api/v1/conversations/{id}/reply
with the conversationId from the event.What your webhook receives
media— when the customer sent a photo, voice note, video or document:{ "kind": "image" | "audio" | "video" | "file", "mimeType", "filename" }. The file itself is not in the event — read the conversation’s messages for a download link.form— when the customer submitted a WhatsApp form:{ "answers": { "field": "value" } }.text— the message, or a media message’s caption.messageId— the same id the messages API returns, so you can tell a message you already handled from a new one.
x-thinnest-signature: sha256=…, an HMAC-SHA256 of the
raw body under your signing secret. Check it before trusting the body.
Every message is sent, not just the last one in a burst. If a customer sends
three messages quickly, your platform gets three events.
What your agent can send
One kind per call. The full reference, with every refusal, is on
Reply to a conversation.
When a person takes over
If a teammate takes a conversation over in the inbox, your agent’s replies to it are refused, and its new messages are not sent to your webhook, until the conversation is handed back. That way the customer never has two voices answering at once. The teammate’s exchange can be read through the conversations API. “STOP” and other opt-outs are handled before anything reaches you. The customer is unsubscribed from marketing whatever your agent does.Pricing
Meta bills your WhatsApp Business Account directly for its fee on each message, at Meta’s rates. ThinnestAI charges 10% of Meta’s rate per message, from your wallet — pay as you go, with no monthly subscription. A message Meta does not charge for costs nothing from us either. Replies your teammates send from the inbox or a connected helpdesk on these numbers are charged the same way. There is no AI usage to pay for on these numbers, because your agent does the answering.If your endpoint misses a message
Each event is sent once. An event your endpoint does not accept is not retried, and after five failures in a row the webhook is switched off. Nothing is lost: read back what you missed with the conversations API, then switch the webhook back on.Not available yet
- No typing indicator or read receipts from your agent.
- WhatsApp only. Website chat, Telegram and voice are answered by ThinnestAI agents.