Como enviar mensagens SMS com Ruby on Rails

Apesar do crescimento de aplicativos de mensagens como o WhatsApp e o Facebook Messenger, o SMS continua sendo essencial. Ele funciona em qualquer dispositivo móvel sem a necessidade de software adicional, apresenta maior engajamento para mensagens urgentes e é a opção mais confiável, já que não requer conexão com a internet.

Este tutorial mostra como enviar mensagens SMS em um aplicativo Ruby on Rails usando o Vonage. Esta é a primeira publicação da série “Guia de Início Rápido do Vonage para Ruby on Rails”, que tem como objetivo ajudá-lo a dar os primeiros passos com as funcionalidades principais do conjunto de APIs do Vonage em seu aplicativo Ruby on Rails.

Resumo Pule esta parte e veja todo o códigos do Guia de Início Rápido no GitHub

Observe que esta série de tutoriais utiliza a Messages API, que integra facilmente o suporte omnicanal. A Vonage também oferece a SMS API.

A demonstration of the Vonage Rails Quickstart application sending an SMS message in real time.

Pré-requisitos

• Ruby e Rails instalados no seu computador. Para qualquer dúvida sobre as convenções do Rails, a documentação é bastante completa. 

• Um número virtual da Vonage.

Como criar uma aplicação em Ruby on Rails

Este tutorial pressupõe que você tenha um conhecimento básico de Ruby e Rails, limitando-se aos comandos necessários, sem entrar em explicações muito detalhadas.

Primeiro, vamos criar nosso novo projeto.

rails new vonage-rails-quickstart

Em seguida, acesse o projeto e adicione a gem Vonage ao seu Gemfile para que possamos acessar o SDK da Vonage. Também vamos adicionar o `dotenv-rails` para que possamos usar variáveis de ambiente com segurança.

#Gemfile
gem 'vonage'
gem 'dotenv-rails', groups: [:development, :test]

Em seguida, execute o bundler para instalar nossas gems.

bundle install

Agora, precisaremos criar nosso modelo SmsMessage, que define seus atributos e como eles são armazenados no banco de dados. Precisaremos de 6 campos:

• para: o destinatário da mensagem SMS.

• de: o remetente da mensagem SMS.

• texto: o conteúdo da mensagem.

• status: se uma mensagem SMS foi entregue com sucesso ou não. Veja mais informações na Referência da API.

• message_uuid: o ID da Vonage associado à mensagem, que será importante para acompanhar o status das mensagens.

• is_inbound: se a mensagem é enviada ou recebida pelo nosso aplicativo; isso será importante na próxima postagem do blog.

rails g model SmsMessage to:string from:string text:text status:string message_uuid:string is_inbound:boolean  

Também precisaremos atualizar nosso banco de dados com o novo modelo.

rails db:migrate

Vamos criar nosso controlador para lidar com nossa lógica.

rails g controller OutboundSms new create

Por fim, vamos definir nossas rotas para SMS de saída.

# config/routes.rb

Rails.application.routes.draw do
 # For OutboundSms controller, new & create
  get  '/outbound_sms/new', to: 'outbound_sms#new',    as: :new_outbound_sms
  post '/outbound_sms',     to: 'outbound_sms#create', as: :outbound_sms
end

Como criar uma aplicação da Vonage

Agora que nosso aplicativo Rails está pronto, também precisaremos criar e configurar nosso aplicativo Vonage. Primeiro, precisamos criar nosso aplicativo no Painel do Vonage. Dê um nome ao aplicativo e ative o recurso “Mensagens”. Por enquanto, você pode adicionar URLs provisórias para os webhooks. Atualizaremos esses detalhes em posts futuros do blog.

The Vonage Developer dashboard showing the creation of a new application with authentication, privacy, and messaging capabilities settings.

Certifique-se de gerar um arquivo private.key clicando em “Gerar chave pública e privada”. Isso fará com que um arquivo private.key seja baixado para o seu computador. Em seguida, mova o arquivo private.key para a raiz do seu aplicativo Rails.

Quando seu aplicativo for criado, anote o ID do aplicativo. Você precisará do ID do aplicativo, da sua chave de API e do seu segredo de API na próxima etapa.

Crie um arquivo .env na raiz da sua aplicação Rails:

touch .env

Por fim, adicione as seguintes chaves com suas credenciais.

#.env

