Typebot with the official WhatsApp Business API: how to set it up

Updated on October 25, 2026

Typebot has a native integration with the official WhatsApp Business API: you connect your own Meta app and phone number in the bot’s Share tab, and the flow starts answering incoming messages. Typebot doesn’t provide numbers or bill Meta’s messages; it works on a “bring your own Meta app” model. On WhatsApp, the bot has limits that don’t exist on the web version, such as a maximum of 3 buttons per message, and it can only send free-form messages inside the 24-hour window opened by the customer.

This guide covers the prerequisites, the setup, the limits that change how you design the flow, and an alternative through Typebot’s chat API for teams using a WhatsApp API provider.

How Typebot’s WhatsApp integration works

According to Typebot’s documentation, the integration connects the bot to your own WhatsApp Business Platform, Meta’s official service. The flow is:

1. The customer messages your number.
2. Meta sends the event to Typebot’s webhook.
3. Typebot runs the flow and replies through the Cloud API, using your app’s credentials.

You can connect as many numbers as you like, and even several bots to the same number, using a Start bot condition on each bot to decide which one handles the conversation.

Prerequisites on Meta

Typebot describes the steps to create the Meta app:

1. Create (or use) a business portfolio at business.facebook.com. Meta may restrict newly created portfolios until you verify your identity.
2. At developers.facebook.com/apps, create an app, choose Other and the Business type, link it to the portfolio and enable the WhatsApp product.
3. Follow the instructions in the bot’s Share tab to connect the app to Typebot.

For production, use a token that doesn’t expire. Typebot’s self-hosting configuration, for example, asks for a system user token with expiration set to Never and the whatsapp_business_messaging and whatsapp_business_management permissions. The full walkthrough is in the permanent system user token guide.

Want to try it while you read? Create a Vectalk account and send your first message through the official API. Create free account →

Setting up the bot on WhatsApp

Test before publishing

In the editor, click Test and switch the runtime to WhatsApp. Typebot sends the initial preview message to the number you type.

A common pitfall: Typebot warns that the number you type must match exactly what appears in your WhatsApp profile settings. In Brazil, for example, some numbers show up with 8 digits and others with 9 after the area code; if you type the other version, you receive the first message but the bot doesn’t answer after that.

Integration options

Under Configure integration:

Option	What it does
Session expiration timeout	Hours without interaction (0 to 48, default 4) before the session expires. After that, a new customer message starts a new chat
Start bot condition	Condition evaluated on the first message. If it isn’t met, the bot isn’t triggered

To capture contact data, use a Set variable block with WhatsApp’s system values for name and phone number. To ask for a location, a plain text input block receives the position the customer shares in the format <LAT>, <LONG>.

Typebot limits on WhatsApp

Typebot’s documentation lists what changes compared to the web bot:

Limit	Effect on the flow
GIF and SVG aren’t displayed	Use JPEG or PNG
Only .mp4 videos	Convert other formats first
At most 3 buttons per message	Typebot splits extra options into additional “…” messages
Cards with at most 3 buttons per card	Simplify cards
Button text up to 20 characters	Longer text is truncated; write short labels
Incompatible blocks are skipped	Payment, Chatwoot, Google Analytics, Meta Pixel, Cal.com, and Script or Set Variable with Execute on client

These numbers come from the Cloud API itself: reply button messages accept up to 3 buttons with titles of up to 20 characters. For more options, the API offers list messages, with up to 10 rows of up to 24 characters.

The 24-hour window: the limit the flow doesn’t see

Typebot’s editor allows long waits and sessions of up to 48 hours, but Meta’s rule sits on top: free-form messages (text, images, buttons) can only be sent up to 24 hours after the customer’s last message.

In practice:

• Immediate replies always work, because the customer just wrote.
• Long Wait blocks (for example, “wait 2 days and ask if they liked it”) fail if the customer hasn’t written in the meantime.
• Re-engaging after the window requires an approved template. Plan re-engagement with templates sent by your own system, and let Typebot run the conversation once the customer replies.

A number already on the WhatsApp Business app

Typebot recommends a dedicated number. Its docs explain that registering the number on the platform blocks it from regular app use, and that to migrate a number from the WhatsApp Business app you must delete the account in the app; the number is released after about 24 hours. Step by step in how to free up a number for the API.

Meta also offers coexistence, where the same number stays on the app and the API at the same time. It depends on the number being connected through a signup flow that supports this mode; see what syncs in WhatsApp coexistence.

Costs

Typebot’s plan is separate; messages are billed by Meta on your account. Note: Typebot’s FAQ mentions “1,000 free service conversations per month”, a term from the old model. Since July 1, 2025, Meta charges per delivered message rather than per conversation. A chatbot’s free-form replies inside the customer service window are service messages: each phone number gets 1,000 free delivered service messages per month, and since October 1, 2026, Meta charges from the 1,001st on, at the published rate. A bot that sends several bubbles per reply burns through that allowance faster, so it’s worth merging short texts into a single message. Templates used to start conversations are billed by category; see how much a WhatsApp campaign costs.

Alternative: Typebot via the chat API + an API provider

