Criar conta
← Blog

·

Typebot com a API oficial do WhatsApp: como configurar

Atualizado em 25/10/2026

O Typebot tem integração nativa com a API oficial do WhatsApp: você conecta o seu próprio app da Meta e o seu número na aba Share do bot, e o fluxo passa a responder as mensagens recebidas. O Typebot não fornece números nem cobra mensagens da Meta; ele funciona no modelo “traga seu próprio app da Meta”. No WhatsApp, o bot tem limites que não existem na versão web, como no máximo 3 botões por mensagem, e só pode mandar mensagens livres dentro da janela de 24 horas aberta pelo cliente.

Este guia mostra os pré-requisitos, a configuração, os limites que mudam o desenho do fluxo e uma alternativa via API de chat do Typebot para quem usa um provedor da API do WhatsApp.

Como a integração do Typebot com o WhatsApp funciona

Segundo a documentação do Typebot, a integração conecta o bot à sua WhatsApp Business Platform, o serviço oficial da Meta. O fluxo é este:

  1. O cliente manda mensagem para o seu número.
  2. A Meta envia o evento para o webhook do Typebot.
  3. O Typebot executa o fluxo e responde pela Cloud API, usando as credenciais do seu app.

Você pode ligar quantos números quiser e até vários bots no mesmo número, usando uma condição de início (Start bot condition) em cada bot para decidir qual deles atende a conversa.

Pré-requisitos na Meta

O Typebot descreve os passos para criar o app da Meta:

  1. Crie (ou use) um portfólio empresarial em business.facebook.com. A Meta pode restringir portfólios recém-criados até você verificar sua identidade.
  2. Em developers.facebook.com/apps, crie um app, escolha Other e o tipo Business, vincule ao portfólio e ative o produto WhatsApp.
  3. Siga as instruções da aba Share do bot para conectar o app ao Typebot.

Para produção, use um token que não expira. A configuração de self-hosting do Typebot, por exemplo, pede um token de usuário do sistema com expiração Never e as permissões whatsapp_business_messaging e whatsapp_business_management. O passo a passo está no guia de token permanente com usuário do sistema.

Também vale ter claro como funciona o acesso à plataforma como um todo (portfólio, WABA, número, verificação): veja como conseguir acesso à API do WhatsApp e o guia da API oficial do WhatsApp.

Configurando o bot no WhatsApp

Testar antes de publicar

No editor, clique em Test e troque o ambiente para WhatsApp. O Typebot envia a mensagem inicial de pré-visualização para o número que você digitar.

Uma armadilha comum no Brasil: o Typebot avisa que o número digitado precisa ser exatamente o que aparece no perfil do seu WhatsApp. Há números brasileiros que aparecem com 8 dígitos e outros com 9 depois do DDD; se você digitar a versão diferente, recebe a primeira mensagem, mas o bot não responde às seguintes.

Opções da integração

Em Configure integration:

OpçãoO que faz
Session expiration timeoutHoras sem interação (de 0 a 48, padrão 4) até a sessão expirar. Depois disso, uma nova mensagem do cliente começa uma conversa nova
Start bot conditionCondição avaliada na primeira mensagem. Se não for atendida, o bot não é acionado

Para capturar dados do contato, use um bloco Set variable com os valores de sistema do WhatsApp para nome e telefone. Para pedir a localização, um bloco de texto simples recebe a posição enviada pelo cliente no formato <LAT>, <LONG>.

Limites do Typebot no WhatsApp

A documentação do Typebot lista o que muda em relação ao bot web:

LimiteEfeito no fluxo
GIF e SVG não são exibidosUse JPEG ou PNG
Só vídeos .mp4Converta outros formatos antes
No máximo 3 botões por mensagemO Typebot divide as opções extras em mensagens “…” adicionais
Cards com no máximo 3 botões por cardSimplifique os cards
Texto do botão com até 20 caracteresO excedente é cortado; escreva rótulos curtos
Blocos incompatíveis são ignoradosPagamento, Chatwoot, Google Analytics, Meta Pixel, Cal.com e Script ou Set Variable com Execute on client

