Integrar chamadas telefônicas a um chatbot do Dialogflow por meio de WebSockets

Introdução

Este tutorial vai mostrar como fazer uma ligação para um agente do Dialogflow usando o Dialogflow Essentials e uma integração com o WebSockets da Vonage.

O diagrama abaixo apresenta uma visão geral da arquitetura.

Diagram of the call

Pré-requisitos

Para realizar as ações descritas nas etapas a seguir, você precisará criar:

1. A Account do Dialogflow

2. A Account da API da Vonage

Criar um agente do Dialogflow

O Dialogflow é um Software como Serviço (SaaS) e uma plataforma de compreensão de linguagem natural utilizada para criar interfaces de usuário conversacionais.

Um agente é uma instância do Dialogflow, que você pode considerar como seu aplicativo de chatbot. Ele permite que você receba o que os usuários dizem e mapeie isso para intenções e fornecer respostas a eles.

Siga as etapas

1. Abra o console do Dialogflow

2. Crie um agente atribuindo-lhe um nome, definindo o idioma padrão, escolhendo o fuso horário e clicando no botão para criar o agente. O botão pode ser exibido como Create ou Create Agent

3. No menu à esquerda, clique no ícone de engrenagem

4. No Google Project, clique no nome do ID do projeto. Por exemplo, VonageDF Isso o levará ao Console do Google Cloud

Gif showing the steps to create the dialogflow Agent

Criar um Account de serviço no Google Cloud Console

Usaremos a interface gráfica do usuário para gerenciar nosso projeto e nossos recursos do Google Cloud por meio do console do Google Cloud, utilizando o mesmo projeto criado no Dialogflow. Nas etapas a seguir, criaremos uma conta de serviço para controle de acesso e autenticação.

Siga as etapas

1. No console do Google Cloud, clique em Go to project settings

2. No menu à esquerda, clique em Service accounts

3. Na barra superior, clique em + Create Service Account

4. Dê a ela um nome de Account de serviço que você consiga lembrar, por exemplo VonageDF

5. Adicionar uma descrição da conta de serviço

6. Clique em Create and Continue

7. Em Grant this service account access to project, filtre e selecione a função Dialogflow API Admin

Gif showing the seven above steps while creating the Service Account

Você será redirecionado para a página “Contas de serviço”

1. Clique nos três pontos abaixo de action

2. Clique em Manage keys

3. Clique em Add Key

4. Clique em Create new Key

5. Selecionar JSON

6. Clique em Create

7. Você pode ver que um .json arquivo foi baixado. Vamos adicionar esse arquivo ao repositório do GitHub “Dialogflow Reference Connection” que vamos clonar na próxima etapa

Gif showing the above steps to generate the keys

Configurar a conexão de referência do Dialogflow

A conexão de referência do Dialogflow utiliza o recurso WebSockets da Voice API da Vonage. Quando uma chamada de voz é estabelecida, um aplicativo da Voice API aciona uma conexão WebSocket com a Dialogflow-reference-connection. Ela transmite o áudio de e para a chamada de voz em tempo real.

Nas etapas a seguir, apresentaremos duas opções como exemplos: o uso do ngrok para criar um túnel para o servidor de conexão, que está interagindo com nosso agente do Dialogflow, e a implantação no Heroku.

Siga as etapas

1. Clone o repositório `dialogflow-reference-connection` do GitHub e mude de diretório git clone https://github.com/nexmo-community/dialogflow-reference-connection && cd dialogflow-reference-connection

2. Abra o código no seu IDE ou editor de texto preferido

3. Adicione o .json arquivo que acabou de baixar na raiz do projeto

4. Crie um .env arquivo a partir do .env.example

5. Defina as variáveis de ambiente: GCLOUD_PROJECT_ID=<TheProjectIdFoundOnDialogflow> GOOGLE_CLOUD_CREDENTIALS=<TheJSONFileYouDownloaded.json> No terminal:

6. Instale as dependências npm install

7. Execute o arquivo “Dialogflow connecting server” node df-connecting-server.js Existem vários tipos de implantação, como App Engine, Heroku e Cloud Run.

