How We Build a WhatsApp AI Agent, Step by Step
This is the playbook we run every time a business asks for a WhatsApp agent. Three weeks, nine steps, no magic. If you follow it yourself you will end up with something that works; if you want it done, it is what you are paying for.
- Published
Week 1 — understand the conversations
- Export the last 500–2,000 real WhatsApp conversations. Not the ones the owner remembers — all of them. This is the only honest picture of what customers ask.
- Cluster them into message types. Nearly every business lands on 6–12: price enquiry, availability, booking, order status, complaint, location, "are you open", and a long tail. Count each one.
- Decide, per type, what the agent does: answer fully, collect details and hand off, or hand off immediately. Complaints and anything emotional are always immediate hand-off.
- List the systems the agent needs to read or write for the top types — calendar, POS, order system, CRM. Confirm each has an API or a workable export. This list is the real scope.
| Message type | Share | Agent action |
|---|---|---|
| Price / service enquiry | 25 – 35% | Answer from catalogue, offer booking |
| Availability / booking | 20 – 30% | Check calendar, book, confirm |
| Order or appointment status | 10 – 20% | Look up, answer |
| Location / hours | 5 – 10% | Answer with pin and hours |
| Complaint / problem | 5 – 10% | Acknowledge, hand off with summary |
| Everything else | 10 – 20% | Collect details, hand off |
Week 2 — build it and run it in the shadows
- Set up the official WhatsApp Business API on the business’s existing number, with message templates submitted for approval on day one — approval takes days and blocks launch if left late.
- Write the agent’s tools, one per action from step 3: check_availability, book_slot, get_order_status, create_lead, handoff_to_human. Strict input schemas; descriptions written for the model with an example each.
- Write the system prompt last, and keep it short: who the business is, tone, languages, what to do when unsure ("say you will connect them to a person, then call handoff_to_human"). Every rule that can be enforced in code goes in code, not the prompt.
- Build the eval set from the week-1 export: 150+ real conversations with the expected action and, where relevant, the expected tool call. Run it on every change. Target 95%+ on booking and status, 100% on hand-off for complaints.
- Shadow mode: the agent drafts every reply, a staff member approves or edits before it sends. Every edit becomes a new eval case. Run for 5–7 working days.
Week 3 — launch and measure
- Go live on after-hours traffic first, then overflow, then everything — each step gated on the shadow-mode numbers holding.
- Ship the dashboard the owner will actually open: conversations handled, bookings made, hand-offs, and the list of questions the agent could not answer. That last list is the roadmap.
- Weekly for the first month: review hand-offs and misses, add eval cases, adjust tools. Most agents gain 5–10 points of containment in month one from this loop alone.
Total: three weeks, roughly 120–200 engineer-hours, and an agent that answers most messages in under five seconds in the customer’s language. We build these for $4k–$20k depending on integrations, or teach the process in a one-day workshop.
Frequently asked questions
Which model do you use?
A current frontier model for the conversation and tool selection, with adaptive thinking on and a modest effort setting for latency; a cheaper model for simple classification steps. The eval set makes swapping safe.
What about languages?
The eval set must include Hindi, Hinglish and regional-language conversations in the real proportions from the export. That is where bots built on English-only tests fail.
How do you handle spam and abuse?
Rate limits per number, a short-circuit for abusive messages, and a rule that the agent never argues — it hands off or ends politely.