The native integration talks directly to Meta’s Graph API. If you use a WhatsApp API provider, want to centralize the webhook in your own system or need to mix the bot with human agents, Typebot documents a way to integrate with messaging apps via the HTTP API:

1. Your server receives the WhatsApp webhook.
2. On a contact’s first message, it calls startChat and stores the sessionId next to the wa_id.
3. On later messages, it calls continueChat with the customer’s text.
4. It turns the messages array (and the input, when present) into WhatsApp messages.

Node.js example using Vectalk to send:

const TYPEBOT = 'https://typebot.co/api/v1'; // or your self-hosted viewer URL
const PUBLIC_ID = process.env.TYPEBOT_PUBLIC_ID;
const VECTALK = 'https://apis.vectalk.com.br/api/messages';
const sessions = new Map(); // use Redis or a database in production

async function talkToTypebot(waId, text) {
  const body = { message: { type: 'text', text }, textBubbleContentFormat: 'markdown' };
  const sessionId = sessions.get(waId);
  if (sessionId) {
    const r = await fetch(`${TYPEBOT}/sessions/${sessionId}/continueChat`, {
      method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body),
    });
    if (r.status !== 404) return r.json();
    sessions.delete(waId); // session expired: start a new one
  }
  const r = await fetch(`${TYPEBOT}/typebots/${PUBLIC_ID}/startChat`, {
    method: 'POST', headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ textBubbleContentFormat: 'markdown' }),
  });
  const data = await r.json();
  sessions.set(waId, data.sessionId);
  return data;
}

async function send(payload) {
  await fetch(VECTALK, {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.VECTALK_TOKEN}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ messaging_product: 'whatsapp', ...payload }),
  });
}

export async function handleMessage(msg) {
  const text = msg.text?.body ?? msg.interactive?.button_reply?.title ?? msg.interactive?.list_reply?.title ?? '';
  const reply = await talkToTypebot(msg.from, text);

  for (const m of reply.messages ?? []) {
    if (m.type === 'text') await send({ to: msg.from, type: 'text', text: { body: m.content.markdown } });
    if (m.type === 'image') await send({ to: msg.from, type: 'image', image: { link: m.content.url } });
  }

  const options = reply.input?.type === 'choice input' ? reply.input.items.map((i) => i.content) : [];
  if (options.length && options.length <= 3) {
    await send({
      to: msg.from, type: 'interactive',
      interactive: {
        type: 'button', body: { text: 'Choose an option:' },
        action: { buttons: options.map((t, n) => ({ type: 'reply', reply: { id: `op${n}`, title: t.slice(0, 20) } })) },
      },
    });
  } else if (options.length) {
    await send({
      to: msg.from, type: 'interactive',
      interactive: {
        type: 'list', body: { text: 'Choose an option:' },
        action: { button: 'See options', sections: [{ title: 'Options', rows: options.slice(0, 10).map((t, n) => ({ id: `op${n}`, title: t.slice(0, 24) })) }] },
      },
    });
  }
}

handleMessage is called by the worker that consumes the webhook queue. This route takes more work, but it lets you pause the bot when an agent takes over, log everything in your own database and use the same number with other systems. If you’d rather build the flow in an automation tool, see n8n with the official API.

How to do it with Vectalk

Typebot’s native integration requires your own Meta app and calls the Graph API directly. With Vectalk, use the chat API route:

1. Register your server’s URL with POST https://apis.vectalk.com.br/api/webhooks (instance_id, url, name).
2. In the worker, call Typebot as in the example above.
3. Send replies with POST https://apis.vectalk.com.br/api/messages, which accepts text, images, buttons and lists in the same format as the Cloud API.

Events arrive with Meta’s payload, and you can register several URLs per instance. Message costs come on your Vectalk invoice, with no card at Meta, and coexistence lets you keep the number on the WhatsApp Business app. Create your account at apps.vectalk.com.br/register or read the docs (in Portuguese).

Frequently asked questions

Does Typebot provide the WhatsApp number?

No. Typebot works with your own Meta app and your own number. It only runs the flow.

Why doesn’t my Typebot reply after publishing?

The causes Typebot’s docs point to: the bot doesn’t work in test mode, the number is still in use on the WhatsApp Business app, a start condition the first message doesn’t meet or, with a Meta test number, your phone not being on the list of allowed numbers. Reconfiguring the number in Typebot, following the instructions carefully, is also among the suggested fixes.

Can I have more than one Typebot on the same number?

Yes. Use a start condition on each bot to decide which one handles each conversation.

Can Typebot message someone who hasn’t contacted me?

Outside the 24-hour window, Meta only accepts approved templates. Plan the first contact with a template sent by your own system and let Typebot run the conversation after the customer replies.

Can I use Typebot with WhatsApp via QR code?

QR code integrations rely on unofficial APIs, which go against WhatsApp’s Terms of Service. Typebot’s integration uses Meta’s official platform. See official vs. unofficial API.

---

Official sources consulted on October 25, 2026: Typebot: WhatsApp, Typebot: Create a WhatsApp Meta app, Typebot: Self-hosting configuration, Typebot: Integrate with external messaging apps, Typebot: Start chat, Meta: Interactive reply buttons, Meta: Interactive list messages, Meta: Pricing, Vectalk docs.