--- title: "Introdução às integrações" url: https://ajuda.botconversa.com.br/aula/introducao-as-integracoes section: "API e desenvolvedores" date_modified: 2026-09-06T16:42:18.288592+00:00 language: pt-BR --- # Introdução às integrações [Vídeo da aula](https://www.youtube.com/watch?v=Xggsb_cRa_w) ## Resposta rápida O BotConversa tem **quatro formas de conversar com outros sistemas**, e a escolha depende de uma pergunta só: **quem começa?** Se o sistema de fora manda dados para cá, você usa **Webhook** ou **a API**. Se é o BotConversa que vai buscar lá fora, você usa o **bloco de Integração** dentro do fluxo. O **Zapier** serve para os dois lados, sem escrever código. **Tempo de leitura:** ~6 min**Para quem é:** Desenvolvedor | Quem vai contratar um ## Integração ativa e passiva: a única distinção que importa Antes de escolher a ferramenta, decida a direção. Todo o resto decorre disso. - **Integração ativa** — o **BotConversa começa**. Alguém termina um fluxo e você quer gravar esse lead no seu CRM. O BotConversa sai daqui e vai bater na porta do outro sistema. - **Integração passiva** — o **outro sistema começa**. Alguém compra na Hotmart e você quer que o BotConversa cadastre o contato e mande as boas-vindas. O outro sistema vem bater na nossa porta. Muita gente trava aqui: tenta receber um pagamento usando a ferramenta de enviar dados, ou vice-versa. Se você identificar quem começa, a ferramenta certa fica óbvia. ## Qual ferramenta usar? Você quer… Direção Ferramenta Precisa programar? Receber dados de um formulário, checkout ou CRM Passiva **Webhook de entrada** Não — o mapeamento é por tela Cadastrar contatos e disparar fluxos a partir do seu sistema Passiva **API REST** Sim Consultar um sistema no meio da conversa (CEP, boleto, estoque) Ativa **Bloco de Integração** Um pouco — você monta a requisição Ligar a uma ferramenta popular sem código As duas **Zapier** Não ### Webhook de entrada Gera uma URL fixa. Você entrega essa URL ao sistema de fora, ele manda um POST, e você **mapeia por tela** quais campos daquele JSON viram telefone, nome e demais dados do contato. É o caminho de quem não quer escrever código. Passo a passo em [Configurando webhooks](/aula/configurando-webhooks). ### API REST Controle total: criar contato, aplicar etiqueta, enviar mensagem, disparar fluxo, inscrever em sequência ou campanha — tudo comandado pelo seu código. É o caminho de quem tem um sistema próprio. Comece por [API do BotConversa: primeiros passos](/aula/api-do-botconversa-primeiros-passos). ### Bloco de Integração Vive dentro do fluxo. O robô pausa a conversa, chama a URL que você configurou, e pode **usar a resposta nos blocos seguintes** — é assim que o bot responde "seu pedido está a caminho" com dados que ele foi buscar no seu sistema na hora. Detalhes em [Bloco Integração](/aula/bloco-integracao). O bloco de Integração está disponível **apenas no plano PRO** e tem **timeout de 10 segundos**. Se a sua API demorar mais que isso, o fluxo segue pela saída de baixo **sem os dados** — e o cliente recebe a mensagem incompleta sem que nada acuse erro. Vale medir o tempo de resposta do seu endpoint antes de montar o fluxo em cima dele. ### Zapier Intermediário entre o BotConversa e milhares de aplicativos, nos dois sentidos, sem código. Tem chave própria em **Configurações → Geral → Integrações**, separada da chave da API. Veja [Integrando com outras plataformas](/aula/integrando-com-outras-plataformas). ## Como combino as duas direções? As integrações mais úteis usam as duas pontas. Um exemplo completo, do jeito que costuma ser montado na prática: 1. O cliente compra na sua loja. A loja envia um POST para o **webhook de entrada** com nome, telefone e número do pedido — _passiva_. 2. O webhook cria o contato e dispara um fluxo de boas-vindas. 3. No meio do fluxo, o cliente pergunta pelo status. O **bloco de Integração** consulta a sua API de pedidos e traz o código de rastreio — _ativa_. 4. Ao fim do atendimento, o seu sistema usa a **API REST** para aplicar a etiqueta "compra concluída" no contato — _passiva_. ## Dicas - **Comece pelo webhook, mesmo que você saiba programar.** Ele mostra na tela o JSON que chegou, o que economiza horas de adivinhação sobre o formato que o outro sistema realmente envia. - **Teste antes de ligar.** O webhook nasce em Modo Teste e o bloco de Integração tem **Testar Requisição**. Nos dois casos, dá para ver a resposta real antes de qualquer cliente passar por ali. - **Só HTTPS.** Tanto o bloco de Integração quanto a nossa API recusam `http://`. - **Trate a chave de API como senha.** Ela vale pela companhia inteira: quem tem a chave cria contato, dispara fluxo e apaga dado. ## Perguntas frequentes Preciso saber programar para integrar? Não necessariamente. Webhook de entrada e Zapier são configurados por tela. API REST e bloco de Integração pedem alguém que entenda de requisições HTTP. Qual a diferença entre o webhook de entrada e o bloco de Integração? A direção. No webhook de entrada, o outro sistema chama o BotConversa. No bloco de Integração, o BotConversa chama o outro sistema — e pode usar a resposta na conversa. Existe limite de chamadas? O webhook de entrada tem teto de requisições por conta, exibido no topo da aba Webhooks. Acompanhe esse contador antes de ligar um volume grande. O Integrador é a mesma coisa que integração? Não. O Integrador é a área que monta automações entre aplicativos já suportados, sem código. Veja [Conectando com outras ferramentas](/aula/conectando-com-outras-ferramentas-integrador). Meu webhook não dispara. Por onde começo? Confira se ele saiu do Modo Teste e se o consentimento foi marcado. O diagnóstico completo está em [Webhook não está disparando](/aula/webhook-nao-esta-disparando).