Componente: Requisição API

O componente Requisição API é útil para você integrar o seu fluxo conversacional com outros sistemas que possuam API. Para usá-lo basta configurar a sua requisição e capturar os resultados em variáveis a serem utilizadas posteriormente. Veja como configurar:

Requisição:

1. Escolha o tipo de requisição a ser realizada: JSON, SOAP (xml) ou FORM
2. Informe a URL da API
3. Defina qual o método será utilizado
4. Preencha os dados do cabeçalho da sua requisição
5. Preencha os dados do corpo da sua requisição, podendo definir se o valor é do tipo Texto (string), Número ou JSON
6. (Opcional) Ative o envio de uma mensagem de erro ao seu cliente caso a requisição falhe¹

¹Consideramos falha de requisição quando há retorno HTTP 500. Quando há retorno 200, mesmo que não haja nenhum dado sendo retornado na API, a requisição é considerada como bem-sucedida.

Resultado:

1. Marque a opção quando quiser armazenar informações retornadas no body (corpo) da resposta da API
2. Marque a opção quando quiser utilizar informações retornadas no body da resposta da API como menu de opções para o seu cliente usando o componente Múltipla Escolha.
3. Marque a opção quando quiser utilizar informações retornadas no headers (cabeçalho) da resposta da API

Vejamos um exemplo prático abaixo:

• A consulta (GET) acima visa buscar dados de um CPF na base
• Há uma autorização do tipo Bearer Token a ser enviada no cabeçalho da requisição e estamos passando o token como uma variável já obtida anteriormente
• No corpo informamos o CPF a ser pesquisado e o mesmo também possui o valor de uma variável ({{CPF}}), a qual já foi capturada anteriormente na conversa

Supondo que essa estrutura abaixo seja o formato do JSON retornado como resposta da requisição:

Nós podemos escolher as informações do body que desejamos armazenar configurando a parte de 'Resultado' do componente:

1. Escolhemos os campos de resultado da API que queremos armazenar
2. Definimos a variável que armazenará o valor de resultado da API
3. Assinalamos se aquele campo está dentro de um array ou não

Avançado

Quando uma API retorna informações mais completas, os dados podem vir organizados em estruturas aninhadas, como listas (arrays) dentro de outras listas ou objetos. O componente de Requisição API permite que você acesse qualquer informação específica usando uma notação de caminho, combinando nomes de propriedades e posições de arrays.

Exemplo 1: Valor em arrays aninhados

Veja o exemplo a seguir, com um retorno real da API da OpenAI:

{
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "Agendar consulta"
        }
      ]
    }
  ]
}

Nesse exemplo, o valor que desejamos capturar é "Agendar consulta", que está dentro do campo text. No entanto, para chegar até ele, é necessário percorrer o seguinte caminho:

1. O campo output é um array (lista), então precisamos acessar sua primeira posição com output.0.
2. Dentro desse primeiro item, há um novo campo chamado content, que também é um array. Acessamos sua primeira posição com content.0.
3. Por fim, dentro desse objeto, está a propriedade text, que contém o valor desejado.

Dessa forma, o caminho completo que você deve informar no componente para armazenar esse valor é:

output.0.content.0.text

🔍 Como esse caminho funciona:

output        → nome do campo principal (é um array)
.0            → acessa o primeiro item da lista 'output'
.content      → acessa o campo 'content' dentro do primeiro item
.0            → acessa o primeiro item da lista 'content'
.text         → acessa o valor final no campo 'text'

Portanto, no componente Requisição API, ficaria dessa forma:

💡 Importante: Essa notação permite acessar qualquer valor retornado pela API, mesmo em estruturas complexas. Basta identificar a sequência correta de propriedades e posições dos arrays.

Exemplo 2: Acessando um item na posição 2 de um array

Imagine agora outro tipo de retorno, em que há uma lista de mensagens e você deseja capturar o valor da terceira mensagem (posição 2 do array):

{
  "messages": [
    { "text": "Primeira mensagem" },
    { "text": "Segunda mensagem" },
    { "text": "Mensagem desejada" }
  ]
}

Para capturar "Mensagem desejada", você deve informar o seguinte caminho:

messages.2.text

Ilustração visual:

messages
 ├── [0] → "Primeira mensagem"
 ├── [1] → "Segunda mensagem"
 └── [2]
      └── text → "Mensagem desejada"