VONAGE_APPLICATION_ID=''
VONAGE_PRIVATE_KEY='./private.key'

Como inicializar o cliente Ruby da Vonage

O cliente da API REST nos permite acessar facilmente 15 APIs da Vonage, e não apenas a Messages API. Você pode saber mais sobre as APIs compatíveis.

Antes de habilitar o cliente Ruby em uma aplicação Rails completa, vamos ver como podemos usá-lo de maneira mais geral em código Ruby. Para usar o cliente, basta inicializar uma instância com as informações da nossa aplicação armazenadas no nosso arquivo de ambiente.

 vonage = Vonage::Client.new(
 	application_id: ENV["VONAGE_APPLICATION_ID"],
private_key: ENV["VONAGE_PRIVATE_KEY"]
)

Como enviar uma mensagem SMS em Ruby

Agora que nosso cliente está inicializado, enviar um SMS se torna bastante simples. Chamamos o método para instruir o cliente a usar a Messages API e, em seguida, chamamos o método `send` com os campos necessários.

# app/controllers/outbound_sms_controller.rb
response = vonage.messaging.send(
   "message_type": "text",
   "text": "Hello from Vonage!",
   "to": "447700900000",
   "from": "447700900001",
   "channel": "sms"
)

Você pode ver todas as opções para os diferentes canais e campos na Referência da API.

Envio de SMS em um aplicativo Ruby on Rails

Agora que já vimos como usar o cliente Ruby da Vonage para enviar SMS, vamos integrar uma funcionalidade de envio de SMS em Ruby on Rails ao nosso aplicativo, usando um formulário e um controlador simples. Precisaremos de uma interface de usuário agradável para lidar com o para, dee texto . Você pode copiar e adicionar o formulário ao seu /app/views/outbound_sms/new.html.erb e CSS associado.

A Vonage-powered SMS form where users can input a sender's phone number or name, the recipient's phone number, and a message before sending an SMS.

Observação: Nem todos os países aceitam um nome como campo “para” válido 

Agora, vamos implementar a lógica para que nosso formulário funcione. Primeiro, precisamos criar uma instância vazia do SMS para carregar o formulário. Em seguida, chamamos o método `create`, que salva o SMS em nosso banco de dados e, depois, o envia por meio do método .

#app/controllers/outbound_sms_controller.rb 

 def new
    @sms_message = SmsMessage.new
 end

  def create
    # Create a SMS record to be stored in the database
    @sms_message = SmsMessage.new(safe_params)

    if @sms_message.save
      deliver @sms_message
      redirect_to :new_outbound_sms, notice: 'SMS Sent'
    else
      flash[:alert] = 'Something went wrong'
      render :new
    end
  end

  private

 def safe_params
    params.require(:sms_message).permit(:to, :from, :text)
 end

A método é basicamente o mesmo que usamos na seção anterior, exceto que agora utilizamos o método Messages objeto e lidamos com a resposta da API.

Se a mensagem for enviada com sucesso, é retornado um código de status 202, juntamente com um UUID da mensagem. Esse UUID ajuda a rastrear o status da entrega usando o Status da Mensagem, que abordaremos no próximo post.

 def deliver(sms_message)
    message = vonage.messaging.sms(message: sms_message.text)

    response = vonage.messaging.send(
      from: sms_message.from,
      to: sms_message.to,
      **message
    )

    if response.http_response.code == '202'
      sms_message.update(
        message_uuid: response.entity.attributes[:message_uuid]
      )
    end
end

> Veja o arquivo completo outbound_sms_controller.rb .

Agora inicie seu servidor Rails:

rails s

E abra http://localhost:3000/outbound_sms/new no seu navegador. Você já pode começar a enviar SMS pelo seu aplicativo Ruby on Rails!

Conclusão

Você conseguiu! Você aprendeu a criar um aplicativo Vonage, a inicializar e usar o cliente Vonage para Ruby e a enviar SMS com sucesso a partir de um aplicativo Ruby on Rails. Em posts futuros, vamos adicionar mais recursos de SMS e Voice a este aplicativo.

Se você tiver alguma dúvida ou sugestão para mais conteúdos sobre Ruby, envie-nos uma mensagem no Slack da Comunidade. Você também pode ficar por dentro do nosso conteúdo para desenvolvedores e dos eventos no X, anteriormente conhecido como Twitter.