Suite | Team, Growth, Professional, Enterprise ou Enterprise Plus |
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
authorization
oux-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.json Recuperar 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.
70 comentários
Leo Alberti
Seconding the request to increase the character limit for variables. Some self-service links I'm trying to provide customers exceed this length, so the limit is quite a blocker.
0
Alex Duffey
We need the character limit to be lifted. 280 is very small. Please look at opening this in the future. We are trying to a return an accessory list of products for one of our products, but the 280 limit stops us from providing that full list.
We tried breaking it up into multiple variables, but the the system requires us to save each one for each new product, which then runs into the 50 mac variable limit.
Please either raise the character limit to at least 1000 or raise the variable limit to at least 200.
1
Jeffrey Porter
Is it possible to include the originating URL for the page on which the chat bot was accessed in an API call? Our use case is that we are installing the chat bot on a video player and each video has a distinct URL. I created a chat bot flow that creates a Zendesk ticket. We'd like to be able to include the URL for the page in the ticket so we know where to go look for a problem. Right now we'd have to ask the user for something and we're guaranteed to get vague answers.
0
Aktie Projeto
Como faço para apagar variáveis que coloquei para teste e agora estão ocupando espaço no meu bot?
0
Yiannis Lamprou
I am trying to get data from hubspot via Make API call.
I am using POST method and i get all fields i want and can turn them to variable.
However the fields ( variables) are coming as numbers. (e.g
"hs_pipeline_stage":"67655766",
)How can i say to ZD to display text according to the variable coming in?
Is there a way to create an array or so besides carousel?
0
이지훈(AI Tester)
I have a similar question to 6336142945306
For example, I want to use users.json to allow end users to retrieve their information using an API.
If a user has a "custom_role_id" value, I can create a flow by saving that value as a variable.
However, if the flow is executed for a user who does not have a "custom_role_id" value, an API error is returned.
In conclusion, even null values should be saved as variables, and when the variable is referenced in the flow, a null value should be returned instead of an error.
Is this possible?
0
Nir Tzezana
Hi,
I have some data I want to add to the API request body, this is data that I already have when the chat window opened (no need to gather it from the user), how can I do that?
0
Fatima Sbeih
Has anyone managed to set this up with Stripe?
0
דורין אברבך
Hey, https://support.zendesk.com/hc/en-us/articles/4572971586586/comments/4614301298458 is there any updates?
about getting information from the user in order to use their input as parameters in API request
0
Javier DM
Este caso que comentas, está justamente mencionado al pie de este artículo, donde pone:
He visto este tipo de situaciones, cuando se quiere utilizar un
null
value como expresión boolean. Por eso la llamada puede ser exitosa (respuesta 200), pero el valor no corresponde a ninguna de las varlables que se han guardado para el flujo, por lo que el paso API fallará.Un ejemplo:
En este caso, cuando el valor sea
null
el paso API va a fallar, por mas que la llamada sea exitosa. Ya que la variable aquí guardada esorganization_id
ynull
no es un valor exista para ese atributo.Espero esta explicación te sea de utilidad. Si precisaras revisar tu caso en mas profundidad, te sugiero por favor dirigirte a support.zendesk.com/hc e iniciar una conversación con el bot para ponerte en contacto con nuestro equipo de soporte.
Saludos y que tengas buena semana!
0
Entrar para deixar um comentário.