API e webhooks: o que dá e o que não dá

Este artigo serve para decidir antes de desenhar a integração. Para pôr a mão na massa, veja API do BotConversa: primeiros passos, Configurando webhooks e O bloco Integração.

Quais são as três peças e para que serve cada uma?

Peça	Quem chama quem	Serve para
API REST	O seu sistema chama o BotConversa, com o cabeçalho API-KEY	Criar e buscar contatos, enviar mensagem, disparar fluxo, aplicar etiqueta, gravar campo, inscrever em sequência ou campanha, gerenciar a equipe
Webhook de entrada	Outra ferramenta (formulário, checkout, CRM) chama uma URL do BotConversa	Receber um lead ou evento e agir sobre o contato daquele telefone
Bloco Integração	O fluxo chama a API do seu sistema	Mandar dados da conversa para fora e usar a resposta no fluxo (status de pedido, CEP, segunda via)

O que dá para fazer

Pela API REST

• Criar contato e achar pelo telefone (POST /subscriber/ e GET /subscriber/get_by_phone/{phone}/).
• Responder pelo seu sistema: enviar texto ou arquivo (send_message) ou disparar um fluxo inteiro (send_flow).
• Organizar o contato: etiquetas, campos personalizados, campos do robô, sequências e campanhas.
• Equipe: listar, criar, alterar e remover membros.

A lista completa, com os 30 endpoints, está em Referência dos endpoints da API. Para testar sem código, use o Swagger.

Pelo webhook de entrada

Primeiro o webhook acha o contato pelo telefone com DDI que veio na requisição e, se você deixar, cria o contato e atualiza o nome. Depois executa as ações que você configurou, na ordem:

• adicionar ou remover etiqueta;
• inscrever ou retirar de uma sequência;
• iniciar um fluxo para o contato;
• enviar uma mensagem (texto, imagem, áudio, vídeo ou documento);
• gravar um valor num campo personalizado.

Para enviar mídia, o valor precisa ser uma URL pública que termina com a extensão do arquivo (.pdf, .png, .mp4…). O plano limita quantos webhooks a companhia pode ter.

Pelo bloco Integração

O fluxo faz uma chamada https (POST, GET, PUT, PATCH ou DELETE) com os dados do contato no corpo, espera até 10 segundos pela resposta e grava o retorno em campos. O bloco Integração é do plano PRO.

O que não dá para fazer

Você quer…	Existe?	O que dá para fazer
Ler as mensagens ou o histórico de um contato pela API	Não. Nenhum endpoint lê mensagens	Ver a conversa no painel: Contatos → abrir o contato → ícone de chat, que abre o Inbox. Para ler conversas com uma IA, use o conector do BotConversa para Claude e ChatGPT
Exportar as conversas	Não. O Baixe Relatório de Contatos exporta dados dos contatos (nome, telefone, etiquetas, campos), não as mensagens	Mesma saída da linha acima
Receber mensagens pela API	Não. A API só recebe chamadas do seu sistema	Pôr um bloco Integração no ponto do fluxo em que a resposta do cliente foi capturada, mandando o campo para o seu sistema
Criar ou editar fluxos por código	Não. A API só dispara fluxos que já existem	Montar o fluxo no construtor e disparar com send_flow
Criar ou gerenciar modelos de mensagem	Não pela API REST	Os modelos vivem na Meta. Veja Entendendo modelos de mensagem
Puxar relatórios e métricas	Não. A API não expõe relatórios	Usar o painel e os relatórios exportáveis

Qual é o limite de requisições?

Na aba Automação → Webhooks, no canto superior direito, aparece "Limite de requisições: X/25000": X é o que a conta já usou e 25.000 é o teto. O contador soma todos os webhooks da conta. Cada webhook também mostra as colunas Requisições do mês e Requisições totais, para você ver qual deles consome mais.

Webhook em Modo Teste não executa ações reais; ativo, ele passa a processar as requisições e a contar contra o limite. Se a sua integração vai mandar volume alto, fale com o suporte antes de subir.

Erros comuns

• Mensagem enviada pela API ou pelo webhook que nunca chega (API Oficial). Mensagem livre só é entregue dentro da janela de 24 horas, e a requisição responde sucesso mesmo assim. Um contato que o webhook acabou de criar não tem janela aberta: use a ação de iniciar um fluxo cujo primeiro bloco envia um modelo aprovado.
• Telefone sem DDI. O webhook e a API precisam do número com o código do país (55 no Brasil). Se o seu sistema manda DDI e número em campos separados, combine os dois.
• Webhook parado em Modo Teste. É a causa mais comum de "não dispara". Veja Por que meu webhook não está disparando?
• Chave errada. A chave da API fica no bloco API de Configurações → Geral → Integrações, e não é a mesma do bloco Zapier. A errada devolve 401.
• URL de mídia sem extensão. Links com parâmetros no fim ou rotas dinâmicas podem falhar, porque o WhatsApp identifica o tipo de mídia pela extensão.