Como habilitar a funcionalidade de Voice em um chatbot que opera apenas com texto

Visão geral

Saiba aqui como adicionar interação por Voice ao seu chatbot atual, que funciona apenas com texto.

Este aplicativo utiliza a Voice API da Vonage para recursos de reconhecimento de fala e conversão de texto em fala, permitindo que seu chatbot ouça as solicitações faladas dos usuários e reproduza as respostas.

São oferecidas mais de quarenta opções de idioma para habilitar a funcionalidade Voice do seu chatbot.

Neste tutorial, há dois exemplos de código de aplicativos da Voice API e um aplicativo simples de chatbot de texto; o primeiro aplicativo da Voice API se conectará ao serviço do aplicativo de chatbot simples, que simula solicitações/respostas cujo único objetivo é ilustrar como um chatbot real pode ser habilitado para voz, e o segundo exemplo de aplicativo da Voice API possui os mesmos recursos básicos de voz que o primeiro, você atualizará esse aplicativo para integrá-lo ao seu chatbot real para solicitações/respostas, usando o primeiro como referência.

O código de ambos os aplicativos da Voice API suporta chamadas de voz recebidas ou realizadas de/para usuários, conforme necessário para o seu caso de uso do chatbot.

Neste tutorial, vamos usar e fazer referência ao repositório do GitHub das aplicações da Voice API e ao repositório do GitHub do simulador de chatbot simples.

Pré-requisitos

Você vai precisar de:

• Node.js,

• Ngrok,

• um Account da API da Vonage,

• Opcionalmente, o Heroku para uma implantação hospedada.

A configuração de cada item pré-requisito é detalhada a seguir.

Instalação do Node.js

• Instale o nvm (Node Version Manager); se você estiver usando o sistema operacional Windows, consulte estas observações importantes

• Instale o Node.js versão 16 com o comando: nvm install 16

• Use o Node.js versão 16 com o comando: nvm use 16

  • Testamos as applications com a versão 16.15.1 do Node.js

Instalação do Ngrok

Para começar a testar rapidamente, você pode executar o aplicativo da Voice API e o aplicativo simulador de chatbot simples no seu computador local; no entanto, eles precisam estar acessíveis pela Internet para utilizar a Voice API da Vonage, por exemplo, para receber chamadas de webhook relacionadas a eventos como chamadas de voz recebidas, chamadas atendidas e transcrições de reconhecimento de fala. Você consegue essa funcionalidade instalando o serviço de tunelamento de Internet ngrok.

Cada aplicação precisará de seu próprio túnel ngrok.

Para configurar o ngrok:

• Instale o ngrok,

• Certifique-se de que está usando a versão mais recente do ngrok e não uma versão instalada anteriormente,

• Cadastre-se gratuitamente Account no ngrok,

• Verify seu endereço de e-mail por meio do e-mail enviado pelo ngrok,

• Recuperar seu Authoken,

• Execute o comando ngrok config add-authtoken <your-authtoken>

• Configure os dois túneis

• • Correr ngrok config edit

  • • Para criar um account gratuito no ngrok, adicione as seguintes linhas ao arquivo de configuração do ngrok (abaixo da linha “authoken”):

tunnels:
  	six:
  		proto: http
  		addr: 6000
  	eight:
  		proto: http
  		addr: 8000

• Para uma conta paga del ngrok, você pode definir nomes de host do ngrok que nunca mudarão a cada nova instância do ngrok; adicione as seguintes linhas ao arquivo de configuração do ngrok (abaixo da linha authoken) — defina os nomes de host (eles devem ser únicos) com os valores desejados:

  tunnels:
    	six:
    		proto: http
    		addr: 6000
    		hostname: youmustsetanamehere6.ngrok.io
    	eight:
    		proto: http
    		addr: 8000
    		hostname: youmustsetanamehere8.ngrok.io

  Copiar

Observação: O aplicativo da Voice API estará em execução na porta local 8000, e o aplicativo do chatbot simples estará em execução na porta local 6000

• Inicie os dois túneis do ngrok

