O criador de integrações é uma poderosa ferramenta sem código que permite conectar o agente de IA a qualquer API ou fonte de dados sem grandes habilidades técnicas ou de programação. Personalize suas experiências de chat e obtenha resoluções automatizadas mais altas com conteúdo dinâmico.
Imagine um agente de IA que pode acessar facilmente informações do cliente no seu sistema de back-office, recuperar dados de qualquer outra fonte de dados externa ou interagir com aplicativos de terceiros, tudo isso sem exigir que você escreva uma única linha de código.
Com recursos de conteúdo dinâmico, o criador de integrações permite recuperação, análise e transformação de dados em tempo real, possibilitando que o agente de IA forneça respostas, recomendações e soluções personalizadas com base nas necessidades individuais do usuário.
Com uma interface simples, recursos intuitivos e funcionalidades sem código, o criador de integrações oferece total flexibilidade e personalização sem a necessidade de amplo conhecimento técnico.
Neste artigo, exploraremos os principais recursos e benefícios do criador de integrações, juntamente com um guia passo a passo sobre como aproveitar seus recursos para conectar o agente de IA a qualquer API ou fonte de dados.
Introdução
Para acessar o criador de integrações, clique em "Integrações de API" no menu de navegação lateral. Isso direcionará você para uma lista de visão geral onde todas as suas integrações futuras serão convenientemente listadas e ficarão acessíveis. Inicialmente, você começará sem integrações de API ou com uma integração de API de exemplo, dependendo da sua jornada de integração.
Para criar uma nova integração, clique na opção "Adicionar integração", localizada no canto superior direito.
Forneça um nome para a integração.
Adicione uma breve descrição com contexto adicional.
Quando terminar, clique em "Salvar" para prosseguir para a página de configuração da integração.
Se você não vir as integrações de API na navegação lateral, isso provavelmente significa que você não é um administrador do cliente. Atualmente, restringimos o acesso ao criador de integrações somente a administradores do cliente. Nesse caso, entre em contato com o representante da sua conta para falar sobre direitos de acesso.
Caso você prefira obter informações por meio de uma apresentação audiovisual, veja a seguir um vídeo de introdução de um membro da nossa equipe de engenharia personalizada, Chloe.
Parâmetros da solicitação
Para começar, você precisa configurar os parâmetros de solicitação necessários para garantir uma resposta bem-sucedida da API. Esses parâmetros de solicitação contêm informações derivadas da conversa e servem para definir as especificidades da solicitação de API. Por exemplo, se você pretende recuperar informações específicas do usuário para exibir durante a conversa, é crucial incluir o ID do usuário como parte da solicitação. Isso garante que a resposta da API contenha dados relevantes para o usuário ou visitante atual envolvido no chat.
A seguir há um exemplo de um parâmetro de solicitação configurado.
Além de especificar a chave e o tipo de parâmetro de solicitação, você tem a opção de definir um valor de teste. É altamente recomendável fazer isso, pois esse valor de teste será usado durante a configuração ao utilizar a funcionalidade de teste localizada no canto superior direito. Durante uma conversa em tempo real, o valor será passado para a integração da API antes de fazer a solicitação. No entanto, como não temos o contexto da conversa em tempo real atual, é necessário definir um valor de teste para executar uma chamada de API com êxito.
A caixa de seleção "obrigatório" permite que você determine se o parâmetro de solicitação é opcional ou precisa ser informado para chamar as integrações de API na conversa, caso ainda não tenha sido salvo na sessão.
A inclusão de parâmetros de solicitação depende dos requisitos específicos da API chamada. Para algumas APIs, os parâmetros de solicitação são anexados à URL, enquanto para outras, eles são incluídos nos cabeçalhos ou no corpo da solicitação. Consulte a documentação da API para determinar onde o parâmetro de solicitação deve ser incluído. Depois de identificado, você pode adicionar o parâmetro à URL, ao cabeçalho ou ao corpo da solicitação fazendo referência à chave entre chaves duplas: {{userID}}.
Ambientes
Depois que o parâmetro de solicitação é adicionado, a configuração principal para a chamada de API pode ser executada na seção de ambiente. Ao lado do nome do ambiente exibido durante o teste de integração ou ao se referir a ele no criador de diálogos, é necessário escolher o método, a URL e o tipo de autorização com base na documentação da API subjacente.
Tipos de autorização
Oferecemos os seguintes tipos de autorização:
| Tipo de autorização | Descrição | Exemplo |
| Chave da API | Uma chave de API simples que deve ser fornecida pelo responsável pela API. |  |
| Token do portador | Outro token que deve ser fornecido pelo responsável pela API. |  |
| Autenticação básica | Um nome de usuário e uma senha são usados para autenticação com a API. |  |
| OAuth 2.0 | São necessárias várias informações de autenticação com base no tipo de concessão. |  |
| Personalizada | Autorização via token de expiração | Consulte Uso de autorização personalizada com o criador de integração. |
Lembre-se de incluir o token de autenticação na solicitação, adicionando-o como {{apiToken}} aos cabeçalhos de todos os tipos de autorização (exceto quando não for necessária uma autorização). Consulte a seção de cabeçalhos para ver um exemplo.
Cabeçalhos
Os cabeçalhos contêm informações adicionais sobre a solicitação ou sobre a comunicação entre o cliente e o servidor. Eles são pares de valores-chave incluídos na seção de cabeçalho da solicitação. Alguns cabeçalhos comumente usados incluem:
- Content-Type: indica o formato dos dados no corpo da solicitação (por exemplo, JSON, XML, dados de formulário).
- Authorization: fornece credenciais ou tokens para autenticar o cliente que faz a solicitação.
- User-Agent: especifica o agente do usuário que inicia a solicitação, normalmente o navegador da web ou o aplicativo cliente.
- Accept: informa o servidor sobre os formatos de resposta aceitos pelo cliente.
- Cache-Control: define diretivas de armazenamento em cache para o servidor ou caches intermediários.
- X-Requested-With: identifica o tipo de solicitação (por exemplo, XMLHttpRequest, Fetch API) feita pelo cliente.
Corpo
O corpo de uma solicitação de API contém os dados enviados à API. Ele é normalmente usado em solicitações que exigem dados de entrada para processamento ou manipulação de dados no lado da API. O corpo pode conter vários formatos, como JSON, XML, texto sem formatação ou dados de formulário, dependendo da API e do ponto de extremidade específico chamado. No nosso caso, até agora só oferecemos suporte a JSON.
Gerenciamento de ambientes
Para lidar com os desafios de trabalhar com ambientes sandbox e de produção para APIs, incorporamos o conceito de ambientes ao criador de integrações. Além do ambiente principal padrão criado automaticamente ao configurar uma integração, você tem a flexibilidade de incluir ambientes adicionais.
Esses ambientes adicionais permitem personalizar a URL, os detalhes de autenticação, os cabeçalhos e o corpo das solicitações, possibilitando que você se concentre em ambientes sandbox ou de produção específicos na sua API.
Para criar um novo ambiente, basta clicar no botão "+" localizado ao lado da seção de ambiente. Se você deseja replicar um ambiente existente, passe o cursor do mouse sobre ele e escolha a opção "duplicar" no menu de três pontos. Apenas um ambiente pode ser definido como padrão, o qual será posicionado no topo da lista e automaticamente selecionado primeiro no criador de diálogos (a menos que seja modificado intencionalmente).
Se um ambiente não está sendo utilizado por nenhum agente de IA e não é o único ambiente nem o ambiente padrão, ele pode ser apagado. Para modificar as configurações padrão, você pode selecionar facilmente a opção apropriada no menu de três pontos.
Funcionalidade de teste
Depois de concluir a configuração da solicitação de API, é útil verificar se todas as configurações foram feitas corretamente. Para facilitar esse processo, o criador de integrações oferece uma funcionalidade de teste conveniente localizada no canto superior direito.
O botão de teste pode ser facilmente identificado pelo rótulo "Testar" seguido pelo nome do ambiente padrão. Ao clicar nele, o criador de integrações inicia uma solicitação à API usando as informações fornecidas nas seções de parâmetros de solicitação e ambiente. A resposta recebida da API é então exibida na seção Testar integração, no lado direito da interface. Se você deseja testar a API usando os detalhes da solicitação de outro ambiente, selecione o ambiente desejado no menu de lista suspensa da funcionalidade de teste e clique no botão de teste novamente.
Conteúdo da resposta
Na seção Testar integração, o criador de integrações apresenta a resposta obtida da API. O conteúdo da resposta é organizado nos seguintes objetos:
| Objetos | Conteúdo | Exemplo |
| statusCode | Os códigos de status de resposta HTTP indicam se uma solicitação HTTP específica foi concluída com êxito. Saiba mais. | "statusCode": 200 |
| data | O objeto de dados exibe os dados relevantes da API no caso de uma solicitação concluída com êxito. No entanto, se ocorrer falha na solicitação, esse objeto fornece informações adicionais com base nos códigos de status correspondentes. |
"data": { "name": "Germany", "capital": "Berlin", "region": "Europe", "population": 83240525, "area": 357114 } |
| requestParameters | No objeto requestParameters, o criador de integrações exibe os parâmetros de solicitação junto com os valores de teste associados utilizados para chamar a API. |
"requestParameters": { "country": "de"} |
Antes de utilizar a funcionalidade de teste novamente para analisar a integração com quaisquer configurações modificadas, salve a integração.
Cenários
Cada integração recém-criada inclui três cenários pré-configurados. Embora dois desses cenários possam ser personalizados ou apagados de acordo com suas necessidades, o terceiro cenário, chamado "Fallback", não pode ser editado. O cenário "Fallback" funciona como a principal opção de fallback caso nenhum dos cenários anteriores seja iniciado por gatilho.
| Cenário | Consulta padrão | Descrição |
| Êxito | statusCode >= 200 e statusCode < 300 | O cenário que deve capturar o caminho preferencial/satisfatório se o código do status estiver entre 200 e 300. |
| Falha | statusCode < 200 ou statusCode >= 300 | O cenário que deve capturar o caminho com falha se o código do status não estiver no intervalo de 201 a 299. |
| Fallback | - | O cenário Fallback para sempre iniciar por gatilho pelo menos um cenário. |
Os cenários são equivalentes às diferentes ramificações que a conversa segue no diálogo quando a integração da API é iniciada por gatilho.
Consultas de cenário
Apenas um cenário pode ser iniciado por gatilho para cada integração de API. A lógica para determinar o cenário que é iniciado por gatilho durante uma conversa é baseada nas consultas de cenário e na ordem em que os cenários são definidos.
As consultas de cenário representam as condições que devem ser atendidas para que um cenário específico seja iniciado por gatilho. Para determinar se uma condição é verdadeira, o criador de integrações analisa a consulta de cenário, bem como os dados contidos na resposta da API. Os campos de dados comumente usados incluem códigos de status, dados específicos da API dentro do objeto de dados da resposta da API e possivelmente até valores dos parâmetros da solicitação.
A consulta de cenário padrão do cenário Success exige que o código do status da resposta da API esteja no intervalo de 200 a 300. Se essa condição for atendida, o cenário Success será iniciado por gatilho.
Como as consultas padrão de cenário podem ser modificadas e novos cenários podem ser adicionados, é possível que várias consultas de cenários distintas sejam verdadeiras com base na resposta da API. Nesses casos, a ordem dos cenários determina qual cenário será iniciado por gatilho.
Para fornecer feedback visual, implementamos um recurso que indica qual cenário seria iniciado por gatilho com base na resposta atual da API. Ele também identifica cenários que teoricamente seriam iniciados por gatilho, mas que, de fato, não o são porque um cenário de ordem superior já foi iniciado por gatilho. Além disso, ele destaca cenários que não seriam iniciados por gatilho porque possuem condições que não foram atendidas.
| Correspondência de critérios | Visualização | Descrição |
| Os critérios correspondem ao primeiro na ordem |  |
O cenário destacado por um ponto azul sólido representa o cenário que é iniciado por gatilho. |
| Os critérios não correspondem |  |
Os cenários destacados por um ponto vazio não são iniciados por gatilho. |
| Os critérios correspondem, mas não ao primeiro na ordem |  |
Os cenários representados por um ponto sólido cinza só seriam iniciados por gatilho teoricamente. |
Para modificar a ordem dos cenários, basta clicar em um cenário e reorganizar a ordem arrastando-o. Exceto para o cenário Fallback, que sempre permanece na última posição, você pode ajustar a ordem de acordo com sua preferência.
Parâmetros da sessão
Ao configurar cada cenário, você pode aprimorar a conversa com vários pontos de dados de seus sistemas de back-end. Você pode especificar os dados que deseja que fiquem acessíveis em cada cenário, transformando e armazenando as informações relevantes da resposta da API em parâmetros de sessão. Esses parâmetros de sessão podem ser utilizados no processo de criação de diálogo para apresentar informações aos visitantes ou mapear o fluxo de trabalho subjacente.
Um parâmetro de sessão é definido por um par de chave-valor. A chave serve como referência dentro do criador de diálogos, enquanto a consulta é empregada para transformar e extrair dados específicos da resposta da API para salvar o valor. O criador de integrações fornece feedback em tempo real sobre como o valor salvo, com base na resposta atual, aparecerá no campo de valor de resposta.
Na imagem anterior, a chave do parâmetro de sessão é definida como "capital" e pode ser referenciada dentro do criador de diálogos usando chaves duplas: {{capital}}. A consulta determina quais dados devem ser transformados e salvos como o valor do parâmetro de sessão. Nesse caso, é extraído o conteúdo do campo "capital" dentro do objeto de dados da resposta da API.
Linguagem de consulta: JSONata
A linguagem JSONata serve para consultas no nível do cenário e no nível do parâmetro de sessão. Essa linguagem foi desenvolvida com o princípio de que consultas simples devem ser fáceis de escrever, sendo acessível para profissionais com e sem conhecimento técnico. A JSONata apresenta uma curva de aprendizado superficial, o que permite que seja dominada rapidamente. Com a JSONata, você pode executar funções básicas, transformar datas e até mesmo fundir diferentes pontos de dados.
A JSONata é uma linguagem de consulta e transformação documentada publicamente, cuja documentação pode ser encontrada aqui.