--- title: "API e webhooks: o que dá e o que não dá" url: https://ajuda.botconversa.com.br/aula/api-e-webhooks-o-que-da-e-o-que-nao-da section: "API e desenvolvedores" date_modified: 2026-11-09T17:32:28.779139+00:00 language: pt-BR --- # API e webhooks: o que dá e o que não dá ## Resposta rápida O BotConversa tem três jeitos de conversar com outro sistema. A **API REST** deixa o seu sistema criar contatos, enviar mensagens, disparar fluxos e mexer em etiquetas, campos, sequências e campanhas. O **webhook de entrada** (**Automação → Webhooks**) recebe dados de outra ferramenta e age sobre o contato. O **bloco Integração** faz o fluxo chamar o seu sistema no meio da conversa. O que **não** existe: ler mensagens ou o histórico de conversas pela API, criar ou editar fluxos por código e gerenciar modelos de mensagem. Os webhooks têm um teto de **25.000 requisições** por conta, mostrado na própria tela. **Tempo de leitura:** ~7 min**Para quem é:** Desenvolvedor | Quem integra o BotConversa a outro sistema 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](/aula/api-do-botconversa-primeiros-passos), [Configurando webhooks](/aula/configurando-webhooks) e [O bloco Integração](/aula/bloco-integracao). ## 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](/aula/referencia-dos-endpoints-da-api). Para testar sem código, use o [Swagger](https://backend.botconversa.com.br/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](/aula/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](/aula/entendendo-modelos-de-mensagem-templates) 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?](/aula/webhook-nao-esta-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. ## Perguntas frequentes Consigo responder o cliente pelo meu sistema? Sim. Pela API, use `send_message` (texto ou arquivo) ou `send_flow`. Na API Oficial, mensagem livre só chega dentro da janela de 24 horas. Fora dela, dispare um fluxo que comece com um modelo aprovado. Dá para baixar o histórico de conversas pela API? Não. Nenhum endpoint lê mensagens, e o relatório de Contatos não traz as conversas. O histórico fica no Inbox. O webhook de entrada consegue iniciar um fluxo? Sim. Entre as ações do webhook está iniciar um fluxo para o contato que veio na requisição. A API e a aba Webhooks são a mesma coisa? Não. A API fica em `backend.botconversa.com.br/api/v1/webhook` (o nome no caminho é herança) e é chamada pelo seu sistema. A aba Webhooks cria URLs que recebem dados de fora. O limite de 25.000 requisições aparece na aba Webhooks. Qual a diferença entre o webhook de entrada e o bloco Integração? No webhook, o outro sistema avisa o BotConversa. No bloco Integração, o fluxo chama o outro sistema e pode usar a resposta. Antes de abrir chamado sobre integração, teste a mesma chamada no [Swagger](https://backend.botconversa.com.br/swagger/) e guarde a resposta completa. Se funciona lá e falha no seu código, a diferença está na requisição (cabeçalho, barra final ou telefone).