Crie uma aplicação de conversão de texto em fala com o Hanami

Este tutorial mostrará como criar um aplicativo de conversão de texto em fala usando o Hanami, o SDK Ruby da Vonage e a Voice API. Para este tutorial, será necessário criar um aplicativo da Vonage com recursos de voz.

Você também pode encontrar o código e o aplicativo totalmente funcional apresentado neste tutorial no GitHub.

Pré-requisitos

• Aplicativo Vonage Voice

• Número de telefone fornecido pela Vonage

• Ruby e Hanami instalados no seu computador

• Ngrok

O que é o Hanami?

Hanami é uma estrutura web em Ruby com recursos completos. Ela oferece uma alternativa ao Ruby on Rails que é mais leve e consome menos memória. É baseada na mesma metodologia MVC (modelos, visualizações e controladores) do Rails. Uma de suas principais diferenças de design é que ele divide a funcionalidade em suas menores partes possíveis. Como resultado, um aplicativo web Hanami pode ter mais arquivos para realizar a mesma tarefa que um aplicativo web Rails, mas cada arquivo é responsável pelo mínimo possível. Isso torna o rastreamento de bugs, a adição de recursos e a refatoração mais eficientes.

Não é incomum encontrar modelos e controladores extensos em uma aplicação Ruby on Rails. Muitas vezes, grande parte desse código é reestruturado para uma área de serviços ou classes auxiliares. No entanto, em uma aplicação Hanami, devido ao seu design geral, é bastante difícil acabar enchendo um único modelo ou um único controlador com tanto código a ponto de torná-lo difícil de manejar.

Criar uma aplicação de voz da Vonage

Para criar um aplicativo web que utilize a Voice API da Vonage, precisaremos criar um aplicativo de voz da Vonage no Painel de Controle. Acesse Seus Applications no menu da barra de navegação lateral. Gere um novo aplicativo com o nome de sua escolha e, em seguida, selecione “Gerar chave pública e privada”. Isso fará com que o private.key arquivo para o seu computador. Assim que começarmos a criar nossa aplicação Hanami, vamos mover esse arquivo para a pasta raiz dela.

Certifique-se de ativar o recurso “Voice” em Recursos ao criar o aplicativo. Quando terminar, clique em Salvar. Se você esquecer de clicar em Salvar, as informações das chaves pública e privada não serão salvas no aplicativo da Vonage, e você precisará gerar um novo par de chaves pública e privada novamente.

Os aplicativos de voz da Vonage exigem que sejam fornecidos endereços de webhooks acessíveis externamente para receber os dados da Voice API da Vonage. Neste tutorial, não faremos nada com esses dados. Ainda assim, é uma boa prática em ambientes de produção, ao trabalhar com webhooks, pelo menos confirmar o recebimento das informações enviadas pela API. Você pode usar o ngrok para tornar seu ambiente de desenvolvimento local acessível externamente ao criar ou trabalhar em um aplicativo. Se você nunca usou o ngrok antes, pode seguir este tutorial para obter instruções sobre como configurá-lo e usá-lo em seu aplicativo Vonage.

Depois de concluir a criação do aplicativo de Voice no Painel, você receberá um ID do aplicativo. Esse ID será importante no nosso aplicativo, portanto, anote-o.

Agora que já temos um aplicativo Vonage Voice e um número virtual da Vonage, estamos prontos para desenvolver nosso aplicativo!

Criar um aplicativo Hanami

O primeiro passo em nosso novo aplicativo é inicializá-lo. Na linha de comando, execute:

Isso criará um novo diretório chamado voice_app de onde executamos este comando, com a estrutura básica de um aplicativo web que usa o PostgreSQL como banco de dados. Vá para esse diretório e abra-o com seu editor de código preferido.

Agora podemos começar a escrever o código para nosso aplicativo de conversão de texto em fala.

Instale o SDK Ruby da Vonage

A primeira tarefa que queremos realizar é adicionar o SDK do Vonage para Ruby como uma dependência gem ao Gemfile.

Abra a Gemfile na pasta raiz e adicione gem 'vonage' a ele. Depois de fazer isso, você pode executar bundle install a partir da linha de comando.

Para instanciar um cliente SDK da Vonage autenticado, capaz de realizar chamadas de voz, precisamos fornecer algumas credenciais da API da Vonage. O private.key arquivo que você baixou do Painel da Vonage agora pode ser movido para a pasta raiz do seu aplicativo Hanami. Também precisamos fornecer nosso ID de aplicativo da Vonage e, aproveitando o momento, adicionaremos nosso número de telefone da Vonage. Se ainda não houver um, crie um .env arquivo na pasta raiz ou abra o arquivo atual e adicione o seguinte:

VONAGE_APPLICATION_ID=Your Vonage Application ID Goes Here
VONAGE_PRIVATE_KEY=./private.key
VONAGE_NUMBER=Your Vonage Number Goes Here

