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
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
- Abra o bot no Criador de fluxos.
- Clique no ícone Adicionar novo no ponto em que deseja adicionar uma 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. É 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.
- 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
- No painel de configuração, clique em Detalhes da API.
- 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.
- 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://. - Opcionalmente, selecione uma conexão para autenticar a chamada da API. Observação: você precisa criar uma conexão antes de autenticar a chamada da 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 de Fazer chamada de API que incluem um cabeçalho relacionado à 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.
Salvamento da resposta da API como uma variável
Uma variável é uma maneira de armazenar respostas da API. As variáveis podem ser usadas de diversas maneiras:
- Personalização da mensagem do bot para os clientes. Por exemplo, você pode salvar o nome de um cliente como uma variável e fazer referência a ele em uma mensagem de bot. É possível adicionar variáveis em qualquer ponto do fluxo após a etapa Fazer chamada de API na qual a variável foi criada, nas etapas que incluem uma mensagem configurável:
-
Envio de dados na chamada para um sistema externo. Por exemplo, você pode solicitar ao cliente o número do pedido e, em seguida, fazer uma chamada da API para seu sistema de comércio eletrônico para obter o status de envio desse pedido específico. Ao usar variáveis na etapa Fazer chamada de API, algumas restrições precisam ser observadas.
No campo URL do ponto de extremidade, as variáveis podem ser adicionadas apenas ao caminho da URL ou aos valores da cadeia de caracteres da consulta. As variáveis não podem ser usadas na parte do domínio ou subdomínio da URL. A tabela a seguir mostra exemplos do que você pode ou não fazer com variáveis:
Configuração válida Configuração inválida https://myshopify.com/admin/api/orders/order_number.jsonRecuperar um pedido ao especificar a ID dele do Shopify.
https://domain.com/api/search?input=valueNão é possível adicionar as variáveis ao domínio/subdomínio
https://maps.googleapis.com/maps/api/place?input=city_nameRecuperar o local por pesquisas de palavra-chave da Places API da Google.
https://example.com/api/search?key=valueNão é possível adicionar as variáveis à chave da cadeia de caracteres da consulta
Se uma variável se tornar inválida (se o esquema da API for alterado, por exemplo), o bot ignorará a variável quando exibida para o usuário final. Você pode criar até oito variáveis na etapa Fazer chamada de API.
Depois de configurar os detalhes da API e testar a chamada dela, você pode usar os dados de resposta retornados para criar suas variáveis. As etapas a seguir correspondem à continuação do procedimento descrito na seção anterior.
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.
Autenticação da chamada da API
Na etapa Fazer chamada de API, você pode usar uma conexão para autenticar chamadas da API ao serviço ou sistema externo.
Para fazer isso, antes você precisa criar a conexão na Central de administração. Uma conexão permite que você armazene e transfira com segurança as credenciais do serviço. Para obter mais informações e instruções detalhadas, consulte Criação de conexões na Central da administração.Se você está tendo problemas para adicionar a conexão, consulte o Registro de auditoria na Central de administração para obter mais informações.
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 em tempo de execução.
0 Comentários
Por favor, entre para comentar.