GoldenrozBook a call

How to build a WhatsApp chatbot on the official API

To build a WhatsApp chatbot you connect a business phone number to Meta's Cloud API, receive incoming messages on a webhook, decide the reply in your own code or with an AI model, and send it back through the API. A production bot also needs a handoff to a person, approved templates for messages outside the 24-hour window, and fallback replies for when the model fails. Bots built on unofficial tools that automate the consumer app violate WhatsApp's terms and get numbers suspended.

A gold sphere connected by thin rods to six small navy spheres.

The architecture in one paragraph

A WhatsApp chatbot is a web service with four parts. A webhook receives messages from Meta. A conversation layer keeps the state of each chat and decides what to do next. An integration layer reads and writes your systems: catalog, orders, CRM, calendar. A sender calls the Cloud API to deliver the reply. The AI model, if there is one, sits inside the conversation layer. It is one component, and the bot must keep working when that component is slow or wrong.

Shai built and runs a production WhatsApp ordering bot on Claude. The steps below follow the order in which that kind of project is built.

Step 1: set up the account

You need a Meta business portfolio, a WhatsApp account under it, and a payment method. Start business verification on day one, because it depends on documents and review time. The background on accounts, verification and messaging limits is in our WhatsApp Business API guide.

Decide who owns the portfolio. It should be a company-controlled admin, with at least two people holding access.

Step 2: choose and register the number

Register a business phone number on the Cloud API. Meta’s documentation says real and virtual numbers are both accepted. Choose the display name carefully, because it is what customers see.

If the number is already in use in the WhatsApp Business app, plan the move before you touch it. Moving a live number affects how the team answers chats today.

Step 3: build the webhook

Meta’s documentation says the platform relies heavily on webhooks. Every incoming message and every delivery status arrives as an HTTP request to your endpoint. Four rules make it reliable:

  • Verify the signature on every request, so nobody else can inject messages.
  • Acknowledge fast. Return a success response immediately and process the message from a queue. Do not call the AI model before answering Meta.
  • Deduplicate. Deliveries are retried, so the same message can arrive more than once. Store message IDs and ignore repeats, or the customer gets two replies or two orders.
  • Handle every type. Users send text, voice notes, images, locations and button taps. Decide what the bot does with each, even if the answer is “I can only read text, here is a person”.

Step 4: design the conversation

Write the conversation before you write code. For each task the bot handles, list what it needs to know, in what order, and what happens when the user goes off script.

WhatsApp gives you interactive elements that reduce typing:

  • Reply buttons and list messages for short, fixed choices.
  • WhatsApp Flows for structured input. Meta describes Flows as a way to build structured interactions, with examples such as collecting details for an insurance quote or capturing which products a customer wants. Use a Flow where free text causes errors: addresses, dates, multi-field forms.
  • Free text for everything else, which is where an AI model earns its place.

A useful split: buttons and Flows for data entry, the model for understanding what the user wants and answering questions.

Step 5: add the AI layer

A scripted bot follows a tree. An AI bot uses a language model to understand the message and write the reply. Most business bots need both: fixed steps for the parts that must never vary, and a model for language.

What the AI layer needs:

  • Instructions that define the bot’s job, tone and limits.
  • Grounding. The model answers from your data, not from memory. For questions, that means retrieval from a knowledge base, explained in what a RAG chatbot is. For orders, it means tools that read the catalog and stock.
  • Tools with limits. Each action the bot can take is a function your code exposes: look up an order, add to cart, book a slot. Your code checks every call. The model proposes, the server decides.
  • A fallback chain. Models time out and providers have outages. The production bot Shai runs uses a model fallback chain, timeouts, retries and deterministic fallback replies, so the customer always gets an answer, even if it is “I could not process that, a person will reply shortly”.
  • Cost and token tracking per conversation, so usage is visible before the invoice arrives.

One rule from Meta’s terms matters here. The platform may not be used to distribute a general-purpose AI assistant. A bot that serves your own customers for your own business function is the normal, permitted case. Keep the bot on its job: it should decline unrelated requests.

When the bot starts taking multi-step actions on its own, it has become an agent, with the extra permission and testing work described in AI agent vs chatbot.

Step 6: build the handoff to a person

Meta’s Business Messaging Policy requires that a business using automation offer “prompt, clear, and direct escalation paths”. Beyond the policy, handoff is what keeps a bot from damaging customer relationships.

A working handoff has:

  • Triggers. The user asks for a person, the bot fails twice in a row, the topic is on a list that always goes to staff (complaints, legal, payments disputes), or the model reports low confidence.
  • Context transfer. The agent sees the whole conversation and what the bot already collected. The customer is never asked to repeat.
  • A clear state. While a person is handling the chat, the bot is silent. When the agent closes the case, the bot resumes.
  • An out-of-hours answer. If no one is available, the bot says so and says when someone will reply.

