Chatbot WhatsApp: Guia Completo da API do WhatsApp Business

Como integrar chatbots, mensagens e chamadas de voz no WhatsApp Business: um número, uma API, sem novas integrações.

O WhatsApp tem 2 bilhões de usuários no mundo. No Brasil, é o canal padrão de comunicação, pessoal e comercial. Se seus clientes estão no WhatsApp e sua empresa não está, você é invisível.

A API do WhatsApp Business (também chamada de WhatsApp Business Platform) permite enviar e receber mensagens e chamadas em escala pela API oficial, não pelo aplicativo WhatsApp Business limitado a um celular. É a base para automação, chatbots e integração com qualquer sistema.

Este guia mostra o que é a API do WhatsApp Business, como ela viabiliza chatbots e automação, e como conectá-la à sua infraestrutura de telefonia e mensagens já existente.

O que é a API do WhatsApp Business?

A API do WhatsApp Business é a interface oficial da Meta para empresas enviarem e receberem mensagens e chamadas do WhatsApp de forma programável. Diferente do aplicativo WhatsApp Business (limitado a um dispositivo e um usuário), a API suporta:

• Conversas simultâneas ilimitadas — atenda milhares de clientes ao mesmo tempo
• Chatbots e automação — agentes de IA, fluxos baseados em templates, respostas automáticas
• Comunicação bidirecional — atendimento em tempo real dentro da janela de 24 horas
• Chamadas de voz — chamadas recebidas e realizadas pelo WhatsApp
• Integração com CRM e helpdesk — arquitetura baseada em webhooks conecta a qualquer sistema

Você não acessa a API diretamente pela Meta. A conexão é feita por meio de um Business Solution Provider (BSP) como a Telnyx, que cuida da integração, do provisionamento de números e da verificação comercial junto à Meta.

Como a API viabiliza chatbots no WhatsApp

A API do WhatsApp Business é o que torna chatbots possíveis nesse canal. Sem ela, você fica restrito ao aplicativo. Com a API, cada mensagem recebida dispara um webhook que seu chatbot pode processar e responder em tempo real.

Chatbot com templates aprovados

Para mensagens iniciadas pela empresa (fora da janela de 24h), a API exige templates aprovados pela Meta para autenticação (códigos OTP), utilidade (atualizações de pedidos), marketing (promoções) e serviço (suporte ao cliente). Seu chatbot envia esses templates automaticamente com base em gatilhos do seu sistema (novo pedido, consulta agendada, carrinho abandonado).

Chatbot com mensagens livres

Dentro da janela de 24 horas após o cliente enviar uma mensagem, a API permite responder com texto livre. É aqui que chatbots com IA brilham: respostas naturais, contexto da conversa e escalonamento para um humano quando necessário. O webhook da API entrega cada mensagem ao seu chatbot, que responde instantaneamente.

Chatbot WhatsApp com IA

Com a Telnyx, o mesmo agente de voz com IA que atende chamadas telefônicas pode atender conversas no WhatsApp. A API unifica mensagens e chamadas no mesmo número. O agente transcreve, interpreta e responde em tempo real, seja por texto ou por chamada de voz dentro do WhatsApp.

API do WhatsApp Business vs. Aplicativo WhatsApp Business

Se você já ultrapassou os limites do aplicativo, é hora de migrar para a API.

Como configurar a API do WhatsApp Business

1. Conecte sua conta WhatsApp Business

Crie ou vincule uma WhatsApp Business Account (WABA) por meio do embedded signup da Meta sem precisar acessar o Meta Business Manager separadamente.

Embedded signup: o que a Meta exige

O embedded signup é um fluxo integrado que permite criar e verificar uma WABA diretamente pelo portal do provedor (como o Mission Control Portal da Telnyx). Durante o processo, a Meta solicita:

• Dados da empresa — CNPJ, razão social, endereço comercial, site e e-mail de contato
• Conta do Facebook Business — você precisa de uma conta ativa no Meta Business Manager; se ainda não tiver, pode criar uma na hora
• Verificação comercial — a Meta confirma que a empresa é legítima. Para isso, pode solicitar documentos como cartão CNPJ, comprovante de endereço e vínculo do solicitante com a empresa. Empresas já verificadas no Meta Business Manager pulam essa etapa
• Número de telefone — um número que não esteja ativo no WhatsApp Consumer ou no aplicativo WhatsApp Business

Prazo de aprovação: a verificação comercial geralmente leva de 2 a 5 dias úteis. Empresas com documentação completa e consistente podem ser aprovadas em menos de 24 horas.

Motivos comuns de rejeição:

• Dados da empresa inconsistentes (CNPJ que não corresponde ao endereço informado)
• Site da empresa sem conteúdo ou com domínio genérico (gmail.com, outlook.com)
• Solicitante sem vínculo comprovado com a empresa
• Empresa em setor de alto risco (criptomoedas, jogos, farmácia) sem documentação adicional

Se a verificação for negada, você pode reenviar com a documentação corrigida. Provedores como a Telnyx oferecem suporte durante todo o processo para minimizar atrasos.

2. Verifique seu número

Registre um número de telefone para o WhatsApp Business. Com a Telnyx, você usa um número existente ou provisiona um novo. A Meta envia um código de verificação para confirmar a propriedade.

3. Comece a enviar mensagens e fazer chamadas

Envie templates de mensagens (para saída), receba mensagens de entrada e faça ou receba chamadas de voz pelo WhatsApp, tudo pelo mesmo número e API.

Recursos principais da API do WhatsApp Business

Templates de mensagens

Formatos pré-aprovados para autenticação (códigos OTP), utilidade (atualizações de pedidos, lembretes de consulta), marketing (promoções, anúncios) e serviço (suporte ao cliente). Os templates precisam de aprovação da Meta, que você envia diretamente pelo portal Telnyx.

Criação e aprovação de templates

Para criar um template, defina o nome, a categoria (autenticação, utilidade, marketing ou serviço), o idioma e o conteúdo do corpo. A Meta analisa cada template antes de aprovar. O processo leva de alguns minutos até 24 horas.

Critérios de aprovação da Meta:

• O conteúdo deve ser relevante para a categoria selecionada (não envie template de marketing como "utilidade")
• Sem spam, engano ou conteúdo sensível (álcool, armas, política)
• Variáveis devem ser usadas de forma que o template faça sentido mesmo com qualquer valor inserido
• Não solicitar dados financeiros completos (número de cartão, CVV)

Recursos dos templates:

• Variáveis — use {{1}}, {{2}} etc. para personalizar dinamicamente (nome do cliente, número do pedido)
• Botões de ação — adicione CTAs como "Visite nosso site" (URL) ou "Ligue agora" (telefone), além de respostas rápidas
• Mídia — templates com imagem, vídeo ou documento anexado para maior engajamento
• Cabeçalho e rodapé — personalize o topo e o final do template com texto ou mídia

Exemplo: enviando um template com variável

Para disparar um template de confirmação de pedido com o nome do cliente e o número do pedido, faça uma chamada POST à API do WhatsApp Business:

Copy
curl -X POST https://api.telnyx.com/v2/messages \
  -H "Authorization: Bearer SEU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5511988887777",
    "type": "template",
    "template": {
      "name": "confirmacao_pedido",
      "language": { "code": "pt_BR" },
      "components": [{
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Maria" },
          { "type": "text", "text": "12345" }
        ]
      }]
    }
  }'

Os valores em parameters substituem {{1}} e {{2}} no corpo do template aprovado. Resultado: "Olá Maria, seu pedido 12345 foi confirmado."

Se um template for rejeitado, você pode editá-lo e reenviar, ou abrir um recurso (appeal) pelo Meta Business Manager se considerar que a rejeição foi incorreta. Boa prática: teste com poucos templates primeiro, valide a aprovação e escale.

Mensagens bidirecionais

Dentro de 24 horas após um cliente te enviar uma mensagem, você pode responder com texto livre. Depois que a janela fecha, use templates aprovados para comunicações outbound. Chatbots gerenciam essa transição automaticamente: mensagens livres durante a janela, templates para reengajamento.

Chamadas no WhatsApp

Faça e receba chamadas de voz para usuários do WhatsApp diretamente pela sua conexão SIP, Voice API ou TeXML existente. A mesma lógica de chamada, em um novo canal. Chamadas no WhatsApp funcionam com agentes de voz com IA: um agente de IA pode atender uma chamada do WhatsApp da mesma forma que atende uma chamada PSTN.

Comprovantes de entrega e leitura

Acompanhe cada mensagem: enviada → entregue → lida. Notificações via webhook mantêm seu sistema atualizado em tempo real para auditoria, SLAs e automação de follow-up.

Webhooks e arquitetura de integração

A API do WhatsApp Business é orientada a eventos. Toda interação — mensagem recebida, status de entrega, leitura — é comunicada via webhook para o seu servidor. O fluxo técnico é:

1. Mensagem chega — o usuário envia uma mensagem pelo WhatsApp
2. Webhook dispara — a Meta (via BSP) envia um POST HTTP para a URL do seu webhook com o payload da mensagem
3. Seu servidor processa — seu backend decodifica o JSON, identifica o remetente, o conteúdo e o contexto da conversa
4. Resposta via API — seu sistema chama a API do WhatsApp Business para enviar a resposta, seja um texto livre (dentro da janela de 24h) ou um template aprovado (fora da janela)