Você precisa substituir o texto após cada sinal de igual pelo valor desejado. Você pode manter o valor do VONAGE_PRIVATE_KEY , já que ele aponta corretamente para o seu arquivo de chave privada.

Prepare o banco de dados

Nesta etapa, vamos preparar nosso banco de dados para o aplicativo. Usaremos o banco de dados para armazenar uma lista de opções de idiomas para nosso aplicativo de conversão de texto em fala. Os usuários poderão escolher qualquer um dos idiomas disponíveis no banco de dados para criar uma mensagem a ser enviada por meio de uma ligação telefônica.

Vamos criar um novo modelo que armazenará as informações sobre nossos idiomas. No Hanami, a lógica de um modelo de banco de dados é armazenada em um entity, e os dados são armazenados em um repository. Um entity é desacoplado do banco de dados, enquanto o repository é o próprio nível de dados.

Para gerar nosso modelo de linguagem, podemos usar o gerador Hanami novamente, executando bundle exec hanami generate model language.

Isso criará uma nova entidade em lib/voice_app/entities chamada language.rb, um novo repositório em lib/voice_app/repositories chamado language_repository.rb e uma nova migração de banco de dados em db/migrations. O arquivo de migração começará com um carimbo de data/hora e terminará com create_languages.rb. O gerador também cria alguns arquivos de especificação para nós.

Precisamos abrir o arquivo de migração e editá-lo para incluir colunas para o nome do idioma e o idioma designação de código .

O arquivo de migração terá a seguinte aparência quando você o abrir pela primeira vez:

Hanami::Model.migration do
  change do
    create_table :languages do
      primary_key :id

      column :created_at, DateTime, null: false
      column :updated_at, DateTime, null: false
    end
  end
end

Após a primary_key :id linha, adicione o código para criar duas novas colunas de dados:

column :name, String, null: false
column :code, String, null: false

Você pode salvar o arquivo e, em seguida, executar o comando a seguir para criar nosso banco de dados com a tabela “languages” e as colunas que adicionamos:

Por fim, vamos adicionar alguns idiomas ao nosso banco de dados. A maneira mais rápida de fazer isso agora é acessar o console do Hanami pelo terminal e adicionar alguns. Você pode escolher entre a lista de idiomas disponíveis no Portal do Desenvolvedor da API da Vonage ou usar os que constam no código de exemplo abaixo. Primeiro, para acessar o console, execute bundle exec hanami console na linha de comando. Em seguida, para criar os dados, execute o código a seguir, usando os idiomas de exemplo no trecho de código abaixo ou substituindo-os pelos que você escolheu:

>> repository = LanguageRepository.new
>> repository.create(language: 'English', code: 'en-US')
>> repository.create(language: 'Danish', code: 'da-DK')
>> repository.create(language: 'Tamil', code: 'ta-IN')
>> exit

Agora temos um banco de dados de idiomas criado em nosso novo aplicativo e estamos prontos para avançar para a próxima etapa: a geração das visualizações.

Criar as ações da Web

Neste tutorial, vamos criar ações estruturadas na home pasta que vem com o Hanami para manter nosso código simples. Assim, para nossa primeira ação, que corresponde à nossa / , usaremos o gerador do Hanami na linha de comando para criar uma index ação. Isso criará um controlador para a index visualização e o modelo HTML correspondente dentro de app/web/templates/home/index.html.erb.

Além disso, esse gerador também adicionará automaticamente uma rota para nós dentro de app/web/config/routes.rb: get '/', to: 'home#index'.

Executamos o seguinte código para criar o que está acima: bundle exec hanami generate action web home#index.

Vamos aproveitar esse momento para criar as outras ações necessárias para o nosso aplicativo. Resumindo, precisamos do seguinte:

• new: A POST ação para o formulário que os usuários enviarão com suas informações de contato

• create: A ação para criar uma nova chamada de conversão de texto em fala com os dados do formulário

• success: A ação que exibirá a visualização após a inicialização da chamada

Para criá-los, execute o código a seguir. Cada um está dividido em uma linha separada para maior clareza:

Cada uma das ações do gerador mencionadas acima criou sua própria estrutura de pastas para o controlador e o modelo, assim como a primeira index ação.

Criar as visualizações

Vamos adicionar código HTML para duas visualizações do nosso aplicativo. A primeira visualização será a visualização raiz index , e a segunda será a success exibida após o envio do formulário.

Abra o /apps/web/templates/home/index.html.erb arquivo e adicione o seguinte:

<h1>Text-to-Speech Calls on Hanami</h1>

<p>Let's make a phone call!</p>

<form action="/create" method="post">
  <label for="number">Enter a recipient number:</label>
  <input type="text" id="number" name="number">
  <br />
  <label for="language">Choose a language:</label>
  <select id="language" name="language">
    <% languages.each do |voice| %>
      <option value=<%= language.code %>><%= language.name %></option>
    <% end %>
  </select>
  <br />
  <label for="message">Enter a message:</label>
  <textarea id="message" name="message" col="10">
  </textarea>
  <br />
  <input type="submit" value="Submit">
