Uso da etapa Fazer chamada de API em um agente de IA para mensagens (legado)

Qual é o meu plano?

Suite

Qualquer plano

Este artigo descreve a funcionalidade disponível apenas para clientes que tinham um agente de IA rascunhado ou publicado em 2 de fevereiro de 2025. Para obter informações sobre funcionalidade equivalente no complemento Agentes de IA - Avançado, consulte Integração de outras plataformas com agentes de IA - Avançado.

A etapa Fazer chamada de API permite configurar uma chamada da API para outro sistema, como um CRM ou ERP interno, ou enviar detalhes da conversa para um ponto de extremidade externo, como o Amazon Event Bridge ou Google Analytics.

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
• Inclusão de detalhes da API
• Salvamento de variáveis de resposta da API
• Sobre as ramificações da etapa

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.

Os procedimentos descritos a seguir pressupõem que você já criou um agente de IA para mensagens e, agora, deseja adicionar essa etapa ao agente de IA.

Observação: se o sistema sendo chamado não responder em 10 segundos, a chamada será encerrada.

Como adicionar a etapa Fazer chamada de API

1. Na Central de administração, clique em Canais na barra lateral e selecione Agentes de IA e automação > Agentes de IA.
2. Clique em Gerenciar agentes de IA para mensagens.
3. Clique no nome do agente de IA que você quer editar.
4. Clique na aba Respostas e crie uma nova resposta ou abra uma resposta existente.
5. 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.
6. No painel de configuração, clique em Fazer chamada de API.
7. 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.

8. 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

1. No painel de configuração, clique em Detalhes da API.
2. 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.
3. 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.

4. 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.
5. 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 ou x-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.

6. 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.	https://domain.com/api/search?input=value Não é possível adicionar as variáveis ao domínio/subdomínio
https://maps.googleapis.com/maps/api/place?input=city_name Recuperar o local por pesquisas de palavra-chave da Places API da Google.	https://example.com/api/search?key=value 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.

Observação: os valores das variáveis não são traduzidos automaticamente. Lembre-se disso se você usa o recurso de tradução automática nas conversas por redes sociais.

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

1. No painel de configuração, clique em Fazer chamada de API.
2. 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.
3. Clique em Salvar.
4. 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

Você pode enviar variáveis de matriz usando Fazer chamada de API e fornecendo uma URL para o sistema externo. O sistema externo precisa ter um ponto de extremidade da API. Um ponto de extremidade da API é uma URL em que a API recebe solicitações e envia respostas, permitindo que dois sistemas interajam. As respostas são renderizadas no formato JavaScript Object Notation (JSON), como mostra o exemplo a seguir.

{               
    "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",
	…
    

Somente os primeiros itens na variável de matriz são exibidos na Central de administração para ajudar a visualizar quais dados são retornados. Por exemplo, na saída JSON acima, 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.

Observação: somente os primeiros 280 caracteres do valor de uma propriedade aparecem na resposta.

Matrizes JSON aninhadas também podem ser salvas como variáveis de matriz. Por exemplo, considerando a seguinte saída JSON, 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.

Se a variável retornada for nula, o item não será exibido no carrossel. Por exemplo, no seguinte cenário, suponha que o valor da variável {{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

neste exemplo, uma variável de matriz é criada usando um ponto de extremidade de API que retorna uma matriz de pedidos. A matriz de pedidos é especificada pela propriedade "results" no seguinte trecho de resposta da API.

     {
  "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

1. No painel de configuração, clique em Fazer chamada de API.
2. Insira orders como o nome.
3. No painel de configuração, clique em Detalhes da API.
4. Clique no menu suspenso Método de solicitação e selecione GET.
5. Insira a URL da URL do ponto de extremidade.
6. 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.

7. Clique em Fazer chamada de API.
8. Clique em Salvar perto de results.

   

9. Na lista suspensa Valor, selecione Pedido e, em seguida, Imagem.

   Use o nome padrão da variável (image).

10. 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).

    

11. Clique em Salvar.

Como criar o carrossel dinâmico

1. No criador de bots, clique em Adicionar etapa em Êxito na chamada da API e selecione Adicionar carrossel.
2. No painel de configuração, clique em Converter para mensagem dinâmica.
3. No menu suspenso Matriz, clique em results. Essa é a matriz que você criou anteriormente.
4. 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.

5. Para o link do botão, clique no sinal de mais e selecione results.image.
6. Para o texto do botão, clique no sinal de mais e selecione results.status.
7. Para o link da imagem, clique no sinal de mais e selecione results.image.
8. 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.

O agente de IA moverá a ramificação com falha para baixo quando ocorrer um dos seguintes casos:

• A API retornar um código de resposta 400 ou 500.
• A API retornar um código de resposta 200 em que 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.

Se você usa a etapa Fazer chamada de API, reconhece que o sistema externo ao qual você se conecta é um Serviço Não Zendesk (conforme definido no Contrato Principal de Serviços). A Zendesk não opera nem controla os Serviços Não Zendesk ativados por meio do uso do recurso de extensões do criador de bots e também não é responsável por obrigações legais ou regulamentares de conformidade suas e dos Serviços Não Zendesk.