--- title: "How to ship an AI agent on WhatsApp to production (WABA in practice)" description: "The no-nonsense guide from someone who's done it: from the WhatsApp Business API to the 24-hour window, HSM templates, LLM fallback, and what separates a demo bot from an agent that survives production." slug: agente-ia-whatsapp-producao lang: en date: 2026-07-22 updated: 2026-07-22 author: Lucas Silva category: deep-dive tags: [WhatsApp, WABA, AI Agents, Conversational AI, Production, LLM] reading_time: 12 featured: true --- Most of the "AI agents on WhatsApp" I see out there never make it past the demo. They work in the LinkedIn video, they answer beautifully in a controlled environment, and they collapse the moment a real customer shows up. This post is the opposite of that: it's what I learned putting real agents into the wild, handling support, selling, and solving problems 24 hours a day. If you want a bot to post about, you don't need to read this. If you want an agent that survives production, pull up a chair. ## First things first: you need the WABA, not regular WhatsApp There's one distinction that sinks 90% of projects right at the start. The WhatsApp you use on your phone — and even the **WhatsApp Business** app — isn't built for automation at scale. The right tool is the **WhatsApp Business API (WABA)**, Meta's official API. With the WABA you get three things that don't exist in the app: - **Programmatic sending and receiving** via webhook and REST endpoints, with no phone that has to stay powered on. - **Multiple agents and automation** on the same number, without the single-session limitation. - **Approved templates** to legitimately start conversations (more on that shortly). The unofficial route — libraries like Baileys that emulate WhatsApp Web — works for a prototype, but it's a ticking time bomb: number bans, breakage with every protocol update, zero guarantees. For anything serious, it's WABA. Period. ## The 24-hour window: the rule most people ignore Here's the concept that separates the people who get it from the people who just skimmed the docs. Meta splits messages into two worlds: 1. **Inside the 24h window** — after the *customer* sends you a message, a 24-hour window opens in which you can respond freely, with text, media, whatever you want. This is the "service" conversation. 2. **Outside the window** — 24 hours passed with no message from the customer, or you want to be the first to reach out? Then you can **only** open with an **approved template** (HSM — Highly Structured Message). Ignoring this is the #1 cause of "my message isn't arriving." It's not a bug, it's a rule. Your agent needs to know what state the conversation is in and choose between a free reply and a template — automatically. In practice, I model this as a simple state machine per contact: ``` NEW → only a template can open OPEN_24H → free reply allowed (I store the timestamp of the customer's last msg) EXPIRED → back to template ``` Every message received on the webhook renews the `timestamp`. Before any proactive send, I check the window. Simple, but it's what keeps the operation alive. ## HSM templates: where bureaucracy meets conversion Every template that starts a conversation has to be **approved by Meta** before it runs. They have categories (marketing, utility, authentication), and the category changes the price and the tolerance for rejection. What I learned the hard way: - **Write the template with approval in mind, not just the customer.** A vague promise, an over-the-top urgency trigger, and a bare "click here" get your template rejected. A well-written utility template passes easily. - **Variables are positional** (`{{1}}`, `{{2}}`). Document what each one means in your code, because six months from now you won't remember. - **Have a template fallback.** If a template gets paused for quality, your operation can't stop. I keep approved backup variations on hand. The number's quality (the famous *quality rating* — green/yellow/red) rises and falls as customers mark you as spam or block you. A bad template drops the rating, a bad rating drops your sending limit. It's a cycle — and it forces you to stay relevant. ## The minimal architecture of an agent that survives production A WhatsApp agent that actually works isn't "webhook → OpenAI → response." That naive version breaks with the first customer who sends three messages in a row, an audio, and a photo. The real architecture has layers: **1. Ingestion (webhook)** Receives Meta's payload, validates the signature, and — this is crucial — **returns 200 immediately**. Processing is asynchronous, in a queue. If you process synchronously, Meta resends the webhook thinking it failed, and you process the same message twice. **2. Normalization** Text, audio, image, document, location, a clicked button — everything becomes a single internal format. Audio goes through transcription (STT) before reaching the LLM. The agent shouldn't know or care whether the source was voice or text. **3. Message aggregation (debounce)** A real customer doesn't send a paragraph. They send "hi," then "I wanted to ask," then "about your plan" — three webhooks in five seconds. If you respond to each one, the agent looks schizophrenic. I batch messages within a short window (about 3–8 seconds of silence) before triggering the LLM. It changes everything about how natural it feels. **4. The brain (LLM + context + tools)** This is where the intelligence lives: the conversation history, the customer's data (from the CRM/ERP), and the **tools** the agent can call — look up an order, open a ticket, schedule a visit. The LLM *isn't* the product; it's the orchestrator that decides which tool to use. **5. Delivery** Chooses window vs. template, respects rate limits, and logs everything. Status (sent/delivered/read/failed) comes back via webhook and feeds the logic. ## LLM fallback: the day the provider goes down (and it will) If your agent depends on a single LLM provider, it has the availability of the weakest link. Providers go down, get slow, return 529 errors. In production, with customers waiting for a response in seconds, that's unacceptable. I run with a **cascading fallback**: a primary model, and if it fails or blows past the timeout, it automatically drops to the secondary, then the tertiary — from different providers. The customer never knows. The rule is: *no single point of failure in the response*. This also gives me the freedom to optimize cost: a cheaper model for simple intents, a more capable model only when the conversation calls for reasoning. Most messages are "where's my invoice?" — you don't need the top-of-the-line model for that. ## Tools: where the agent stops being chat and becomes a product An agent that only talks is a fancier chatbot. An agent that **acts** is software. The difference is the tools. In my AI call center for ISPs, the agent doesn't "talk about" the duplicate invoice — it **queries the ERP, generates the invoice, and sends the PIX** inside the conversation. It doesn't "explain how to open a ticket" — it **opens** one. That requires connecting the LLM to the business's real APIs (CRM, ERP, payment gateway) via function calling, with rigorous validation of every call. Golden rule: **every tool that changes state in the real world needs explicit confirmation and a log.** The LLM can hallucinate; the tool layer can't. It validates, confirms with the customer when the step is irreversible, and records everything. ## What separates demo from production — the honest summary - **Idempotency:** the same message will arrive twice. Handle it by `message_id`. - **Observability:** if you don't log every decision the agent makes, you can't debug anything. Correlation ID per conversation, from webhook to response. - **Human handoff:** the agent needs to know when to hand off to a human — and hand off with the full context, not dumping the customer back at square one. - **Cost per conversation:** measure it. An out-of-control agent calling the expensive model in a loop burns budget without you seeing it. - **Resilience:** queue, retry, fallback. Production doesn't forgive "oh, the provider went down." ## Start with the problem, not the technology The most common mistake isn't technical. It's building the agent before you know what it solves. I always start with the question: *which conversation, repeated a thousand times a month, is eating up the human team?* That's where AI pays for itself. Duplicate invoices, order status, scheduling, a recurring question. Automate the conversation that's already happening — not the one you imagine will happen. A WhatsApp agent in production isn't an AI project. It's a business product that happens to use AI at its core. Treat it that way and it ships. Treat it like a demo and it stays a demo. --- *I build AI agents and conversational products in production — from diagnosis to deploy. If you have a WhatsApp operation that needs to scale without hiring more people, [reach out](https://www.lucassilva.io).*