• • Correr ngrok start six eight

  • Você verá linhas como... Interface da Web http://127.0.0.1:4040 Encaminhamento https://xxxxxxx.ngrok.io -> http://localhost:6000 Encaminhamento https://yyyyyyy.ngrok.io -> http://localhost:8000

  • Anote xxxxxxx.ngrok.io (sem o https:// inicial), que está associado à porta local 6000, pois ele será definido como BOT_SERVER nas próximas etapas abaixo,

  • Anote https://yyyyyyy.ngrok.io (com o https:// no início), que está associado à porta local 8000, pois será necessário nas próximas etapas abaixo.

Account da API da Vonage

Faça login na sua ou cadastre-se para obter uma Account da API da Vonage.

Acesse Seus aplicativos, acesse um aplicativo existente ou + Crie um novo aplicativo.

Na seção “Recursos” (clique em [Editar] caso não veja essa seção):

Ativar Voice

• Em “URL de resposta”, mantenha HTTP GET e insira https://<host>:<port>/answer (substitua <host> e <port> pelo nome de host público e, se necessário, pela porta pública do servidor onde o aplicativo de exemplo da Voice API está em execução), por exemplo, https://yyyyyyyy.ngrok.io/answer ou https://myappname.herokuapp.com/answer (veja as próximas seções) ou https://myserver2.mycompany.com:40000/answer (implantação em seus próprios servidores)

• Em “URL do evento”, selecione HTTP POST (em vez de HTTP GET) e digite https://<host>:<port>/event (substitua <host> e <port> pelo nome de host público e, se necessário, pela porta pública do servidor onde o aplicativo de exemplo da Voice API está em execução), por exemplo, https://yyyyyyyy.ngrok.io/eventou https://myappname.herokuapp.com/event consulte as próximas seções(consulte as próximas seções) ou https://myserver2.mycompany.com:40000/event (implantação em seus próprios servidores)

• Clique em [Gerar chave pública e privada] caso ainda não tenha criado nenhuma ou queira gerar novas, e salve como .private.key arquivo (observe o ponto inicial no nome do arquivo) na pasta que conterá o aplicativo da Voice API. IMPORTANTE: Não se esqueça de clicar em [Salvar alterações] na parte inferior da tela caso tenha criado um novo conjunto de chaves.

• Associe um número de telefone a este aplicativo, caso ainda não haja nenhum associado a ele.

Anote o ID da sua inscrição e o número de telefone vinculado (pois eles serão necessários na próxima seção).

Para as próximas etapas, você precisará de:

• Sua chave da API da Vonage (como API_KEY)

• Sua segredo da API da Vonage, e não um segredo de assinatura (como API_SECRET)

• Seu ID de aplicativo (como APP_ID),

• O número de telefone vinculado à sua aplicação (conforme SERVICE_NUMBER), seu celular ligará para esse número,

• O nome de host público e a porta do servidor do chatbot “Simple Text-Only” (conforme BOT_SERVER), o argumento não possui o prefixo http:// nem https://, não tem / no final e não contém nenhum subcaminho, por exemplo: xxxxxxx.ngrok.io ou mysimplebotname.herokuapp.com ou myserver1.mycompany.com:32000

Configuração do Heroku

Após realizar os testes localmente, mais tarde, você poderá, se desejar, fazer a implantação em ambientes hospedados no Heroku.

Para configurar o Heroku,

Instalar o.

Cadastre-se para criar uma conta no Heroku Account.

Instale o linha de comando do Heroku e faça login na sua conta do Heroku.

Para implantar as Applications, siga as instruções da seção “Implantar no Heroku”.

Desenvolvimento

Vamos ver como funcionam as Applications.

Primeira fase

Na primeira fase, vamos usar e implantar o aplicativo de referência voice-on-text-bot-app-with-simple-bot.js do repositório “Voice Enabling Text Bot Applications”, em conjunto com o aplicativo de chatbot simples `very-simple-bot.js`, do repositório “Voice-Enabling Text Bot Simple Chatbot”.

Implantação local no seu computador para ambos os Applications

Voice enabling text-only chatbot. Local deployment for tests

Baixe o código do aplicativo de referência do repositório para uma pasta local e, em seguida, acesse essa pasta.

Copie o env.example arquivo para um novo arquivo chamado .env (com um ponto no início): cp env.example .env

Edite o arquivo .env e defina os valores dos cinco parâmetros (consulte as seções anteriores):

API_KEY=

API_SECRET=

APP_ID=

BOT_SERVER=

SERVICE_NUMBER=

Instale as dependências uma única vez:

npm install

Certifique-se de que o ngrok tenha sido iniciado com os dois túneis, conforme explicado nas seções anteriores.

Inicie o aplicativo:

node voice-on-text-bot-app-with-simple-bot.js

Baixe o código do aplicativo simples de chatbot do repositório para uma pasta local e, em seguida, acesse essa pasta.

Inicie o aplicativo:

node very-simple-bot.js

Para interagir por meio de chamadas de voz com esse bot bem simples, ligue para o número de telefone vinculado ao seu aplicativo, aquele indicado como SERVICE_NUMBER.

Implantar no Heroku

Opcionalmente, você pode implantar ambas as aplicações em ambientes hospedados no Heroku.

Certifique-se primeiro de que suas aplicações funcionem conforme o esperado na implantação local em seu computador e de que você tenha configurado o Heroku conforme os pré-requisitos.

Vá até a pasta onde está o aplicativo da Voice API,

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

git init

git add .

git commit -am "initial"

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

heroku create myappname

ou heroku create myappname --team <xxxxx> (se seu account do Heroku usa equipes)

No painel do Heroku, onde a página do seu aplicativo é exibida, clique no botão “Configurações”, adicione as seguintes variáveis de configuração e defina-as com seus respectivos valores:

API_KEY

API_SECRET

APP_ID

BOT_SERVER (see further below)

SERVICE_NUMBER

PRIVATE_KEY_FILE with the value ./.private.key

Agora, implante o aplicativo:

git push heroku master

No seu painel do Heroku, onde a página do seu aplicativo é exibida, clique no botão “Abrir aplicativo”. Esse nome de host é o que deve ser usado na sua Recursos do aplicativo da Voice API da Vonage (clique na aplicação correspondente e, em seguida, em [Editar]).

Por exemplo, os links correspondentes seriam (substitua myappname pelo valor real):

https://myappname.herokuapp.com/answer

https://myappname.herokuapp.com/event

Veja mais detalhes na seção acima sobre o Account da API da Vonage.

Vá até a pasta onde está o aplicativo de chatbot bem simples,

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

acesse a pasta deste aplicativo bot simples

git init

git add .

git commit -am "initial"

Crie este aplicativo no Heroku a partir da linha de comando usando a CLI do Heroku:

Observação: No comando a seguir, substitua “mysimplebotname” por um nome exclusivo em toda a plataforma Heroku.

heroku create mysimplebotname

ou heroku create mysimplebotname --team <xxxxx> (se seu account do Heroku usa equipes)

Implantar o aplicativo

git push heroku master

Nesse caso, ao configurar o aplicativo da Voice API, o parâmetro BOT_SERVER para a outra implantação no Heroku será mysimplebotname.herokuapp.com (substitua mysimplebotname pelo valor real; não há https:// no início nem / no final)

Para interagir por meio de chamadas de voz com esse bot muito simples, ligue para o número de telefone vinculado ao seu aplicativo, aquele indicado como SERVICE_NUMBER.

Como funcionam as Applications

O aplicativo voice-on-text-bot-app-with-simple-bot.js:

• Utiliza a Voice API da Vonage com o SDK para servidor Node.js ‘@vonage/server-sdk’,

• Valores predefinidos para:

  • Código de idioma do ASR (Reconhecimento Automático de Fala) e do TTS (Conversão de Texto em Fala), como ‘languageCode’,

  • Saudação inicial, como ‘greetingText’,

  • e outros parâmetros, conforme indicado nos comentários.

• Gerencia rotas de webhooks:

  • ‘/makecall’

    • Se você quiser fazer chamadas

    • Atualize o número no objeto callInfo. Deve ser o número internacional completo (formato E.164), com o código do país, sem o sinal “+” no início, sem prefixos de discagem internacional como “011” ou “00”, sem traços “-” ou espaços

    • Ele chamará a rota de “/placecall”

      • Para iniciar a chamada, em um navegador da web, digite o endereço: <this-application-host-name>/placecall, por exemplo, xxxxxxx.ngrok.io/makecall

• ‘/placecall’

  • É aqui que a solicitação à Voice API para uma chamada de saída de voz é efetivamente feita.

• ‘/resposta’

  • Essa rota de webhook é acionada pela plataforma da Voice API da Vonage ao ocorrer uma chamada de voz recebida ou quando uma chamada de voz efetuada é atendida,

  • O segmento da chamada (Voice API) é identificado pelo seu valor UUID,

  • O aplicativo retorna um NCCO onde:

    • É reproduzida uma saudação para o interlocutor remoto com “action”: “talk”,

    • Inicia um ciclo de ASR (Reconhecimento Automático de Fala) com “action”: “input”,

A plataforma da Voice API chamará a URL do webhook conforme especificado no eventUrl parâmetro (rota /asr), independentemente de ter sido detectada fala ou não.

• ‘/evento

  • Essa rota de webhook é acionada pela plataforma da Voice API da Vonage em diferentes estados do segmento de chamada de voz com um determinado valor de UUID,

  • Nesta aplicação, não há ações em resposta a essa rota de webhook, exceto o retorno do código HTTP 200 (ok).

• ‘/asr’

  • Essa rota de webhook é acionada pela plataforma da Voice API da Vonage com base nos resultados do ASR (Reconhecimento Automático de Fala), independentemente de uma transcrição ter sido retornada com sucesso ou não; por exemplo, pode ter havido ruídos em vez de palavras realmente faladas ou pode ter ocorrido um tempo limite caso nenhum som tenha sido detectado (a duração do tempo limite corresponde ao parâmetro startTimeout )

  • Ele inicia um novo ciclo de ASR retornando um NCCO com “action”: “input”

• ‘/botreply’

  • Essa rota de webhook é chamada pelo chatbot simples para retornar uma resposta em texto a uma solicitação de texto,

  • Em seguida, ele inicia um TTS (Text-to-Speech) para reproduzir a resposta do chatbot.

• Neste aplicativo, configure o código de idioma do ASR (Reconhecimento Automático de Fala) e o código de idioma do TTS (Text-to-Speech) (parâmetro languageCode) que correspondam ao idioma do seu chatbot de texto. Mais de 40 configurações regionais de idioma estão disponíveis na Voice API da Vonage, tanto para ASR quanto para TTS.

• As duas últimas linhas de código permitem que esta aplicação Node.js escute na porta local 8000 para implantação local ou em uma porta local diferente para uma implantação hospedada (configurada automaticamente em uma implantação no Heroku).

O aplicativo very-simple-bot.js:

• Simula um chatbot apenas de texto. Seu único objetivo é mostrar como um chatbot real, apenas de texto, seria habilitado para voz com o aplicativo que utiliza a Voice API da Vonage,

• Este exemplo de chatbot muito simples oferece suporte aos idiomas inglês e francês, a título de exemplo

• As únicas solicitações compatíveis estão listadas nos respectivos dicionários botKbEn e botKbFr,

• Este chatbot, que é bem simples, não utiliza Processamento de Linguagem Natural para fins de teste. Você deve digitar exatamente uma das solicitações esperadas e suportadas. Caso contrário, a resposta será a padrão para solicitações desconhecidas,

• Ele processa o webhook ‘/bot’ para receber solicitações; ele fará uma chamada de retorno para a URL do webhook indicada na solicitação recebida para fornecer a resposta de texto correspondente,

• As duas últimas linhas de código permitem que esta aplicação Node.js escute na porta local 6000, no caso de uma implantação local, ou em uma porta local diferente, no caso de uma implantação hospedada (definida automaticamente em uma implantação no Heroku).

Segunda fase

Voice Enabling text-only chatbot. Hosted/ Production deployment.

Na segunda fase, você atualizará (onde indicado no texto) o código-fonte voice-on-text-bot-app-generic.js para interagir com seu chatbot real em relação a solicitações e respostas de texto e utilizará o voice-on-text-bot-app-with-simple-bot.js como referência; ambos estão no repositório do aplicativo.

Você não precisará de nenhum código do repositório do simulador de bot simples.

Você vai interagir por Voice com o seu chatbot ligando para o número de telefone vinculado ao seu aplicativo, aquele indicado como SERVICE_NUMBER.

Conclusão

Neste tutorial, você aprendeu que, usando a Voice API da Vonage, é possível habilitar a funcionalidade de voz em qualquer chatbot que funcione apenas com texto, e que vários idiomas são suportados.

Você começa, primeiro, com uma implantação local no seu computador, utilizando o aplicativo da Voice API e o chatbot de texto simples, para ilustrar como é possível habilitar a funcionalidade de voz em um chatbot de texto.

Você pode, se desejar, fazer a implantação em ambientes hospedados no Heroku.

Em seguida, você atualizará o outro aplicativo da Voice API para adicionar apenas o código específico necessário para a integração com seu chatbot de texto para solicitações e respostas em texto, já que toda a interação necessária com a Voice API da Vonage — incluindo o gerenciamento de chamadas de voz recebidas e realizadas, o reconhecimento automático de fala e a conversão de texto em fala — já foi implementada nesse arquivo de código-fonte.

O que você achou deste tutorial? Tem alguma dúvida ou comentário sobre como habilitar a funcionalidade de Voice em um chatbot apenas de texto? Junte-se a nós no Slack para desenvolvedores da Vonage. E siga-nos no Twitter para ficar por dentro das últimas atualizações do Vonage Developer