How to build a WhatsApp chatbot: flows, API setup and best practices

What is a WhatsApp chatbot?

A WhatsApp chatbot is software that talks to customers on WhatsApp on a company's behalf. It might tell a customer where their parcel is, confirm an appointment, collect a few details before a support agent takes over, or answer the five questions your team gets a hundred times a week. The customer sees a normal chat with your verified business name; the replies come from your system.

Bots are worth building when conversations are repetitive and the answers live in a system you already have. They are not worth building when every conversation is unique. This guide shows how to plan one, what you need from WhatsApp, how the technical flow works with a short code sample, and the mistakes that turn a helpful bot into a frustrating one. If you are new to the platform, read our introduction to the WhatsApp Business API first.

What you need before you start

How a WhatsApp chatbot works

1. The customer sends a message. It could be free text, a tap on a button or a click on a "chat on WhatsApp" link or ad.
2. WhatsApp posts it to your webhook. The message arrives as a webhook, an HTTPS request to your server, including the sender's number and content. See webhooks.
3. Your logic decides the reply. A rule, a lookup in your system, or a language model chooses the answer.
4. You send the reply by API. Text, an image, a document, buttons or a list, within the 24-hour window.
5. The conversation continues or is handed over. Either the bot keeps going, or it assigns the chat to an agent with the history.

Rule-based bot or language-model bot?

Start with a rule-based flow. It is predictable, cheap and quick to test. Add natural-language understanding only for the steps where users type free text and a button would not do. The platform sends and receives messages the same way in both cases; the difference is the logic in the middle. Many teams build rules in the middle and connect their preferred language service on the edge. Whatever you choose, keep a path to a person.

Design the conversation first

• Pick two or three jobs. "Where is my order?", "Book an appointment", "Return a product". Automate the highest-volume ones first.
• Write the happy path as a short script. Each reply should end with a question or a choice.
• Prefer buttons and lists. Reply buttons suit up to three choices and lists suit longer menus, so nobody has to guess what to type.
• Handle the unexpected. Define what the bot says when it does not understand, and hand over after two misses.
• Keep messages short. One idea per message, plain words, no walls of text.
• Say that it is a bot. People are kinder to a bot that introduces itself and clearly offers a person.

Sample webhook: receive a message and reply

This short Node example receives a message, answers a button choice and sends a reply through the API. It shows the shape of the code; field names follow the illustrative Telnxo format in the API reference, and you would add signature checks and error handling before production.

import express from "express";
const app = express();
app.use(express.json());

app.post("/whatsapp/webhook", async (req, res) => {
  res.sendStatus(200); // acknowledge fast, process after
  const m = req.body;
  if (m.event !== "message.received") return;

  const choice = m.button_id || m.text?.toLowerCase();
  let reply;
  if (choice === "track") {
    const status = await lookupOrder(m.from); // your own system
    reply = { text: `Your order is ${status}.` };
  } else {
    reply = {
      text: "Hi, I'm the Telnxo assistant. What do you need?",
      buttons: [
        { id: "track", title: "Track order" },
        { id: "agent", title: "Talk to an agent" }
      ]
    };
  }
  await fetch("https://api.telnxo.com/v1/messages", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.TELNXO_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ channel: "whatsapp", to: m.from, ...reply })
  });
});

app.listen(3000);

Three habits matter here: reply to the webhook with a 200 at once and do the work afterwards, make processing idempotent because messages can be delivered twice, and verify the webhook signature on every request.

Handover, templates and the 24-hour window

A bot can reply freely for 24 hours after the customer's latest message. After that, it can only send an approved template. This affects design in two places. First, if a conversation is likely to pause, such as a customer who goes to find an order number, plan a template to re-open it. Second, if the bot hands over to an agent, show the agent how much of the window remains. Our guide to templates and the 24-hour window covers the details.

Costs

A chatbot mostly replies inside the window, so many programmes cost far less than they expect. See the pricing page for our rates and the cost calculator to estimate a month.

Measure what matters

• Containment rate. The share of conversations the bot resolves without an agent.
• Handover rate and reason. Which steps send people to a human, and why.
• Drop-off by step. Where users stop answering.
• Customer satisfaction. A one-tap rating at the end of a conversation.
• Quality rating. Blocks and reports lower it; replies raise it.

Fall back to SMS for critical messages that must arrive even if WhatsApp does not, and see support and e-commerce for patterns that fit.

A good chatbot solves the easy questions quickly so that your people can spend time on the hard ones.