</form>

A index visualização contém um pequeno formulário HTML com três campos de entrada e um botão de envio. O primeiro campo é o número que o usuário deseja discar. O segundo campo é a seleção do idioma. Por fim, o terceiro campo é a mensagem a ser transmitida durante a ligação.

A lista suspensa de idiomas no segundo campo de entrada é gerada a partir dos idiomas presentes em nosso repositório de idiomas. No entanto, você notará que eles são acessados por meio de uma variável local voices na visualização. De onde veio essa variável? Vamos tornar essa variável acessível na próxima etapa deste tutorial.

Agora, vamos adicionar a success visualização. Abra o arquivo /apps/web/templates/home/success.html.erb e adicione o seguinte:

<p>Congrats, you sent your message!</p>
<br />
<p>Care to <a href="/">try again?</a>

Esta tela exibe uma mensagem de parabéns pela conclusão da ligação e um convite para tentar novamente.

Vamos adicionar a lógica aos nossos controladores para que a voices variável local funcione na visualização e realize a ligação telefônica.

Definir a lógica do controlador

Como mencionamos na etapa anterior, precisamos fornecer o contexto da variável na index visualização. Caso contrário, nosso aplicativo a considerará indefinida. Fazemos isso definindo uma variável de instância no index controlador dentro apps/web/controllers/home/index.rb. São necessárias duas etapas. Primeiro, precisamos expor os dados ao controlador. O Hanami não pressupõe que todo controlador precise acessar todos os armazenamentos de dados; por isso, exige que você defina explicitamente quais dados um controlador pode acessar. Segundo, precisamos instanciar uma variável no #call método com os dados.

É assim que o index controlador:

module Web
  module Controllers
    module Home
      class Index
        include Web::Action

        def call(params)
        end
      end
    end
  end
end

Após a include Web::Action linha, adicione outra linha com expose :languages. Isso tornará a tabela do banco de dados de idiomas disponível para o nosso controlador. Em seguida, dentro da #call ação, adicione o seguinte: @languages = LanguageRepository.new.all para passar todos os idiomas do repositório para a index visualização.

Agora, vamos incorporar o SDK do Vonage para Ruby ao create controlador. Vamos instanciar uma instância autenticada do SDK e usá-la para gerar a chamada telefônica com o texto do usuário enviado durante a chamada por meio da conversão de texto em fala. Você pode adicionar o seguinte ao seu apps/web/controllers/home/create.rb arquivo:

require 'vonage'

module Web
  module Controllers
    module Home
      class Create
        include Web::Action

        def call(params)
          client = Vonage::Client.new(
            application_id: ENV['VONAGE_APPLICATION_ID'],
            private_key: ENV['VONAGE_PRIVATE_KEY']
          )

          response = client.voice.create(
            to: [{
              type: 'phone',
              number: params[:number]
            }],
            from: {
              type: 'phone',
              number: ENV['VONAGE_NUMBER']
            },
            ncco: [{
              action: 'talk',
              text: params[:message],
              language: params[:language]
            }]
          )

          redirect_to '/success'
        end
      end
    end
  end
end

Na primeira linha do trecho de código, nós require o SDK Ruby da Vonage. Em seguida, dentro do #call método, criamos nosso cliente e, em seguida, usamos o Client SDK voice#create para enviar a chamada. O voice#create método segue a especificação da API da Voice API nos parâmetros obrigatórios e opcionais que ela aceita. No mínimo, o método requer:

• to parâmetro: Um array que contém um hash com type e number chaves

• from parâmetro: Um hash com duas chaves de type e number

• ncco parâmetro: Um array com um hash que contém as instruções enviadas à Voice API.

A especificação da API, bem como a referência da NCCO, são bons pontos de partida para descobrir todos os valores possíveis que podem ser utilizados ao criar sua chamada de voz.

Executando o aplicativo

Agora você está pronto para executar seu aplicativo! Para iniciar seu aplicativo web Hanami, execute o seguinte comando no terminal:

O comando acima iniciará um servidor web na porta 2300. Agora você pode usar seu navegador para acessar http://localhost:2300. Você verá o formulário que criou para enviar texto para fala por meio de uma ligação telefônica. Vá em frente e preencha-o, talvez usando seu número de telefone como número do destinatário. Depois de clicar em “Enviar”, você deverá receber a ligação com sua mensagem, e seu navegador deverá ser redirecionado para a success página de visualização.

Parabéns! Você criou um aplicativo de voz totalmente funcional usando o recurso de conversão de texto em fala da Voice API da Vonage com o Hanami.

E agora?

Agora que você começou a explorar as possibilidades da Voice API da Vonage, ainda há muito mais para descobrir. Os recursos a seguir podem ser um bom ponto de partida para continuar sua jornada:

• Resposta Interativa por Voz

• Bots de chamada / Assistentes de voz

• Utilizando WebSockets

• Reconhecimento de fala

• Criar um correio de voz com Ruby on Rails