Esses números vêm da própria Cloud API: as mensagens com botões de resposta aceitam até 3 botões com título de até 20 caracteres. Para mais opções, a API oferece a mensagem de lista, com até 10 linhas de até 24 caracteres. Detalhes no artigo sobre mensagens interativas.

Janela de 24 horas: o limite que o fluxo não vê

O editor do Typebot permite tempos de espera longos e sessões de até 48 horas, mas a regra da Meta vale por cima: mensagens livres (texto, imagem, botões) só podem ser enviadas até 24 horas depois da última mensagem do cliente. Veja janela de 24 horas.

Na prática:

  • Respostas imediatas funcionam sempre, porque o cliente acabou de escrever.
  • Blocos Wait longos (por exemplo, “esperar 2 dias e perguntar se gostou”) falham se o cliente não escreveu nesse meio-tempo.
  • Retomar contato depois da janela exige um template aprovado. Planeje o reengajamento com templates, enviados pelo seu sistema, e use o Typebot para conduzir a conversa quando o cliente responder.

Número que já está no app WhatsApp Business

O Typebot recomenda um número dedicado. A documentação explica que registrar o número na plataforma bloqueia o uso dele no app comum, e que, para migrar um número do app WhatsApp Business, é preciso apagar a conta no app; o número fica liberado após cerca de 24 horas. O passo a passo está em como liberar um número para a API.

A Meta também oferece a coexistência, em que o mesmo número fica no app e na API ao mesmo tempo. Ela depende de o número ser conectado por um fluxo de cadastro que suporte esse modo; veja coexistência no WhatsApp.

Custos

O Typebot cobra o plano dele; as mensagens são cobradas pela Meta na sua conta. Atenção: o FAQ do Typebot fala em “1.000 conversas de serviço grátis por mês”, termo do modelo antigo. Desde 1º de julho de 2025, a Meta cobra por mensagem entregue, e não por conversa. As respostas livres de um chatbot dentro da janela de atendimento são mensagens de serviço: cada número tem 1.000 mensagens de serviço entregues grátis por mês, e, desde 1º de outubro de 2026, a Meta cobra a partir da 1.001ª, pela tarifa publicada. Um bot que manda várias bolhas por resposta consome essa cota mais rápido, então vale juntar textos curtos numa só mensagem. Templates usados para iniciar conversas são cobrados conforme a categoria; veja preço da API do WhatsApp no Brasil.

Alternativa: Typebot via API de chat + provedor da API

A integração nativa fala direto com a Graph API da Meta. Se você usa um provedor da API do WhatsApp, quer centralizar o webhook num sistema seu ou precisa misturar bot e atendimento humano, o Typebot oferece um caminho documentado para integrar com apps de mensagens via API HTTP:

  1. Seu servidor recebe o webhook do WhatsApp.
  2. Na primeira mensagem do contato, chama startChat e guarda o sessionId junto do wa_id.
  3. Nas próximas, chama continueChat com o texto do cliente.
  4. Converte o array messages (e o input, quando houver) em mensagens do WhatsApp.

Exemplo em Node.js usando a Vectalk para enviar:

const TYPEBOT = 'https://typebot.co/api/v1'; // ou a URL do seu viewer self-hosted
const PUBLIC_ID = process.env.TYPEBOT_PUBLIC_ID;
const VECTALK = 'https://apis.vectalk.com.br/api/messages';
const sessoes = new Map(); // em produção, use Redis ou banco

async function falarComTypebot(waId, texto) {
  const corpo = { message: { type: 'text', text: texto }, textBubbleContentFormat: 'markdown' };
  const sessionId = sessoes.get(waId);
  if (sessionId) {
    const r = await fetch(`${TYPEBOT}/sessions/${sessionId}/continueChat`, {
      method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(corpo),
    });
    if (r.status !== 404) return r.json();
    sessoes.delete(waId); // sessão expirou: começa outra
  }
  const r = await fetch(`${TYPEBOT}/typebots/${PUBLIC_ID}/startChat`, {
    method: 'POST', headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ textBubbleContentFormat: 'markdown' }),
  });
  const dados = await r.json();
  sessoes.set(waId, dados.sessionId);
  return dados;
}

