{"id":710,"date":"2026-10-29T13:16:48","date_gmt":"2026-10-29T13:16:48","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/ai-chatbot-whatsapp-api\/"},"modified":"2026-10-29T13:16:50","modified_gmt":"2026-10-29T13:16:50","slug":"ai-chatbot-whatsapp-api","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/en\/ai-chatbot-whatsapp-api\/","title":{"rendered":"AI chatbot on the official WhatsApp Business API: architecture and code"},"content":{"rendered":"\n

Updated on October 29, 2026<\/em><\/p>\n\n\n\n

To connect a chatbot or AI agent to WhatsApp through the official API, you receive each message by webhook, return 200 right away, put the event in a queue and let a worker build the context, call the language model and send the reply through the API. The bot’s free-form replies can only go out inside the 24-hour window the customer opened, and Meta’s policy requires a clear path to a human agent. Meta’s terms also prohibit using the platform to offer general-purpose AI assistants as the main product, with exceptions in a few countries, Brazil among them.<\/p>\n\n\n\n

This guide shows the architecture, the rules that affect the bot and a working Node.js example using Vectalk, which passes through the same payloads and webhooks as Meta.<\/p>\n\n\n\n

Architecture: webhook, queue, LLM and reply<\/h2>\n\n\n\n
Customer on WhatsApp\n      \u2502\n      \u25bc\nMeta \u2500\u2500POST\u2500\u2500\u25b6 Vectalk \u2500\u2500POST\u2500\u2500\u25b6 \/webhook (returns 200 and enqueues)\n                                     \u2502\n                                     \u25bc\n                                   Queue\n                                     \u2502\n                                     \u25bc\n                Worker: dedupe \u25b6 load history \u25b6 decide (bot or human)\n                                     \u2502\n                         \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n                         \u25bc                       \u25bc\n                   LLM writes reply         Human agent\n                         \u2502\n                         \u25bc\n             POST \/api\/messages (Vectalk) \u2500\u2500\u25b6 Meta \u2500\u2500\u25b6 Customer<\/code><\/pre>\n\n\n\n
Each piece has a clear job:<\/p>\n\n\n\n
Component<\/th>Responsibility<\/th>Main concern<\/th><\/tr><\/thead>
Webhook<\/td>Receive the event, validate it and return 200<\/td>Don’t call the LLM inside the request<\/td><\/tr>
Queue<\/td>Decouple receiving from processing<\/td>Guarantee a retry if the worker crashes<\/td><\/tr>
Deduplication<\/td>Ignore repeated events by their wamid<\/code> ID<\/td>Keep processed IDs for a few days<\/td><\/tr>
History<\/td>Build the conversation context by wa_id<\/code><\/td>Cap the size to control cost and latency<\/td><\/tr>
Router<\/td>Decide whether the bot replies or the conversation is with a human<\/td>Respect the handoff state<\/td><\/tr>
LLM<\/td>Generate the reply within the business scope<\/td>A prompt with clear limits and a maximum response time<\/td><\/tr>
Sending<\/td>Call the API and store the sent message ID<\/td>Handle errors and check the 24-hour window<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Why the queue is mandatory<\/h3>\n\n\n\n
A language model can take several seconds to answer. Vectalk expects HTTP 200 in under 20 seconds and resends the event if it doesn’t get it, according to its webhooks documentation<\/a>. If the endpoint waits for the LLM, a spike in messages causes resends, duplicate replies and double cost. With the queue, the webhook only stores the event and responds.<\/p>\n\n\n\n
The article on WhatsApp API webhooks<\/a> covers the event format, deduplication and status handling, and webhook signature validation<\/a> shows how to check X-Hub-Signature-256<\/code> before enqueueing.<\/p>\n\n\n\n
Mark as read and show “typing”<\/h3>\n\n\n\n
The Cloud API lets you mark the incoming message as read and show the typing indicator in the same call. According to the typing indicators documentation<\/a>, the indicator disappears when you reply or after 25 seconds, whichever comes first. Meta recommends showing it only if you are actually going to reply.<\/p>\n\n\n\n
{\n  \"messaging_product\": \"whatsapp\",\n  \"status\": \"read\",\n  \"message_id\": \"wamid.HBgLNTUx...\",\n  \"typing_indicator\": { \"type\": \"text\" }\n}<\/code><\/pre>\n\n\n\n
On Vectalk, this call goes to POST \/api\/messages<\/code>, the same endpoint documented for marking messages as read.<\/p>\n\n\n\n
The 24-hour window defines what the bot can send<\/h2>\n\n\n\n
When the customer sends a message, a 24-hour customer service window opens, and it renews with each new message from them. Inside it, the bot can reply with free-form text, media and interactive messages. Outside it, only approved templates (see Meta’s page on service messages and the customer service window<\/a>).<\/p>\n\n\n\n
In practice, this changes how you design the agent:<\/p>\n\n\n\n