Tipos de bloco: O bloco Integração

Ao final desta aula você vai saber montar uma chamada de API dentro do fluxo, enviar os dados do contato, ler o que o outro sistema devolveu e responder ao cliente com essa informação, tudo sem ninguém copiar e colar nada.

Como o bloco Integração funciona?

Pense no bloco como um mensageiro. Quando o contato chega nesse ponto do fluxo, o BotConversa:

1. Monta um pedido (a requisição) com o endereço da API, o método, os headers e o corpo que você configurou, já com os dados daquele contato no lugar das variáveis.
2. Envia o pedido ao outro sistema.
3. Recebe a resposta, normalmente um JSON, e grava os valores que você escolheu em campos do contato.
4. Segue o fluxo pela saída correspondente, e os blocos seguintes já podem usar esses campos.

Um exemplo: o cliente digita o número do pedido, o bloco pergunta ao sistema da loja qual é o status, guarda "Em transporte" no campo status_pedido e a próxima mensagem diz "Seu pedido está {status_pedido}".

Regra	O que significa na prática
Só https	A URL precisa começar com https://. Endereços http:// são recusados no próprio editor.
Espera de até 10 segundos	Na saída Em resposta com sucesso, se a API não responder nesse prazo, o fluxo não recebe os dados.
Uma integração por bloco	Cada bloco Integração faz uma chamada. Precisa de duas? Use dois blocos em sequência.
Plano PRO	O bloco Integração não faz parte do plano Starter.

Quais tipos de integração o bloco oferece?

Ao adicionar o bloco pelo botão + do construtor, o painel Adicionar método de integração mostra cinco opções. Esta aula foca na de Webhook, que é a que liga o fluxo a qualquer sistema com API.

Opção	Para que serve
Adicionar Integração de Webhook	Chama a API de qualquer sistema (CRM, ERP, loja, n8n, Make, sistema próprio) e pode usar a resposta no fluxo. É o foco desta aula.
Adicionar Evento do Integrador	Dispara uma automação montada no Integrador do BotConversa.
Adicionar Integração do Zapier	Envia os dados para um Zap.
Adicionar Google Sheets	Grava linhas em uma planilha do Google.
Adicionar integração com RD Station	Envia o contato para o RD Station.

As quatro últimas são conexões prontas, sem configuração técnica. Veja Integrando com outras plataformas.

O que ter em mãos antes de começar?

• A documentação da API do sistema que você quer chamar. Dela você tira o endereço (URL), o método, o formato do corpo e como autenticar (normalmente um token).
• Um exemplo de resposta da API, para saber em que "caminho" do JSON está a informação que interessa.
• Os campos personalizados onde a resposta vai ser guardada, já criados e do tipo certo (texto, número ou data). Veja Criando campos personalizados.
• Os dados do contato que a API precisa (CPF, número do pedido, e-mail), já salvos em campos. Para perguntar e salvar, veja Capturando respostas do cliente.

Passo a passo: como configurar uma Integração com API/Webhook

Passo 1: Adicione o bloco

No construtor do fluxo, clique em + e escolha Integração. No painel que abre à esquerda, clique em Adicionar Integração de Webhook. O bloco passa a mostrar Integração com API/Webhook; clique em Clique aqui para editar esta integração para abrir a janela Editar a requisição.

Passo 2: Escolha o método, cole a URL e adicione os headers

Em Tipo de Requisição, escolha o método que a documentação da API pede. Em URL da Requisição, cole o endereço completo, começando por https://.

Método	Uso mais comum
POST	Enviar dados: criar um lead, abrir um pedido, registrar um agendamento. É o padrão do editor.
GET	Buscar dados: consultar um status, um saldo, um endereço.
PUT / PATCH	Atualizar um registro que já existe (PUT troca tudo; PATCH só o que você mandar).
DELETE	Remover um registro.

Na aba Headers, clique em Adicionar um header para esta requisição e preencha Key e Value. Os dois mais comuns são Authorization (com o token que a API exige, por exemplo Bearer seu-token) e Content-Type: application/json. Para mais de um header, use Adicione o header da requisição; a lixeira ao lado remove a linha.

Passo 3: Monte o corpo com os dados do contato

A aba Corpo define o JSON que vai para a API. Ela tem dois lados que mostram a mesma coisa:

• JSON pronto: cole o JSON de exemplo da documentação da API e troque os valores pelas variáveis do contato. É o caminho mais rápido.
• Entrada manual: monte o JSON clicando. O + ao lado de "root" cria uma chave; clique no valor (aparece NULL) para preenchê-lo.

As variáveis seguem o formato {nome-do-campo}. Pela Entrada manual, no campo Valor, o botão { } abre a lista de campos, separada em Campos do Sistema (como {nome-completo}, {primeiro-nome}, {telefone}, {email}, {cpf}), Campos do Usuário (os seus campos personalizados) e Campos do Robô. Depois clique em Criar Chave.

Se o valor parecer um número, aparece a pergunta "Is número ?": confirme se a API espera um número (10) e não um texto ("10"). A documentação da API diz qual dos dois.

