Uso da etapa Fazer chamada de API no Criador de fluxos

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 fluxo de bot.

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 de fluxos para o bot: Fazer chamada de API.

Este artigo inclui as seções a seguir:

• Inclusão de uma etapa de realização de chamadas da API ao seu bot
• 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 de realização de chamadas da API ao seu bot

Adicionar a etapa Fazer chamada de API ao seu bot requer a execução de várias tarefas distintas.

Os procedimentos descritos a seguir pressupõem que você já criou o fluxo do bot e, agora, deseja adicionar essa etapa ao bot.

Como adicionar a etapa Fazer chamada de API

1. Abra o bot no Criador de fluxos.
2. Clique no ícone Adicionar novo no ponto em que deseja adicionar uma etapa, no final de uma ramificação ou entre duas etapas existentes.
3. No painel de configuração, clique em Fazer chamada de API.
4. Digite a descrição da etapa. É importante lembrar que ela fica visível apenas para sua equipe, ou seja, os clientes não terão acesso a estas informações:
   • 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.
5. Prossiga com o procedimento descrito em Inclusão de detalhes da API a seguir.

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. Use a lista suspensa para selecionar um Método de solicitação:
   • GET – recupera dados de um servidor no recurso externo. Esse é o método mais usado.
   • POST – envia dados para criar ou atualizar um recurso em um sistema externo. Se o recurso já existe, os dados enviados modificam o recurso.
   • PUT – envia dados para atualizar ou criar um recurso. Se o recurso já existe, os dados enviados substituem o 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 de Fazer chamada de API que incluem um cabeçalho relacionado à 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 bot de mensagens pode solicitar que um cliente forneça um número de pedido usando a etapa Peça detalhes. O bot 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 do 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 bot ignorará a variável em 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é oito variáveis na etapa Fazer chamada de API.

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.

Sobre as ramificações da etapa

A etapa Fazer chamada de API é uma etapa de ramificação. Adicionar esta etapa divide as respostas do bot se a API foi executada com êxito.

No tempo de execução do bot, qualquer código de resposta 200 fará com que o bot desça a ramificação bem-sucedida. Todos os códigos de resposta 400 ou 500 farão com que o bot desça a ramificação com falha. Se a API retornar 200 com uma resposta vazia, todas as variáveis ​​salvas nesta etapa serão ignoradas durante uma conversa.

Atenção: se você usa a etapa Fazer chamada de API, você reconhece que o sistema externo ao qual você se conecta é um serviço não Zendesk (conforme definido no Acordo Geral de Assinatura). A Zendesk não opera nem controla os Serviços não Zendesk ativados por meio do uso do recurso Extensões do Criador de fluxos e a Zendesk não é responsável por obrigações legais ou regulamentares de conformidade, pois essas suas e dos Serviços não Zendesk.