Neste artigo, ajudaremos você a executar os procedimentos de inclusão e configuração da etapa em um agente de IA para mensagens.
Para obter uma visão geral sobre a etapa Fazer chamada de API e suas regras de configuração, consulte Noções básicas sobre os tipos de etapas do agente de IA: Fazer chamada de API.
Este artigo inclui as seguintes seções:
Inclusão de uma etapa Fazer chamada de API no seu agente de IA
A adição da etapa Fazer chamada de API ao seu agente de IA requer a execução de várias tarefas distintas.
Como adicionar a etapa Fazer chamada de API
- Na Central de administração, clique em
IA na barra lateral e selecione Agentes de IA > Agentes de IA. - Clique em Gerenciar agentes de IA para mensagens.
- Clique no nome do agente de IA que você quer editar.
- Clique na aba Respostas e crie uma nova resposta ou abra uma resposta existente.
- No criador de bots, clique no ícone Adicionar etapa no ponto em que deseja inserir a etapa, no final de uma ramificação ou entre duas etapas existentes.
- No painel de configuração, clique em Fazer chamada de API.
- Digite a descrição da etapa.
- Nome: um nome para a chamada que facilite a identificação da sua equipe.
- Descrição (opcional): uma descrição sucinta da ação tomada pela chamada.
Essas informações não ficarão visíveis para os clientes.
- Prossiga com o procedimento descrito em Inclusão de detalhes da API.
Inclusão de detalhes da API
Use a seção de detalhes da API para configurar a chamada HTTP que deseja fazer, incluindo o método de solicitação HTTP, a localização do recurso externo e a adição de cabeçalhos, se necessário. As etapas a seguir correspondem à continuação do procedimento descrito na seção anterior.
Como adicionar os detalhes da API
- No painel de configuração, clique em Detalhes da API.
- Selecione um Método de solicitação:
- GET – recupera um recurso externo do serviço de API. Esse é o método mais usado.
- POST – envia dados para criar um recurso em um sistema externo. Se o recurso já existe, os dados enviados modificam o recurso.
- PUT – envia dados para atualizar um recurso.
- PATCH – envia dados para atualizar um recurso em um site externo. É usado para aplicar modificações parciais ao recurso.
- DELETE – remove o recurso do local externo.
- Insira uma URL do ponto de extremidade.
A URL do ponto de extremidade é o local do recurso externo ao qual você está se conectando. A URL do ponto de extremidade é compatível com o protocolo
https://. Você pode incluir variáveis no caminho da URL ou nos valores da cadeia de caracteres da consulta. Para obter mais informações, consulte Envio de variáveis em uma chamada de API. - Opcionalmente, selecione uma conexão para autenticar a chamada da API.
Observação: você deve criar uma conexão antes de usá-la na etapa Fazer chamada de API.
- Se necessário, insira a chave e o valor para um cabeçalho opcional. Importante: não use cabeçalhos para autenticação. Em vez disso, use conexões de API.
As etapas Fazer chamada de API que incluem cabeçalhos relacionados à autenticação, como
authorizationoux-api-key, falharão automaticamente. Se uma etapa Fazer chamada de API falhar, a conversa segue a ramificação Falha na chamada da API da etapa. - Para testar a solicitação da API, clique em Fazer chamada de API.
Se as variáveis forem adicionadas à URL ou ao cabeçalho da etapa, você poderá incluir dados de teste opcionais em seu serviço externo para verificar se a chamada da API está funcionando conforme o esperado. É importante ressaltar que isso fará uma solicitação HTTP para a URL do ponto de extremidade configurado.
Envio de variáveis em uma chamada de API
Ao inserir uma URL do ponto de extremidade em uma chamada de API, você pode incluir variáveis no caminho da URL ou nos valores da cadeia de caracteres da consulta. Assim, é possível enviar dados da conversa para um sistema externo.
Por exemplo, um agente de IA de mensagens pode solicitar que um cliente forneça um número de pedido usando a etapa Peça detalhes. O agente de IA pode então usar a etapa Fazer chamada de API para obter o status da remessa do pedido na sua loja online.
Não é possível usar variáveis no domínio ou no subdomínio da URL de um ponto de extremidade. Veja exemplos de valores válidos e inválidos de uma URL do ponto de extremidade na tabela a seguir.
| URL do ponto de extremidade válida | URL do ponto de extremidade inválida |
|---|---|
https://myshopify.com/admin/api/orders/order_number.jsonRecuperar um pedido ao especificar a ID dele da Shopify. 
|
Não é possível adicionar as variáveis ao domínio/subdomínio |
|
Recuperar o local por pesquisas de palavra-chave da Places API da Google. |
Não é possível adicionar as variáveis à chave da cadeia de caracteres da consulta |
Se uma variável estiver inválida ou vazia, o agente de IA ignorará a variável durante uma conversa.
Salvamento de variáveis de resposta da API
Depois de configurar os detalhes e testar a chamada da API, você pode salvar os valores da resposta do JSON da chamada da API como variáveis. Você pode salvar até 12 variáveis na etapa Fazer chamada de API. apenas os primeiros 280 caracteres do valor de uma variável são salvos.
Como criar uma variável a partir dos dados de resposta
- No painel de configuração, clique em Fazer chamada de API.
- Expanda o acordeão e identifique os dados do sistema externo que você deseja transformar em uma variável.
Dica: alterne para a aba Corpo da resposta para visualizar a resposta bruta que voltou do sistema externo.
- Clique em Salvar.
- Atribua um nome para a variável.
Os nomes de variáveis devem incluir apenas letras minúsculas, números e sublinhados.
Envio de variáveis de matriz em uma chamada de API
{
"info": {
"count": 50,
"pages": 2,
"next": "https://mycompany.com/api/orders?page=2",
"prev": null
},
"results": [
{
"id": 1052,
"name": "Alexander Cummings",
“address”: “123 MyStreet”,
"Item": "belt",
"price": "15.00",
"image": "https://mycompany.com/api/orders/avatar/1.jpeg",
…
id, name, address, item, price e image são todos exibidos. Esses dados são normalmente enviados para um carrossel; entretanto, o carrossel só pode exibir até 10 itens.
lastname e firstname podem ser salvas como variáveis de matriz separadas.
"name":
{
"lastname": "Cummings”,
"firstname": “Alexander"
},
Não é possível editar a matriz nem os valores de matriz na configuração do carrossel na Central de administração. Se for necessário alterar algum dado, você deve apagar a matriz na Central de administração e criar uma nova.
{{customer.order}} esteja vazio. O cartão 1 será renderizado com um título parcial “Order number”. O cartão 2 não será renderizado, pois o título resultante está vazio.
Card 1
Title: Order number {{customer.order}}
Description: Here's your order {{product.description}}
Card 2
Title: {{customer.order}}
Description: Here's your order {{product.description}}
Exemplo
{
"info": {
"count": 5,
"pages": 1
},
"results": [
{
"createdAt": "July 10, 2023",
"name": "Connie Stokes",
"Shippingaddress": "123 Street, City, State",
"order": {
"Status": "Ordered",
"Image": "https://images.pexels.com/photos/1484808/pexels-photo-1484808.jpeg"
},
"Quantity": 1,
"Price": 45,
"Item": "Shirt",
"id": "1"
},
… Este exemplo usa Fazer chamada de API para criar a variável de matriz e, em seguida, usa um carrossel dinâmico para exibir os resultados para o usuário final.
Como criar a matriz
- No painel de configuração, clique em Fazer chamada de API.
- Insira orders como o nome.
- No painel de configuração, clique em Detalhes da API.
- Clique no menu suspenso Método de solicitação e selecione GET.
- Insira a URL da URL do ponto de extremidade.
- Em Autenticação, selecione seu método de autenticação.
Para obter mais informações, consulte Criação de conexões para integração com serviços externos.
- Clique em Fazer chamada de API.
- Clique em Salvar perto de results.
- Na lista suspensa Valor, selecione Pedido e, em seguida, Imagem.
Use o nome padrão da variável (image).
- Clique em Adicionar item e repita a etapa anterior para criar itens para Order Status e Item.
Você pode adicionar até 12 itens (ou pares de valor chave).
- Clique em Salvar.
- No criador de bots, clique em Adicionar etapa em Êxito na chamada da API e selecione Adicionar carrossel.
- No painel de configuração, clique em Converter para mensagem dinâmica.
- No menu suspenso Matriz, clique em results. Essa é a matriz que você criou anteriormente.
- Para o título, clique no sinal de mais e selecione results.item.
Você pode inserir até 128 caracteres para o título e a descrição.
- Para o link do botão, clique no sinal de mais e selecione results.image.
- Para o texto do botão, clique no sinal de mais e selecione results.status.
- Para o link da imagem, clique no sinal de mais e selecione results.image.
- Clique em Concluído.
Este é um exemplo de carrossel dinâmico.
Sobre as ramificações da etapa
A etapa Fazer chamada de API é uma etapa de ramificação. A inclusão dela divide as respostas do agente de IA se a solicitação de API for executada com sucesso.
- A API retornar um código de resposta 400 ou 500.
- Uma das variáveis salvas está ausente ou tem um valor
null.
O agente de IA moverá a ramificação bem-sucedida para baixo em todos os outros casos.