Neste tutorial, apresentaremos exemplos utilizando o ngrok . Aqui está um link com mais informações sobre o ngrok e o Heroku.

Opção 1: Exemplo com o ngrok

1. Correr ngrok http 5000

2. Anote a URL encontrada no console (por exemplo, xxxx.ngrok.io). Adicionaremos essa informação no DF_CONNECTING_SERVER argumento da seção “Configurar o aplicativo de exemplo da Voice API do Dialogflow” do tutorial

The ngrok URL highlighted on the IDE

Opção 2: Exemplo com o Heroku

1. Instalar o git

2. Instalar a linha de comando do Heroku e faça login na sua conta do Heroku

3. Se você ainda não tiver um repositório Git local, crie um: git init

4. Comece criando este aplicativo no Heroku a partir da linha de comando, usando a CLI do Heroku. Observação: no comando abaixo, substitua thisappname por um nome exclusivo em toda a plataforma Heroku. heroku create thisappname

5. No painel do Heroku, onde a página do seu aplicativo é exibida, clique no Settings botão, adicione o seguinte Config Vars e defina-os com seus respectivos valores:

1. Implantar o aplicativo git push heroku master ou git push heroku main dependendo do nome do seu branch.

2. Anote a URL encontrada no console (por exemplo, thisappname.herokuapp.com). Adicionaremos essa informação no DF_CONNECTING_SERVER argumento da seção “Configurar o aplicativo de exemplo da Voice API do Dialogflow” do tutorial

Configure as credenciais do seu aplicativo da Voice API da Vonage e o número de telefone

Siga as etapas

1. Criar uma aplicação a partir do Painel da API da Vonage

2. Dê um nome ao aplicativo, por exemplo VonageDF

3. Clique no botão para gerar uma chave pública e uma chave privada; um private.key arquivo será baixado. Vamos adicioná-lo ao aplicativo de exemplo da Voice API do Dialogflow na próxima seção deste tutorial

4. Vincule um número de telefone a este aplicativo. Se você ainda não tiver um, no menu à esquerda, clique em Numbers e, em seguida, Buy Numbers e siga as etapas para comprá-lo

Vamos configurar o aplicativo de exemplo da Voice API do Dialogflow e voltaremos em breve ao painel de controle deste aplicativo da Vonage para adicionar mais informações.

Configurar o aplicativo de exemplo da Voice API do Dialogflow

Este aplicativo de exemplo utiliza a Voice API da Vonage para atender chamadas de voz recebidas e estabelecer uma conexão WebSocket para transmitir áudio de e para a conexão de referência do Dialogflow em cada chamada.

A código de conexão de referência do Dialogflow fará o seguinte:

• Enviar o áudio da fala do chamador para o agente do Dialogflow,

• Transmitir as respostas de áudio do agente do Dialogflow para o chamador por meio do WebSocket,

• Envie em tempo real as transcrições e as pontuações de sentimento da fala do interlocutor por meio de callbacks de webhooks para este Aplicativo de Exemplo da Voice API.

Assim que esse aplicativo estiver em execução, você ligará para o número de telefone vinculado ao seu aplicativo para interagir por voz com o seu agente do Dialogflow.

Usaremos o ngrok para criar um túnel para o servidor de conexão que está interagindo com nosso agente do Dialogflow, mas se você quiser ver um exemplo usando o Heroku, pode seguir as etapas descritas em Aplicativo de Exemplo da Voice API do Dialogflow no GitHub.

Siga as etapas

1. No seu terminal, clone o Aplicativo de Exemplo da Voice API do Dialogflow do GitHub e mude de diretório git clone https://github.com/nexmo-community/dialogflow-sample-voice-application && cd dialogflow-sample-voice-application Você pode continuar seguindo a explicação das etapas abaixo ou o arquivo README do Aplicativo de Exemplo da Voice API do Dialogflow

2. Adicione o private.key gerado no Painel da Vonage e baixado para o seu computador à raiz do projeto

3. A partir do .env.example criar um .env arquivo

4. Preencha as variáveis de ambiente com as informações disponíveis no Painel da API da Vonage