Exemplo de payload recebido pelo webhook:

Quando um cliente envia uma mensagem, a Meta entrega um POST como este ao seu endpoint:

Copy
{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "5511999999999",
          "phone_number_id": "PHONE_NUMBER_ID"
        },
        "contacts": [{
          "profile": { "name": "Maria Silva" },
          "wa_id": "5511988887777"
        }],
        "messages": [{
          "from": "5511988887777",
          "id": "wamid.HBgN...",
          "timestamp": "1730000000",
          "text": { "body": "Olá, qual o status do meu pedido?" },
          "type": "text"
        }]
      }
    }]
  }]
}

Seu backend lê o campo messages[0].text.body para identificar o conteúdo da mensagem e messages[0].from para saber quem enviou. A partir daí, sua lógica de chatbot decide a resposta.

Boas práticas para webhooks:

• Retorne HTTP 200 rapidamente — a Meta espera resposta em até 20 segundos; processe de forma assíncrona se a lógica for pesada
• Implemente fila de mensagens (Redis, SQS) para picos de volume
• Valide assinatura HMAC do webhook para garantir que o payload veio da Meta
• Implemente lógica de reenvio — a Meta reenvia webhooks não confirmados até 3 vezes em 24 horas
• Use o mesmo endpoint para mensagens e status (entregue, lido) para simplificar a lógica

Exemplo: validando a assinatura HMAC

Antes de processar qualquer webhook, confirme que o payload veio mesmo da Meta. O cabeçalho X-Hub-Signature-256 traz um hash HMAC SHA-256 que você recalcula com seu app secret:

Copy
const crypto = require('crypto');

function validarAssinatura(payload, signature, appSecret) {
  const hashEsperado = crypto
    .createHmac('sha256', appSecret)
    .update(payload)
    .digest('hex');

  const assinaturaRecebida = signature.replace('sha256=', '');

  return crypto.timingSafeEqual(
    Buffer.from(hashEsperado),
    Buffer.from(assinaturaRecebida)
  );
}

// No seu handler de webhook:
app.post('/webhook', (req, res) => {
  const assinatura = req.headers['x-hub-signature-256'];
  const payload = JSON.stringify(req.body);

  if (!validarAssinatura(payload, assinatura, process.env.APP_SECRET)) {
    return res.status(401).send('Assinatura inválida');
  }

  // Payload validado, processe a mensagem
  res.status(200).send('OK');
});

Use crypto.timingSafeEqual em vez de comparação direta com === para evitar ataques de timing. Webhooks com assinatura inválida devem ser descartados imediatamente.

Essa arquitetura permite que chatbots, CRMs e sistemas de helpdesk se integrem de forma nativa — cada mensagem é um evento processável por qualquer sistema.

Traga seu próprio número

Se o seu número pode receber um código de verificação, você pode registrá-lo para o WhatsApp Business. Sem precisar trocar de número ou operadora.

Casos de uso

Notificações para clientes

Envie confirmações de pedidos, atualizações de entrega e lembretes de consulta em um canal com mais de 90% de taxa de abertura. O cliente vê o nome comercial verificado e o template com a marca. A API envia automaticamente quando seu sistema dispara o gatilho.

Atendimento com chatbot

Deixe que seus clientes te encontrem no WhatsApp para receber ajuda em tempo real. O chatbot responde com mensagens livres na janela de 24 horas e usa templates aprovados para follow-ups outbound. Escala para um humano quando o cliente precisa. Tudo gerenciado pela mesma API.

Verificação por WhatsApp (OTP)

Envie códigos de verificação pelo WhatsApp em vez de SMS. Custo menor por verificação, maior entregabilidade e sem filtro de operadora, especialmente eficaz no Brasil e na Índia, onde o WhatsApp é o canal de mensagens principal.

Chatbots com IA no WhatsApp

Conecte mensagens do WhatsApp a agentes de voz com IA para atendimento automatizado, agendamento de consultas e qualificação de leads. O mesmo agente que atende chamadas telefônicas pode atender conversas no WhatsApp, a API unifica os dois canais.

Campanhas de marketing

Alcance leads no Brasil, México, Índia, Oriente Médio e Sudeste Asiático com templates de marketing aprovados pela Meta. Mensagens de marketing no WhatsApp têm taxas de abertura acima de 90% — muito superiores a email e SMS.

Operações internas

Helpdesks de TI, linhas de RH e diretórios de funcionários podem funcionar pelo WhatsApp. Agentes de IA atendem consultas internas automaticamente - seja por chamada, seja por mensagem.

Preços da API do WhatsApp Business

O WhatsApp usa um modelo de preço por conversa. Uma "conversa" é uma sessão de 24 horas de mensagens entre uma empresa e um cliente. O preço varia por:

• Categoria da conversa — utilidade, autenticação, marketing ou serviço
• Iniciada pelo cliente vs. pela empresa — conversas iniciadas pelo cliente custam menos
• País — preços variam por mercado

Categorias de conversa e janela de 24 horas

A Meta classifica cada conversa em uma de quatro categorias, e o preço muda conforme a categoria:

Como funciona a janela de 24 horas: quando um cliente envia uma mensagem para sua empresa, abre-se uma janela de 24 horas. Durante essa janela, você pode enviar quantas mensagens livres quiser — sem template, sem custo adicional por mensagem. Tudo conta como uma única conversa. Quando a janela fecha, você só pode iniciar nova comunicação enviando um template aprovado, o que abre uma nova conversa e gera nova cobrança.

Dicas de otimização de custo:

• Incentive o cliente a iniciar a conversa — conversas iniciadas pelo cliente entram na categoria de serviço (custo menor) e abrem a janela de 24 horas para mensagens livres
• Use templates de utilidade em vez de marketing quando possível — um lembrete de consulta é utilidade, não marketing
• Resolva tudo dentro da janela — evite que conversas expirem e precisem ser reabertas com templates outbound
• Automatize com chatbots — respostas rápidas mantêm a conversa ativa e evitam reaberturas

Com a Telnyx, custos de plataforma e taxas da Meta aparecem em uma única fatura. Sem cobranças separadas, sem reconciliação. Chamadas no WhatsApp têm preço por minuto sem taxas de setup ou assinatura mensal.

Por que rodar o WhatsApp Business em infraestrutura de operadora

A maioria dos provedores de WhatsApp Business são apenas camadas de software puro: conectam à Meta, mas não possuem a telefonia subjacente. Isso significa contratos separados para PSTN, SMS e WhatsApp. Analytics separados. Compliance separado. O "Frankenstack".

A Telnyx opera sua própria rede de operadora. Mensagens no WhatsApp, chamadas no WhatsApp, voz PSTN e SMS funcionam no mesmo número e na mesma conexão. Uma stack. Um contrato. Uma API. Isso importa porque:

• Portabilidade de número — seu número do WhatsApp também é seu número de voz e SMS. Sem provisionamento separado.
• Analytics unificado — veja atividade PSTN, SMS e WhatsApp em um dashboard.
• Compliance — SOC 2 Tipo II, HIPAA com BAA, GDPR e PCI-DSS cobrem toda a stack.
• Pronto para IA — agentes de voz com IA, chatbots e automação funcionam em todos os canais sem reconfiguração.

Como começar

1. Crie uma conta Telnyx — portal.telnyx.com
2. Conecte sua WABA — Navegue até WhatsApp → Conectar no Mission Control. Complete o embedded signup da Meta.
3. Verifique seu número — Use um número Telnyx existente ou traga o seu. A Meta envia um código de verificação.
4. Ative mensagens e chamadas — Ative mensagens e chamadas do WhatsApp no seu número. Sem configuração adicional de conexão.
5. Comece a desenvolver — Envie sua primeira mensagem template ou teste um webhook de entrada. Você está no ar.

Leia a documentação de mensagens do WhatsApp ou o guia de setup de chamadas do WhatsApp para passos detalhados de integração.

Perguntas frequentes

A API do WhatsApp Business é grátis?

Não. A Meta cobra por conversa e os provedores cobram taxas de plataforma. A Telnyx inclui tudo em uma única fatura sem assinatura mensal.

Posso usar meu número atual para o WhatsApp Business?

Sim, desde que o número possa receber um código de verificação. Com a Telnyx, você usa o mesmo número para PSTN, SMS e WhatsApp.

Qual a diferença entre API do WhatsApp Business e WhatsApp Business Platform?

São a mesma coisa. "WhatsApp Business Platform" é a marca atual da Meta. "API do WhatsApp Business" é o termo mais usado em comunidades de desenvolvedores e empresas.

Posso fazer e receber chamadas no WhatsApp?

Sim. As chamadas no WhatsApp permitem que empresas façam e recebam chamadas de voz pelo app. Com a Telnyx, chamadas do WhatsApp são roteadas para sua conexão SIP, Voice API ou TeXML existente.

Agentes de IA podem atender conversas no WhatsApp?

Sim. Mensagens e chamadas do WhatsApp podem ser roteadas para agentes de voz com IA para atendimento automatizado, agendamento e suporte — sem mudanças de código no seu fluxo de chamadas existente.

A API do WhatsApp Business funciona com meu sistema de telefonia existente?

Sim. Com a Telnyx, chamadas do WhatsApp são roteadas para sua conexão SIP, Voice API ou TeXML existente. Sem mudanças na infraestrutura.