Bloco de API - Chame APIs Externas a partir do Fluxo do Seu Chatbot

Visão Geral

O Bloco de API permite que seu chatbot chame qualquer API REST externa no meio da conversa, capture a resposta e roteie o fluxo com base em sucesso ou falha. Use-o para consultar pedidos no seu banco de dados, verificar OTPs, buscar status de envio, checar saldos de conta ou integrar qualquer sistema que exponha um endpoint HTTP.

Quando o bot chega a um bloco de API, ele envia a requisição HTTP configurada, aguarda a resposta, extrai campos do corpo JSON ou XML para variáveis e então segue a ramificação de sucesso (HTTP 2xx/3xx) ou a ramificação de falha (HTTP 4xx/5xx). Os blocos seguintes no fluxo podem usar as variáveis extraídas em mensagens, condições ou chamadas de API subsequentes.

Onde Encontrá-lo

1. Abra seu chatbot no Studio
2. Arraste o bloco API da barra lateral esquerda para o canvas
3. Conecte-o a partir de qualquer bloco anterior
4. Dê um clique duplo no bloco para configurá-lo

O bloco de API tem duas conexões de saída: Sucesso (superior/padrão) para respostas 2xx e 3xx, e Falha (secundária) para respostas 4xx e 5xx.

Configuração

Etapa 1: Defina a URL e o Método da Requisição

Campo	Descrição
URL	O endpoint completo, por exemplo https://api.example.com/orders/{order_id}
Método	Verbo HTTP: GET, POST, PUT, PATCH ou DELETE

Você pode inserir qualquer variável capturada anteriormente no fluxo usando a sintaxe {variable_name} (chaves simples). As variáveis são resolvidas em tempo de execução antes do envio da requisição.

Etapa 2: Adicione Parâmetros de Consulta (Opcional)

Para requisições GET, use Parâmetros de Consulta para anexar pares chave-valor à URL. Cada linha recebe uma Chave e um Valor. A substituição de variáveis funciona em ambos os campos.

Key: customer_email       Value: {email}
Key: include_archived     Value: false

Etapa 3: Configure os Cabeçalhos

Adicione cabeçalhos HTTP personalizados na seção Cabeçalhos. Cada linha recebe uma Chave e um Valor.

Key: Content-Type         Value: application/json
Key: Accept               Value: application/json
Key: X-Custom-Header      Value: {tenant_id}

O Content-Type é detectado automaticamente quando você escolhe um formato de corpo, mas você pode sobrescrevê-lo.

Etapa 4: Adicione Autenticação

O bloco de API suporta três modos de autenticação. Escolha o que corresponde à API de destino.

Tipo de Autenticação	Campos	Como É Enviado
Basic Auth	Usuário, Senha	Enviado como Authorization: Basic <base64>
Token Bearer	Token Bearer	Enviado como Authorization: Bearer <token>
Cabeçalho Personalizado	Nome do Cabeçalho, Valor do Cabeçalho	Enviado como <Name>: <Value> (para chaves de API, esquemas personalizados)

Nota: Para APIs que usam x-api-key ou similar, escolha Cabeçalho Personalizado e defina o Nome como x-api-key e o Valor como sua chave. Você também pode armazenar a chave em uma variável e referenciá-la como {api_key}.

Etapa 5: Monte o Corpo da Requisição

Para requisições POST, PUT e PATCH, configure o corpo na seção Corpo. Escolha o formato:

Formato	Use Quando
JSON	A maioria das APIs REST modernas
XML	Endpoints legados SOAP ou XML
Nenhum	Nenhum corpo necessário (típico para GET e DELETE)

Escreva o JSON ou XML bruto no editor de corpo. As variáveis podem ser inseridas inline:

{
  "order_id": "{order_id}",
  "customer": {
    "name": "{name}",
    "email": "{email}"
  },
  "total": {amount}
}

Etapa 6: Mapeie a Resposta para Variáveis

Em Salvar Resposta em Variáveis, defina como extrair campos da resposta JSON para variáveis do fluxo.

Caminho JSON	Nome da Variável
result.user.name	user_name
data.orders[0].status	order_status
items[*].id	item_ids

Sintaxe de caminho suportada:

• Notação de ponto para objetos aninhados: result.user.email
• Índice de array: items[0].name
• Extração com curinga em array: items[*].id retorna todos os IDs como um array
• Campo raiz: status ou message

Os valores extraídos ficam disponíveis em todos os blocos subsequentes como {variable_name}.

Etapa 7: Envie e Salve

Clique em Enviar no modal do bloco, depois salve o fluxo usando Salvar Alterações na barra superior.

Como a Resposta É Tratada

Caminho de Sucesso (HTTP 2xx / 3xx)

1. As variáveis de Salvar Resposta em Variáveis são preenchidas
2. O fluxo segue a conexão de saída de Sucesso

Caminho de Falha (HTTP 4xx / 5xx)

1. As variáveis de resposta podem ou não ser preenchidas, dependendo do corpo do erro
2. O fluxo segue a conexão de saída de Falha
3. Use esta ramificação para enviar uma mensagem de erro amigável ou tentar novamente

