Typebot no WhatsApp: como ligar seu fluxo à API de WhatsApp

O que o Typebot faz e o que ele não faz sozinho

O Typebot é bom em desenhar a conversa: perguntas, validação de resposta, variáveis, condições. O que ele não faz é falar com um número conectado por QR Code. A integração de WhatsApp que vem no Typebot é pensada para a plataforma oficial da Meta, configurada com as credenciais da sua conta na Meta.

A D-API também não tem conector nativo para o Typebot. Então, para rodar o fluxo num número da D-API, a conversa passa por um terceiro componente. Ser honesto sobre isso antes de começar evita a frustração de procurar um botão "conectar" que não existe.

A arquitetura: três peças e duas APIs

1. A pessoa escreve no WhatsApp. A D-API dispara o evento messages.received para a URL do seu middleware.
2. O middleware procura se aquele telefone já tem sessão no Typebot. Se não tem, chama POST /api/v1/typebots/SEU_PUBLIC_ID/startChat. Se tem, chama POST /api/v1/sessions/SESSION_ID/continueChat com o texto recebido.
3. O Typebot responde com um array messages (as bolhas do bot) e o input que ele espera em seguida.
4. O middleware envia cada bolha pela D-API, na ordem, e guarda o sessionId do Typebot para a próxima mensagem da mesma pessoa.

No Typebot em nuvem, a base dessas rotas é https://typebot.io/api/v1. Se você hospeda o Typebot, troque pelo seu domínio. O fluxo precisa estar publicado.

O middleware em código

Um exemplo enxuto em Node, com o SDK d-api-sdk para enviar e um Map no lugar do armazenamento. Em produção, troque o Map por Redis ou banco, porque memória do processo se perde no deploy e não funciona com mais de uma instância:

import express from 'express'
import { DApi } from 'd-api-sdk'

const dapi = new DApi({ apiKey: process.env.DAPI_KEY })
const TYPEBOT = 'https://typebot.io/api/v1'
const sessions = new Map() // telefone -> sessionId do Typebot

const app = express()
app.use(express.json())

app.post('/webhook/dapi', async (req, res) => {
  res.sendStatus(200) // responde rápido; o processamento segue abaixo
  const { event, sessionId, data } = req.body
  if (event !== 'messages.received' || data.fromMe || data.is_group) return

  const phone = data.from.jid.split('@')[0]
  const typebotSession = sessions.get(phone)
  const url = typebotSession
    ? `${TYPEBOT}/sessions/${typebotSession}/continueChat`
    : `${TYPEBOT}/typebots/${process.env.TYPEBOT_PUBLIC_ID}/startChat`

  const reply = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      message: { type: 'text', text: data.message },
      textBubbleContentFormat: 'markdown',
    }),
  }).then((r) => r.json())

  if (reply.sessionId) sessions.set(phone, reply.sessionId)

  for (const bubble of reply.messages ?? []) {
    if (bubble.type !== 'text') continue
    await dapi.messages.sendText({ sessionId, to: phone, text: bubble.content.markdown })
  }
})

app.listen(3000)

O pedido de textBubbleContentFormat: 'markdown' faz o Typebot devolver cada bolha como texto simples com marcação, o que é bem mais fácil de repassar do que o formato rico padrão.

O que o exemplo acima ainda não cobre

O código mostra o esqueleto. Um middleware que aguenta uso real resolve também:

• Botões e escolhas: quando o input do Typebot é de escolha, transforme as opções numa lista pela rota /api/v1/interactive/send/list ou em texto numerado. Os detalhes de cada formato estão em botões e listas no WhatsApp.
• Mídia: bolhas de imagem, vídeo ou áudio vão para as rotas de envio de mídia correspondentes, com a URL que o Typebot devolve.
• Fim de fluxo: quando o Typebot não devolve mais input, apague a sessão guardada. Senão, a próxima mensagem daquela pessoa cai num fluxo encerrado.
• Mensagens repetidas: a D-API pode reenviar um webhook quando a sua URL demora ou falha. Guarde o data.id das mensagens já processadas por alguns minutos e ignore duplicatas.
• Passagem para humano: defina uma variável no fluxo que, quando preenchida, faz o middleware parar de chamar o Typebot e encaminhar a conversa ao atendimento.

Quando o bloco HTTP request entra

Dentro do fluxo, o Typebot tem o bloco HTTP request, que chama qualquer API no meio da conversa, com URL, método, corpo com variáveis no formato {{Variavel}} e a opção de salvar a resposta em variáveis. Ele não substitui o middleware, porque não recebe mensagens, mas serve para ações laterais. Um exemplo: quando o lead termina a qualificação, o fluxo avisa o vendedor pelo WhatsApp.

POST https://api.d-api.cloud/api/v1/messages/send/text
Authorization: SUA_API_KEY
Content-Type: application/json

{
  "sessionId": "comercial",
  "to": "5511988887777",
  "text": "Lead qualificado: {{Nome}}, empresa {{Empresa}}, orçamento {{Orcamento}}."
}

Por padrão o bloco espera a resposta por 10 segundos, e o tempo pode ser ajustado nas opções avançadas. Como a chave vai dentro do bloco, restrinja quem pode editar o fluxo.

Middleware próprio ou n8n

Se o seu time já escreve código, o middleware acima vira um serviço pequeno ao lado do seu produto. Se não escreve, dá para montar a mesma ponte no n8n: um Webhook recebe o evento da D-API, um nó HTTP Request chama o Typebot e o node nativo da D-API envia as respostas.

Em qualquer caso, a peça do WhatsApp é a mesma API de WhatsApp da D-API, com conexão isolada e IP próprio por número. Para comparar esse desenho com um bot baseado em modelo de linguagem, veja chatbot de WhatsApp com IA. Para outros usos de automação, a página de API de WhatsApp para automação reúne os caminhos, e o guia de webhook de WhatsApp detalha o payload que o middleware recebe.