Step 7: prepare the templates

Free-form replies are allowed only inside the 24-hour customer service window, which opens when the user messages you and resets with each new user message. Anything the bot sends outside that window must be an approved template: order confirmations, delivery updates, appointment reminders, and the “sorry for the delay, here is your answer” message when a handoff takes more than a day.

Templates are reviewed automatically, and Meta notes that review can take up to 24 hours. Each one needs a category: marketing, utility or authentication. Write them early and keep utility templates strictly transactional. You also need recorded opt-in before sending business-initiated messages.

Step 8: test

Test on three levels.

Level What you test How
Plumbing Webhook, deduplication, retries, every message type Automated tests with recorded webhook payloads
Conversation The bot completes each task and answers correctly A fixed set of real or realistic conversations, run on every change
Failure Model timeout, API outage, system of record down, user sends nonsense Forced failures in a staging environment

The conversation test set is the asset that lets you change prompts and models later without guessing. Start it with 30 to 50 cases and add every real failure you find after launch.

Test also with people who do not know the script. They will type things the team never imagined.

Step 9: launch in stages

  1. Internal staff only.
  2. A small share of real customers, with a person reviewing every conversation daily.
  3. Wider rollout once the failure rate and handoff rate are stable.

After launch, watch four things: delivery failures, template status and quality rating, handoff rate, and cost per conversation. Read real transcripts every week. They are the best source of the next improvement.

Why unofficial automation gets numbers banned

There are libraries and browser tools that automate WhatsApp Web or the phone app. They look cheaper because there is no verification and no template review. They are also against the rules. WhatsApp’s Terms of Service prohibit “bulk messaging, auto-messaging, auto-dialing, and the like”, and prohibit using the service through unauthorized automated means. WhatsApp states it may disable or suspend accounts that violate the terms.

For a business, the risk is losing the number that customers have saved. The official API costs more to set up and gives you a sanctioned path, delivery statuses, templates and a number you can keep.

Launch checklist

  • Business portfolio owned by the company, two admins
  • Business verification submitted
  • Webhook verifies signatures, acknowledges immediately, deduplicates
  • Every message type has a defined behavior
  • Model fallback, timeout and a deterministic reply for failures
  • Server-side checks on every tool call
  • Handoff triggers, context transfer and out-of-hours reply
  • Templates approved for every message outside the window
  • Opt-in captured and stored
  • Conversation test set runs on every change
  • Monitoring for delivery failures, template quality and cost

What to do next

Pick one task for the first version, such as order status or booking, and write out the ideal conversation and the three most likely ways it goes wrong. That document is the brief. Our WhatsApp chatbot development service builds on the official Cloud API, in your Meta account, with the WhatsApp Business API integration included. If you need the same assistant on your website or other channels, see AI chatbot development. Goldenroz is independent and is not a Meta Business Partner. Projects start at $25,000 at a fixed price per phase.

Questions buyers ask

How do I create a WhatsApp bot?

Set up a Meta business portfolio and a WhatsApp account, register a business phone number on the Cloud API, host a webhook that receives messages, and write the logic that decides each reply. For anything beyond a menu, add an AI model with access to your catalog or knowledge base, and a handoff to a human agent.

Can I use ChatGPT or Claude in a WhatsApp chatbot?

Yes, as the engine behind your own business bot. Your server receives the WhatsApp message, calls the model through its API with your instructions and data, and sends the reply. Meta's terms prohibit distributing a general-purpose AI assistant over the platform, so the bot must serve your business function, such as support or ordering.

What are WhatsApp Flows?

WhatsApp Flows is Meta's feature for structured interactions inside a chat, such as multi-screen forms. Meta's documentation gives examples like collecting details for a quote or capturing purchase intent. Flows suit steps where typed free text is slow or error-prone, for example an address or a date.

Why do WhatsApp numbers get banned for automation?

WhatsApp's Terms of Service prohibit bulk messaging, auto-messaging and using the service through unauthorized automated means. Tools that drive the consumer app or WhatsApp Web with scripts fall under that. The official Business Platform is the sanctioned route for automation, with opt-in and template rules.

How long does it take to build a WhatsApp chatbot?

It depends on integrations more than on the chat itself. Business verification and template approval add calendar time that code cannot shorten. A bot that answers from a knowledge base is a smaller project than one that takes orders and payments, because each connected system needs its own error handling and tests.

Written by

CTO and technology partner

Shai leads the technology side: business software, SaaS and mobile apps, payments and escrow systems, Postgres security, AI agents built with Claude Code and MCP, and IT and infrastructure projects with senior infrastructure engineers.

Keep reading

Talk to the person who will do the work

One hour, no sales team. You talk to Daniel or Shai, we look at your account or your product, and you leave with a clear next step.

Or send the details

Book a 1-hour consultationWhatsApp us