Skip to main content

​
Configurar Integração de API

Esta configuração permite ao seu agente executar uma função em uma API externa e aguardar por uma resposta ou a obter dados de uma API externa.

​
Parâmetros

​
Geral

  • Nome da Integração: Um nome de identificação interno para sua integração dentro da listagem do agente.
  • Descrição: Esta é a área de instruções que deve ser fornecida como uma descrição detalhada explicando quando o agente de I.A deve usar essa ação e API. Recomenda-se incluir exemplos dos dados que essa ação fornece e das consultas dos clientes que ela ajuda a responder. Ex.: Utilizar quando o usuário pedir por informações do seu cadastro.
  • Endpoint / URL: O endpoint e URL na qual o agente deve encaminhar a chamada de API do seu serviço. Recomenda-se criar uma ação de API por endpoint caso você necessite chamar diversos no mesmo URL / API.
  • Método: O método HTTP a ser utilizado na chamada deste endpoint.

​
Headers

  • Estes são os headers a serem enviados durante a requisição da sua API. Aqui você deve definir parâmetros importantes como o Content-Type, o Accept e também a Autenticação e Autorização da sua API caso possua. Cada campo de Header deve possuir dois parâmetros:
    • Nome: A chave / nome do campo Header que será anexado.
    • Valor: O valor da chave que será enviado.

​
Body / Corpo da Requisição

  • É aqui que você define quais parâmetros serão enviados no Body / Corpo da requisição (ou nos Query Params no caso de requisições GET). Você deve apenas informar o nome do campo a ser enviado e o tipo do campo. O robô se encarrega de obter os dados no contexto da conversa caso possua ou perguntará ao usuário sobre o dado necessário caso não possua acesso a informação ainda. Cada campo a ser enviado é composto por dois parâmetros de configuração:
    • Nome: A chave / nome do campo que será anexado ao corpo da requisição.
    • Tipo: O tipo do valor a ser obtido / enviado, podendo ser Booleano (Verdadeiro / Falso), Texto ou Número.
Você deve clicar em Criar somente após configurar todos os parâmetros descritos acima, sendo os Headers opcionais.

​
Teste das Respostas da API e Dicas

  • Resposta ao vivo: teste com dados ao vivo e reais da sua API para garantir que ela esteja configurada corretamente e retornando os dados conforme esperado.
  • Utilize o Playground para testar sua API após configura-la.
  • Resposta de exemplo: use dados JSON de exemplo se a API não estiver pronta ou em modo de testes, o mais próximo do real possível.
  • Publique apenas após garantir que sua API esta funcionando conforme o esperado.

​
Casos de Uso

​
Atualizar Assinatura

Neste exemplo, usamos uma chamada de API de Upgrade de Assinatura para permitir que o usuário solicite ao agente de I.A o upgrade de sua assinatura para o plano Premium. Na seção Geral, adicionamos Atualizar_Assinatura como o nome da ação. Fornecemos as informações de “Quando usar” para que o agente de I.A use essa API sempre que o usuário quiser fazer o upgrade da assinatura. Na seção de Header, adicionamos apenas um exemplo de Autorização / Autenticação para nossa API externa, utilizando um Token Fixo fictício. Na seção de Body / Corpo, adicionamos os dados necessários para a atualização da assinatura. Adicionamos o status do plano e o novo plano solicitado, além do tipo de dado a ser enviado conforme descrevemos anteriormente ao agente. Agora, estamos prontos para solicitar ao agente de I.A que atualize ou reduza a assinatura quando o usuário perguntar sobre isso na área de Playground!

​
API de Clima

Neste exemplo, usamos uma API “Obter Clima” para fornecer as informações meteorológicas das cidades solicitadas pelo usuário ao agente de I.A. Na seção Geral, adicionamos Obter_Clima como nome da ação de API. Fornecemos as informações sobre “Quando Usar” na descrição para que o agente de I.A use essa API sempre que for questionado sobre o clima de qualquer cidade. Selecionamos aqui o método “GET” para buscar dados. Na seção de Headers, mantemos o mesmo do exemplo anterior, apenas Autenticação. Na seção de Corpo, adicionamos os dados usados para recuperar as informações meteorológicas. Adicionamos o nome da entrada como Cidade (city), o tipo da entrada é Texto e a descrição da entrada foi dada anteriormente ao agente na descrição geral. Agora, estamos prontos para perguntar ao agente de I.A sobre o clima de qualquer cidade que o usuário solicitar na área Playground.