• O SERVICE_NUMBER é o número virtual que você comprou. Lembre-se de adicionar o código do país sem nenhum 00 ou + à frente

• O DF_CONNECTING_SERVER é o servidor da Referência do Dialogflow que você já tem em execução (aquele que você anotou anteriormente)

1. Instale as dependências npm install

2. Execute o df-application.js node df-application.js Abaixo, você encontra as próximas etapas para o ngrok e para o Heroku, respectivamente:

   Opção 1: A seguir, apresentamos as etapas utilizando o ngrok

3. Em uma aba separada do terminal, execute ngrok http 8000 Volte ao site do Painel de Controle da Vonage e, na seção “Recursos”:

4. Ative a opção “Voice” para habilitar esse recurso

5. Adicione a URL do ngrok em execução em dialogflow-sample-voice-application seguido de /answer no campo “URL da resposta”. Certifique-se de que a opção HTTP GET esteja selecionada.

6. Adicione a URL do ngrok em execução em dialogflow-sample-voice-application seguido de /event no campo “URL do evento”. Certifique-se de que a opção HTTP POST esteja selecionada.

7. Clique em “Salvar alterações”

Vonage Dashboard

Opção 2: Passos a seguir usando o Heroku

1. Em uma aba separada do terminal, se você ainda não tiver um repositório Git local, crie um: git init

2. Comece criando este aplicativo no Heroku a partir da linha de comando, usando a CLI do Heroku. Observação: no comando, substitua myappname por um nome exclusivo em toda a plataforma Heroku. heroku create myappname

3. No painel do Heroku, onde a página do seu aplicativo é exibida, clique no Settings botão, adicione o seguinte Config Vars e defina-os com os respectivos valores encontrados no seu .env arquivo.

Adicione também o parâmetro PRIVATE_KEY_FILE com o valor ./private.key

1. No painel do Heroku, onde a página do seu aplicativo é exibida, clique no Open App botão e copie a URL

2. Agora, vamos implantar o aplicativo. Volte ao site do Painel de Controle da Vonage e, na seção “Recursos”:

3. Ative a opção “Voice” para habilitar esse recurso

4. Esse nome de host (a URL que você acabou de copiar do Heroku) será usado seguido por /answer no campo “URL da resposta”. Certifique-se de que a opção HTTP GET esteja selecionada

5. Faça o mesmo para /event na URL do evento. Certifique-se de que a opção HTTP POST esteja selecionada

6. Clique em “Salvar alterações”

Vonage Dashboard

Aprimorando o agente do Dialogflow

Se você tentasse ligar para o número de telefone nesta etapa do tutorial, poderia interagir com o ponto inicial da conversa do ponto de vista do Dialogflow, o Default Welcome Intent.

Uma mensagem seria enviada de volta ao interlocutor com base na lista de respostas do usuário. No entanto, a conversa não seguiria um formato de troca de turnos, pois não dispomos de dados treinados para outras etapas da conversa.

Vamos dar um passo atrás e explorar alguns dos Concepts do Dialogflow para adicionar as frases que os usuários podem dizer, fornecer respostas a elas e incluir o final da conversa, para que você possa ver uma conversa completa ocorrendo em turnos.

Depois de criar um agente, você criará intenções que irão conduzir e moldar a conversa.

Quando um usuário faz uma fala, o Dialogflow associa o que está sendo dito a uma intenção, com base no processamento de linguagem natural (NLP) e nas frases de treinamento que um usuário poderia dizer para corresponder a essa intenção. Assim que a classificação da intenção é feita, uma resposta é enviada ao usuário.

Entidades são os tipos de informação que extrairemos da conversa. Para o caso de uso que veremos a seguir, estamos reservando uma mesa por meio de uma ligação telefônica. As informações que extrairemos da conversa são person, date e time.

Vamos aprimorar a intenção padrão de boas-vindas, criar uma intenção, definir as entidades, adicionar um desfecho à conversa e testá-la.

Siga as etapas

1. Abra o console do Dialogflow e certifique-se de que está no agente correto para este tutorial

2. Clique no Default Welcome Intent