Passo 4: Teste a requisição e confira a resposta

Clique em Testar Requisição. O BotConversa faz a chamada na hora e mostra o que voltou na aba Resposta. É essa resposta que você vai usar no próximo passo para escolher o que guardar.

Importante: no teste não existe um contato real, então as variáveis vão como texto: a API recebe literalmente {telefone}, e não o número. Se a API valida o formato (CPF, telefone, e-mail), o teste pode falhar mesmo com tudo certo. Para testar, troque temporariamente a variável por um valor real de exemplo, teste, e depois volte a variável.

Se aparecer "Opa, erro de servidor" embaixo da URL, a chamada falhou (endereço errado, API fora do ar, token inválido ou dado recusado pela API). Enquanto o erro estiver na tela o botão Salvar fica desabilitado; corrija a URL e teste de novo.

Passo 5: Guarde a resposta em campos (Mapeamento de resposta)

Na aba Mapeamento de resposta, clique em Escolher campo do usuário para mapear resposta (ou Novo campo para mapear, se já houver uma linha). Em cada linha:

• No campo JSONPath, escreva o caminho da informação dentro da resposta, em notação de pontos.
• Em Selecionar campo personalizado, escolha o campo do contato (ou do robô) que vai receber o valor.

Como escrever o caminho:

Se a resposta for assim	Para pegar	Escreva no JSONPath
{"status": "pago"}	pago	status
{"pedido": {"status": "enviado"}}	enviado	pedido.status
{"data": [{"user": {"name": "Ana"}}]}	Ana (o primeiro item da lista)	data[0].user.name

O tipo do campo precisa combinar com o dado: um valor como "R$ 49,90" não entra em um campo do tipo número. Quando houver dúvida, use um campo de texto.

Passo 6: Salve e ligue as saídas do bloco

Clique em Salvar. O bloco passa a mostrar a URL configurada e duas saídas. Ligue a que faz sentido para o seu caso ao próximo bloco.

Passo 7: Teste com um contato de verdade

Dispare o fluxo para um contato de teste (palavra-chave, botão ou Pré-visualização) e confira se a mensagem seguinte veio com os dados certos. Para ver o que foi enviado e o que voltou em cada execução, clique em Ver todos os logs na janela do bloco, ou vá em Configurações → Registros. Os testes do editor não aparecem lá; só as execuções reais do fluxo.

Qual saída usar: Em resposta com sucesso ou Continuar sem esperar resposta?

	Em resposta com sucesso	Continuar sem esperar resposta
Quando segue	Depois que a API responde com sucesso, em até 10 segundos	Na hora, sem esperar a API
Dados da resposta	Já gravados nos campos do mapeamento	Ainda não disponíveis no bloco seguinte
Use para	Consultas: status de pedido, saldo, segunda via, horários livres	Avisos: mandar o lead ao CRM, registrar um evento, notificar a equipe
Se a API falhar ou demorar	O caminho de sucesso não roda	O cliente nem percebe; a conversa já seguiu

Regra simples: se a próxima mensagem depende da resposta, use Em resposta com sucesso. Se o cliente não precisa de nada que venha da API, use Continuar sem esperar resposta e a conversa fica mais rápida.

Como usar a resposta nos próximos blocos?

• Na mensagem: no bloco de conteúdo, insira o campo mapeado com o botão de variáveis, por exemplo "Seu pedido está {status_pedido} e chega em {previsao_entrega}."
• Para decidir o caminho: use o bloco Condição logo depois. Exemplo: se status_pagamento é igual a "pago", libera o acesso; senão, envia o link de pagamento.
• Como rede de segurança: uma Condição que confere se o campo mapeado ficou vazio pega os casos em que a API não encontrou o registro, e o fluxo pode responder "Não encontrei esse pedido, confere o número?".
• Na IA: o Assistente GPT também lê campos, então a resposta da API pode virar contexto para a conversa.

Por que a integração não funcionou?

Sintoma	Causa provável	Correção
"Opa, erro de servidor" ao testar e Salvar desabilitado	URL errada, API fora do ar, token inválido ou dado recusado	Confira a URL e os headers na documentação da API, ajuste a URL e teste de novo
O editor recusa a URL	Endereço com http:// ou vazio	Use o endereço https:// da API
A API diz "telefone inválido" (ou CPF, e-mail) só no teste	No teste as variáveis vão como texto, por exemplo {telefone}	Teste com um valor de exemplo no lugar da variável e depois volte a variável
Erro 401 ou 403 na resposta	Falta o header de autenticação ou o token expirou	Revise o header Authorization com o token atual
A mensagem seguinte sai com o campo vazio	Caminho do JSONPath errado, campo de tipo incompatível, ou a saída usada é Continuar sem esperar resposta	Compare o caminho com a aba Resposta, use um campo de texto e ligue a saída Em resposta com sucesso
O fluxo para no bloco	A API demorou mais de 10 segundos ou não respondeu com sucesso	Veja a execução em Configurações → Registros e fale com quem cuida da API sobre o tempo de resposta