Receita de mensagens: obtenção de dados externos com um bot de mensagens

A etapa Fazer chamada de API do Criador de fluxos deixa um bot de mensagens usar uma solicitação REST API para obter dados de um sistema externo, como Shopify ou Salesforce.

Nessa receita, você criará uma resposta do bot que recupera dados climáticos de um local fornecido pelo usuário final. A resposta obtém dados da API OpenWeather. Você pode usar o fluxo de respostas criado nessa receita como ponto inicial para criar suas próprias respostas viabilizadas pela API.

A receita envolve as tarefas a seguir:

• Tarefa 1: verificando sua configuração
• Tarefa 2: criação de conexão de API
• Tarefa 3: criação de um campo de ticket personalizado
• Tarefa 4: criação de uma resposta usando o Criador de fluxos
• Tarefa 5: teste das alterações feitas

Observação: a Zendesk oferece este artigo apenas para fins educacionais. A Zendesk não oferece suporte aos exemplos nesse artigo. A Zendesk também não oferece suporte a tecnologias de terceiros, como a OpenWeather API.

Tarefa 1: Verificando sua configuração

Para completar esta receita, você precisará do seguinte:

• Uma conta Zendesk com um bot de mensagens publicado. Se quiser, você pode usar um ambiente de teste sandbox para testar o bot antes de usá-lo na produção.

  Para configurar um bot de mensagens em um canal de mensagens na web e em dispositivos móveis, leia Trabalho com bots de mensagens para seus canais de web e dispositivos móveis. Para configurar um bot de mensagem em um canal de rede social, leia Uso do Criador de fluxos para criar um bot para conversas por redes sociais. Para informações sobre uso de mensagens em um ambiente sandbox, leia Uso das mensagens em sua sandbox.

• Uma chave API para a conta OpenWeather. A API usada nesta receita está disponível no plano grátis do OpenWeather.

  Para cadastrar-se para uma conta OpenWeather, veja a página Criar nova conta em openweathermap.org. Após entrar, você pode obter uma chave de API na sua página da conta OpenWeather.

  Para ativar as chaves da API OpenWeather, você deve verificar o endereço de e-mail da sua conta. Após a verificação, chaves de API podem levar até duas horas para ativar. Para mais informações, consulte as perguntas frequentes em openweathermap.org.

Tarefa 2: criação de conexão de API

Para começar, crie uma conexão API para armazenar a sua chave OpenWeather. Seu bot de mensagens pode usar esta conexão para autenticar chamadas para a API OpenWeather.

 Como criar a conexão

1. Em Central de administração, clique em Aplicativos e integrações na barra lateral e selecione Conexões > Conexões.
2. Clique em Criar conexão.
3. Selecione o tipo de autenticação chave da API.
4. Insiraopenweather_api_key como o nome da conexão.
5. Insira x-api-key como o nome do cabeçalho.
6. Insira a sua chave da API OpenWeather como o Valor.
7. Insira api.openweathermap.org como o domínio permitido.
8. Clique em Salvar para criar a conexão.

Tarefa 3: Criação de um campo de ticket personalizado

Em seguida, crie um campo de ticket personalizado para capturar o local fornecido pelo usuário final.

Como criar campos de ticket personalizados

1. Na Central de administração, clique em Objetos e regras na barra lateral e selecione Tickets > Campos.
2. Clique em Adicionar campo.
3. Selecione o tipo de campo Texto.

   

4. Digite Local como o Nome de exibição.
5. Em Permissões, selecione Os clientes podem editar.
6. Em Clientes, insira Local como o Título exibido para os clientes.
7. Clique em Salvar.

Se sua conta usa um único formulário de ticket, o novo campo é exibido automaticamente. Para remover o campo, leia Edição de formulários de ticket.

Tarefa 4: criação de uma resposta usando o Criador de fluxos

Esta seção orienta você a criar uma resposta, configurar sua intenção e adicionar etapas para a resposta no Criador de fluxos. Isso envolve as seguintes etapas:

• Etapa 1: criar a resposta
• Etapa 2: configurar a intenção da resposta
• Etapa 3: adicionar uma etapa de mensagem inicial
• Etapa 4: perguntar um local ao usuário final
• Etapa 5: recuperar dados de clima para o local
• Etapa 6: enviar mensagem de clima para o usuário final
• Etapa 7: adicionar uma mensagem de falha
• Etapa 8: publicar seu bot atualizado

Etapa 1: criar a resposta

Use o Criador de fluxos para criar uma resposta para o seu bot de mensagens.

Como criar a resposta

1. Na Central de administração, clique em Canais na barra lateral e selecione Bots e automações > Bots.
2. Passe o cursor do mouse sobre o bot com o qual você deseja trabalhar e clique em Editar.
3. Clique em Criar resposta.

Etapa 2: configurar a intenção da resposta