3. Role a página para baixo, apague as respostas e adicione: Welcome to our Demonstration Restaurant. When and for whom would you like to book a table?

4. Clique em “Salvar”

5. Clique no item de menu “Intents”

6. Clique no botão “Nova intenção”

7. Dê a ele o nome de Table Booker

8. Em “Frases de treinamento”, adicione as seguintes frases de treinamento

   • Uma mesa para a Nicole no dia 10, às 13h, por favor.

   • Gostaria de reservar um horário às 14h do dia 10/12/2021 para o Joseph?

   • Gostaria de reservar uma mesa no dia 10/09/2020 às 16h para a Amanda. Você vai perceber que, ao digitar essas frases, algumas palavras ficarão destacadas com um contorno colorido; certifique-se de clicar duas vezes nessas palavras e verificar se as entidades corretas estão sendo usadas @sys.person, @sys.date e @sys.time.

9. Em “Ações e Parâmetros”, marque required a opção person, date e time

10. Adicione instruções para cada um dos parâmetros, pois, caso não tenham fornecido essa informação específica durante a conversa, eles serão solicitados a fornecê-la

Training phrases examples

1. Na resposta, você pode acrescentar o seguinte: Table booked for $person at $time on $date. Thank you!

2. Alternar Set this intent as end of conversation, abaixo das respostas

3. Clique em “Salvar”

Table Booker Intent Overview

Interaja por Voice com o agente do Dialogflow

Agora que já configuramos tudo, é hora de ligar para o seu número de telefone virtual e testá-lo. Vamos explicar o que está acontecendo e, em seguida, seguir nossa etapa final para fazer a ligação!

Ao ligar para o número de telefone vinculado ao seu aplicativo da Voice API para interagir com o Agente do Dialogflow, você ouvirá a mensagem de confirmação: Connecting your call, please wait.. Essa mensagem de conversão de texto em fala da plataforma API da Vonage é reproduzida assim que a plataforma atende sua ligação.

Assim que o WebSocket for estabelecido, a plataforma da API da Vonage reproduz a função de conversão de texto em fala Hello para o agente do Dialogflow (você, como chamador, não ouvirá isso).

Você acabou de configurar a função de leitura em voz alta pelo agente do Dialogflow.

Nesta etapa, você vai interagir com as intenções que configurou na seção anterior deste tutorial para reservar uma mesa.

Você verá as transcrições no console do aplicativo de referência de conexão do Dialogflow e também no console do aplicativo de exemplo da Voice API do Dialogflow.

Se você quiser ver os resultados da análise de sentimento, precisará habilitar a API do Cloud Natural no console do Google Cloud. Se ela não estiver habilitada, você receberá uma mensagem de erro semelhante a PERMISSION_DENIED: Cloud Natural Language API has not been used in project xxxx before or it is disabled.

Vamos passar para a etapa final e ver todos os elementos básicos em ação!

Siga as etapas

1. Ligue para o número de telefone vinculado ao seu aplicativo da Voice API e interaja com o agente do Dialogflow

2. Aqui está uma maneira possível de você testar a conversa:

   1. Vonage Websocket: Conectando sua chamada, aguarde, por favor.

   2. Bot: Bem-vindo ao nosso Restaurante de Demonstração. Para quando e para quem você gostaria de reservar uma mesa?

   3. Você: Gostaria de reservar uma mesa para as 10h do dia 01/09/2022 para a Tanya

   4. Resposta do bot: Mesa reservada para a Tanya às 10h do dia 01/09/2022. Obrigado!

   Fim da ligação

Parabéns

Você concluiu este tutorial sobre como fazer chamadas telefônicas para um agente do Dialogflow usando uma integração do Vonage com WebSockets.

Recursos

Você pode encontrar o exemplo de referência do Dialogflow e exemplo de aplicativo de voz no GitHub.

Consulte o guia de referência do WebSockets.

Confira a Um post no blog explicando o ngrok.

Você também pode conferir um exemplo semelhante usando um bot do Amazon Lex.

Espero que tenham gostado. Fiquem à vontade para entrar em contato comigo no Twitter ou participar do nosso canal da Comunidade no Slack.