async function enviar(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 tratarMensagem(msg) {
  const texto = msg.text?.body ?? msg.interactive?.button_reply?.title ?? msg.interactive?.list_reply?.title ?? '';
  const resposta = await falarComTypebot(msg.from, texto);

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

  const opcoes = resposta.input?.type === 'choice input' ? resposta.input.items.map((i) => i.content) : [];
  if (opcoes.length && opcoes.length <= 3) {
    await enviar({
      to: msg.from, type: 'interactive',
      interactive: {
        type: 'button', body: { text: 'Escolha uma opção:' },
        action: { buttons: opcoes.map((t, n) => ({ type: 'reply', reply: { id: `op${n}`, title: t.slice(0, 20) } })) },
      },
    });
  } else if (opcoes.length) {
    await enviar({
      to: msg.from, type: 'interactive',
      interactive: {
        type: 'list', body: { text: 'Escolha uma opção:' },
        action: { button: 'Ver opções', sections: [{ title: 'Opções', rows: opcoes.slice(0, 10).map((t, n) => ({ id: `op${n}`, title: t.slice(0, 24) })) }] },
      },
    });
  }
}

A função tratarMensagem é chamada pelo worker que consome o webhook, como no guia de webhooks da API do WhatsApp. Esse caminho dá mais trabalho, mas permite pausar o bot quando um atendente assume, registrar tudo no seu banco e usar o mesmo número com outros sistemas. Se você prefere montar o fluxo numa ferramenta de automação, veja também n8n com a API oficial.

Como fazer com a Vectalk

A integração nativa do Typebot pede um app da Meta seu e chama a Graph API diretamente. Com a Vectalk, use o caminho da API de chat:

  1. Registre a URL do seu servidor com POST https://apis.vectalk.com.br/api/webhooks (instance_id, url, name).
  2. No worker, chame o Typebot como no exemplo acima.
  3. Envie as respostas com POST https://apis.vectalk.com.br/api/messages, que aceita texto, imagem, botões e lista no mesmo formato da Cloud API.

Os eventos chegam com o payload da Meta, e você pode registrar várias URLs por instância. O custo das mensagens vem na fatura da Vectalk, sem cartão na Meta, e a coexistência permite manter o número no app WhatsApp Business. Crie sua conta em apps.vectalk.com.br/register ou veja a documentação.

Perguntas frequentes

O Typebot fornece o número de WhatsApp?

Não. O Typebot funciona com o seu próprio app da Meta e o seu número. Ele só executa o fluxo.

Por que meu Typebot não responde depois de publicado?

As causas que a documentação do Typebot aponta: o bot não funciona no modo de teste, o número ainda está em uso no app WhatsApp Business, uma condição de início que a primeira mensagem não atende ou, com número de teste da Meta, o seu celular fora da lista de números permitidos. Reconfigurar o número no Typebot, lendo as instruções com atenção, também está entre as soluções sugeridas.

Posso ter mais de um Typebot no mesmo número?

Sim. Use uma condição de início em cada bot para definir qual deles atende cada conversa.

O Typebot consegue mandar mensagem para quem não falou comigo?

Fora da janela de 24 horas, a Meta só aceita templates aprovados. Planeje o primeiro contato com um template enviado pelo seu sistema e deixe o Typebot conduzir a conversa depois que o cliente responder.

Dá para usar o Typebot com WhatsApp por QR Code?

Integrações por QR Code dependem de APIs não oficiais, que contrariam os Termos de Serviço do WhatsApp. A integração do Typebot usa a plataforma oficial da Meta. Veja API oficial x não oficial.

Fontes oficiais consultadas em 25/10/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: Preços, Documentação da Vectalk.

Integre o WhatsApp oficial ao seu sistema

A Vectalk entrega a Cloud API da Meta com os mesmos payloads e webhooks, um token para todas as contas e documentação completa.

Criar conta grátis
Ler a documentação