Configure a intenção da resposta e frases de treinamento. Essas incluem frases e palavras usadas para disparar a resposta em uma conversa.

Para configurar a intenção da resposta

1. Na aba Respostas da página edição do bot, clique em Criar resposta.
2. Insira Obter clima como resposta para a Intenção.
3. Em Frases de treinamento, insira Obter previsão do tempo e Obter temperatura atual.
4. Clique em Avançar.

   A resposta é aberta no Criador de fluxos, onde é possível criar a resposta do bot.

Etapa 3: adicionar uma etapa de mensagem inicial

Para perguntar o local ao usuário, adicione a etapa Enviar mensagem. Essa é a primeira etapa no fluxo da resposta.

Para adicionar uma etapa de mensagem inicial

1. No Criador de fluxos, clique em Adiciona etapa.
2. Em Escolher etapa, selecione Enviar mensagem.
3. Em Mensagem do bot, insira o seguinte texto:

   What location would you like to get the weather for?
   
   Include the country code. For example: "Melbourne, AU" or  "San Francisco, US"

Etapa 4: perguntar um local ao usuário final

Após a mensagem inicial, adicione uma etapa Peça detalhes para apresentar um formulário básico para o usuário final. O formulário inclui uma caixa de texto para o valor Local do campo de ticket.

Como adicionar uma etapa Peça detalhes

1. No Criador de fluxos, clique no ícone () Adiciona etapa.
2. Em Escolher etapa, selecione Peça detalhes.
3. Insira Obter local como o Nome.
4. Em Campos, digite e selecione Local no campo de ticket.

Etapa 5: recuperar dados de clima para o local

Adicione uma etapa Fazer chamada de API para obter dados de clima para o local a partir do ponto de extremidade Dados de clima atual.

Como adicionar a etapa Fazer chamada de API

1. No Criador de fluxos, clique em Adiciona etapa.
2. Em Escolher etapa, selecione Fazer chamada de API.
3. Insira Obter clima como o Nome.
4. Em Detalhes da API, insira https://api.openweathermap.org/data/2.5/weather?units=metric&q= como URL do ponto de extremidade.
5. Use o ícone () Adicionar uma variável para incluir a variável de campo Local ao valor URL do ponto de extremidade.

   O valor final da URL do ponto de extremidade deve parecer com isso:

   

6. Em Autenticação, selecione a conexão openweather_api.
7. Para testar a solicitação da API, clique em Fazer chamada de API.
8. Em Dados de teste, insira Melbourne, AU como o Local.
9. Clique em Fazer chamada de API.
10. Salve as seguintes variáveis usando os seus nomes padrão:
    • main > temp
    • weather > item 1 > description

Etapa 6: enviar mensagem de clima para o usuário final

Após recuperar os dados de clima, use uma etapa Enviar mensagem para responder com uma mensagem contendo os dados de clima.

Para adicionar uma mensagem de sucesso da API

1. No Criador de fluxos, clique em Adicionar etapa na ramificação Êxito na chamada da API da etapa Obter clima.
2. Em Escolher etapa, selecione Enviar mensagem.
3. Em Mensagem do bot, insira o seguinte texto:

   It's {{temp}}° C with {{description}} in 

4. Use o ícone () Adicionar uma variável para incluir a variável de campo Local ao valor Mensagem do bot. Então adicione um ponto (.).

   O valor final da Mensagem do bot deve se parecer com isso:

   

Etapa 7: adicionar uma mensagem de falha

A solicitação feita durante a etapa Fazer chamada de API pode falhar. Por exemplo, a solicitação pode incluir um local que não existe. Adicione uma etapa Enviar mensagem à ramificação Falha na chamada da API. Essa etapa retorna uma mensagem caso a chamada da API OpenWeather falhe.

Para adicionar uma mensagem de falha da API

1. No Criador de fluxos, clique em Adicionar etapa na ramificação Falha na chamada da API da etapa Obter clima.
2. Em Escolher etapa, selecione Enviar mensagem.
3. Em Mensagem do bot, insira o seguinte texto:

   I'm sorry. I wasn't able to get weather data for 

4. Use o ícone () Adicionar uma variável para incluir a variável de campo Local ao valor Mensagem do bot. Então adicione um ponto (.).

   O valor final da Mensagem do bot deve se parecer com isso:

   

Etapa 8: publicar seu bot atualizado

Para ativar a resposta, publique o bot atualizado.

Para publicar o bot

1. Clique em Concluído no canto superior direito do Criador de fluxos.
2. Na página do bot, clique em Publicar bot.
3. Clique em Publicar.

Tarefa 5: teste das alterações feitas

Depois de publicar as alterações, você pode testar a nova resposta perguntando “Como está o clima?“ em uma conversa com o bot atualizado. Para mais informações sobre testar bots de mensagens, leia Teste da experiência de mensagens do usuário final.