O elemento Solicitação de API em chatbots

Automatizar o processo de recebimento de dados se tornou ainda mais fácil com as solicitações API. Você pode solicitar dados sobre a informação que seu usuário está interessado, criar um perfil de cliente, ou se registrar para um evento em sistemas externos. Em troca, você recebe informações que você pode exibir diretamente em uma mensagem para o usuário ou salvá-la como uma variável do chatbot.

Como enviar uma solicitação de dados

O elemento Solicitação de API envia uma solicitação para um servidor externo usando dados do seu chatbot. Adicione um URL de solicitação, cabeçalhos e corpo da solicitação e, em seguida, defina como a resposta deve ser processada.

Configure a solicitação

Arraste o elemento Solicitação de API para a área de trabalho, conecte-o com o elemento que posteriormente você quer obter a informação.

Selecione o tipo de solicitação:

• Uma solicitação GUEST é usada para conseguir dados existentes;
• Uma solicitação POST é usada para criar um novo complemento no sistema e obter informações sobre ele.

Insira a URL para enviar a solicitação. Você pode usar as variáveis personalizadas e globais do seu chatbot e modificá-las na solicitação. Para selecionar as variáveis, clique em {} no canto superior direito do campo de texto. Para encontrar uma variável, na parte superior da lista suspensa de variáveis, digite o nome da variável no campo de pesquisa Encontrar por nome.

Para adicionar cabeçalhos de solicitação, por exemplo, para autorizar essas solicitações, clique em Adicionar cabeçalhos. Você também pode usar variáveis do bot neles.

Se você está utilizando uma solicitação POST, no campo solicitado insira o corpo requisitado em JSON com parâmetros. Você também pode modificar o corpo da solicitação.

Clique em Testar Solicitação para checar o envio dos dados. Além disso, esse teste é útil para reconhecimento de dados para as próximas configurações.

Converter tipos de variáveis no corpo da solicitação

Ao inserir uma variável do chatbot em um corpo de solicitação, o chatbot a envolve automaticamente entre aspas e a envia como texto. Se a API de destino esperar outro tipo de dado, como um número, valor booleano ou objeto aninhado, use um modificador do corpo da solicitação.

Um modificador do corpo da solicitação é um indicador de tipo com prefixo de dois-pontos colocado após o nome da variável:{{variable_name}}::type. Esse modificador converte os valores para o tipo de dado especificado e remove automaticamente as aspas ao redor do resultado JSON.

Você pode adicionar os seguintes modificadores:

Por exemplo, se você usar o seguinte corpo da solicitação:

{
  "name": "{{full_name}}",
  "id": "{{crm_id}}::int",
  "stage_id": 2
}

Seu chatbot substituirá as variáveis pelos respectivos valores e enviará:

{
  "name": "John",
  "id": 123,
  "stage_id": 2
}

Os chatbots enviam o valor id como um número. As aspas ao redor dele são removidas automaticamente.

Os modificadores do corpo da solicitação são diferentes dos modificadores de variável. A sintaxe com dois-pontos se aplica apenas ao elemento Solicitação de API e é usada para converter tipos de dados em cargas JSON.

Se você inserir uma variável no corpo da solicitação sem aspas ao redor, por exemplo: "key": {{var}}, o criador de chatbot identificará o corpo como um JSON inválido.

Como usar dados recebidos

Se a solicitação for bem-sucedida, você receberá um corpo de resposta e o usuário irá para o ramo “Concluído”.

Todas as respostas de solicitação com o status 2xx irão para o ramo “Concluído“. As respostas de solicitações com outros status irão para o ramo “Erro”, e você não poderá usar esses dados. Leia mais: Como continuar um fluxo em caso de erro de solicitação.

Você pode usar os dados recebidos no próximo elemento, salvá-los em uma variável de chatbot para uso repetido, ou enviar uma lista de mensagens baseada no array especificado.

A API pode retornar uma resposta com até 65 KB de tamanho. O limite de tempo de processamento da solicitação é de 60 segundos.

Usando dados salvando-os em uma variável

Para salvar os dados como variáveis para uso futuro, no elemento “Solicitação de API” nas solicitações mapeadas, clique em Adicionar.

No campo de resposta, selecione a chave cujo valor de variável você quer utilizar.

Selecione a variável para que o valor seja armazenado.

Quando você tiver salvado o número de variáveis solicitadas, clique em “Aplicar” e proceda para criar o próximo elemento.

Nesse exemplo, nós criamos um pedido, dados recebidos do nosso CRM, os salvamos como variáveis, e informamos o usuário para identificar rapidamente o serviço ou produto que eles pediram.

Como um usuário, se comunicar com o seu chatbot se parece com isso:

Usando dados como uma expressão de caminho JSON

Se você não precisa escrever os dados nas variáveis, você pode utilizar a informação recebida inserindo uma expressão de caminho JSON da estrutura.

Os dados que você não está escrevendo só podem ser usados uma vez no próximo bloco de texto.

Na mensagem de texto, adicione o Caminho JSON {{$['somekey']['nestedkey']}}.

Para usar cabeçalhos, cookies, códigos de status e outros dados do sistema de uma solicitação, faça referência a eles na sua mensagem como {{$$['headers']}}, {{$$['cookies']}} ou {{$$['data']}}.

Essa abordagem é útil para integrações que dependem de dados de autorização contidos em cookies.

Como um usuário, se comunicar com o seu chatbot vai se parecer com isso:

Usando dados para enviar cartões

Em uma assinatura paga, você pode gerar e enviar cartões a partir dos dados recebidos na resposta da solicitação. Para isso, utilize a aba "Enviar mensagens", adicione um link à sua API e preencha os campos do formulário com os dados do array obtido.

Leia mais: Como enviar cartões de mensagem em chatbots.

Como continuar um fluxo em caso de erro de solicitação

Você também pode ramificar seu cenário e, no caso de uma solicitação de API com falha, continuar seu fluxo usando o ramo Erro. Por exemplo, você pode notificar os usuários sobre um erro, solicitar novamente os dados necessários se eles não corresponderem ou convidar um gerente.

Você também pode transmitir a resposta de erro do servidor. Isso ajuda a exibir uma mensagem de erro para os usuários ou a registrar detalhes do erro para fins de depuração. Para fazer referência a um campo específico na resposta de erro, use uma expressão JSON Path, por exemplo: {{$['status_code']}}.

Última Atualização: 29.05.2026