Tempo Limite

As requisições expiram após 30 segundos. Se sua API for lenta, considere dividir o trabalho em duas etapas ou usar um padrão assíncrono orientado por webhook.

Testando no Playground de API

Toda chamada do bloco de API é registrada e fica disponível no Playground de API dentro do Studio. Para cada execução de teste você pode ver:

• A URL, o método e os cabeçalhos totalmente resolvidos
• O corpo da requisição que foi enviado
• O código de status HTTP recebido
• O corpo completo da resposta
• As variáveis que foram extraídas

Use o playground para depurar variáveis de modelo, autenticação e mapeamentos de caminho JSON antes de publicar o fluxo.

Boas Práticas

• Armazene segredos em variáveis, não na configuração do bloco. Capture chaves de API em configurações específicas do ambiente e passe-as por variáveis para que o mesmo fluxo funcione em staging e produção
• Sempre configure a ramificação de Falha. Nunca presuma que a chamada da API teve sucesso. Envie uma mensagem alternativa como "Não conseguimos recuperar seu pedido agora. Tente novamente mais tarde."
• Mantenha os corpos de requisição pequenos. Não envie históricos de chat inteiros ou cargas grandes a menos que a API precise deles
• Valide os campos da resposta antes de usá-los. Se order_status puder estar ausente, adicione um bloco de Condição após a chamada da API para verificar {order_status} antes de usá-lo em uma mensagem
• Use nomes de variáveis descritivos. user_email é melhor que val1 porque é mais fácil de depurar no Playground e no registro da conversa
• Defina o Content-Type explicitamente ao enviar JSON, para que APIs rigorosas aceitem a requisição

Casos de Uso Comuns

Consulta de Pedido

O cliente fornece um ID de pedido, e o bot busca o status no seu backend de e-commerce.

• Método: GET
• URL: https://api.myshop.com/orders/{order_id}
• Autenticação: Token Bearer
• Mapa de Resposta: data.status para order_status, data.tracking_url para tracking_url

Verificação de OTP

O bot coleta um código de 6 dígitos, chama seu endpoint de verificação e ramifica com base no resultado.

• Método: POST
• URL: https://api.myapp.com/verify-otp/
• Corpo: {"phone": "{phone}", "code": "{otp_code}"}
• Mapa de Resposta: verified para otp_verified
• Use um bloco de Condição em seguida: se {otp_verified} == true continue, caso contrário pergunte novamente

Sincronização de Contato com CRM

Envie os detalhes de contato coletados ao seu CRM quando o usuário concluir a qualificação.

• Método: POST
• URL: https://api.crm.com/v1/contacts/
• Autenticação: Cabeçalho Personalizado (x-api-key: {crm_key})
• Corpo: {"name": "{name}", "email": "{email}", "source": "chatbot"}

Solução de Problemas

A requisição falha com 401 Unauthorized

1. Verifique se o tipo de autenticação corresponde ao que a API espera
2. Para tokens Bearer, não inclua a palavra Bearer no campo do token. O bloco a adiciona automaticamente
3. Para autenticação por Cabeçalho Personalizado, verifique se o nome do cabeçalho corresponde exatamente à documentação da API (sensível a maiúsculas para algumas APIs)
4. Inspecione a requisição no Playground de API para confirmar que o cabeçalho está sendo enviado

As variáveis não são preenchidas a partir da resposta

1. Abra o Playground de API e inspecione o corpo real da resposta
2. Confirme que o caminho JSON corresponde à estrutura da resposta. Os caminhos são sensíveis a maiúsculas
3. Para arrays, use items[0].field para um único valor ou items[*].field para todos os valores
4. Se a resposta for XML, certifique-se de definir o formato do corpo corretamente. Os caminhos JSON também funcionam no XML analisado

O fluxo segue a ramificação de falha mesmo quando a API funciona

1. Verifique o código de status HTTP no Playground de API. Algumas APIs retornam 201 (Created) em POST, o que ainda é sucesso
2. Se a API retorna 200 mas com um erro no corpo, use um bloco de Condição após a ramificação de sucesso para inspecionar o campo da resposta

A requisição expira

1. O tempo limite é fixo em 30 segundos. Se sua API regularmente leva mais tempo, ela pode não ser adequada para chat em tempo real
2. Considere mover o trabalho lento para um job em segundo plano e consultar o resultado, ou use um webhook para ser notificado quando estiver pronto

As variáveis de modelo aparecem como {variable} bruto na requisição

1. Confirme que a variável foi definida por um bloco anterior no fluxo
2. Verifique a grafia do nome da variável (sensível a maiúsculas)
3. Use o Registro da Conversa para inspecionar quais variáveis estão realmente preenchidas naquele ponto

Próximas Etapas

• Bloco de Webhook - Receba chamadas HTTP de entrada para acionar ou retomar um fluxo
• Bloco de Fim de Conversa - Encerre conversas com um botão de reinício
• Visão Geral do Studio - Explore todos os tipos de bloco e os recursos do construtor de fluxos