Como receber mensagens SMS com Ruby on Rails

Agora que seu aplicativo Ruby on Rails já consegue enviar SMS e acompanhar o status das mensagens, o próximo passo é lidar com as mensagens recebidas. Afinal, de que adianta enviar SMS se você não pode receber respostas? Neste artigo, vamos mostrar exatamente como configurar isso.

Neste tutorial, você aprenderá a receber uma mensagem SMS recebida implementando um endpoint de webhook no Ruby on Rails.

Resumo Pule esta parte e veja todo o códigos do Guia Rápido no GitHub.

Pré-requisitos

• Ruby on Rails instalado no seu computador 

• Número virtual da Vonage

• Uma conta no ngrok

Como funciona o SMS de entrada?

Talvez você esteja se perguntando como uma mensagem SMS chega do celular de um usuário até sua aplicação Rails. Da mesma forma que os recibos de entrega funcionavam no post anterior, a Vonage cuida da interação com a rede móvel. Em seguida, ela encaminha essas informações para um webhook que você define em sua aplicação Vonage. Neste tutorial, usaremos o ngrok para lidar com o webhook e encaminhá-lo para nossa aplicação Rails.

Diagram illustrating the inbound SMS process, where a user sends a message through the Vonage platform, which then forwards the message to an application via a webhook.

Como disponibilizar uma aplicação Ruby on Rails com o ngrok

Você pode usar o ngrok para expor com segurança seu servidor local ao público via HTTP. Então, agora, em uma aba separada do seu servidor Rails, abra um túnel do ngrok na porta 3000.

ngrok http 3000

Certifique-se de adicionar sua URL do ngrok como um config.host no seu development.rb . Usaremos a variável de ambiente VONAGE_SERVER_HOSTNAMEpara tornar nosso aplicativo mais dinâmico.

Para obter mais ajuda, consulte como começar a usar o ngrok no Rails.

# config/environments/development.rb

Rails.application.configure do
   config.hosts << ENV['VONAGE_SERVER_HOSTNAME']

Se você ainda não criou um arquivo .env, certifique-se de fazê-lo na raiz do seu aplicativo e adicione suas credenciais da Vonage e a URL do ngrok:

VONAGE_APPLICATION_ID='XXXX'
VONAGE_PRIVATE_KEY='./private.key'
VONAGE_SERVER_HOSTNAME='XXXXXX.ngrok.app

>> Mantenha suas credenciais em segurança

>> Nunca envie arquivos .env para o seu repositório! Certifique-se de que o .env esteja no seu .gitignore.

Agora, precisaremos atualizar nosso aplicativo Vonage (dos artigos anteriores) no painel do desenvolvedor. Clique em “editar”. Agora, atualize a URL de entrada na seção “Recursos de mensagens”. Adicione sua URL do ngrok seguida de /inbound_sms.

Assim que você clicar em “Salvar”, o ngrok passará a encaminhar as solicitações feitas ao endpoint /inbound_sms para o seu aplicativo Rails! Mas há um pequeno problema: nosso aplicativo Rails não possui esse endpoint.

Como lidar com um Webhook de SMS recebido no Rails

Agora que a Vonage está encaminhando uma mensagem SMS para o /inbound_sms vamos atualizar nosso aplicativo e criar uma rota para lidar com isso.

# config/routes.rb

Rails.application.routes.draw do
  resources :inbound_sms, only: [:create]
  ....remaining routes...

Quando uma mensagem SMS for enviada para o seu número virtual da Vonage, a Vonage notificará seu aplicativo por meio de um webhook. Uma carga útil típica de uma mensagem SMS recebida terá mais ou menos esta aparência.

{
    "to": "12013508504",
    "from": "12013508506",
    "channel": "sms",
    "message_uuid": "a1610e97-a045-4d04-933b-5e570fe51691",
    "timestamp": "2025-02-23T18:21:41Z",
    "usage": {
      "price": "0.0059",
      "currency": "EUR"
    },
    "message_type": "text",
    "text": "Testing",
    "context_status": "none",
    "origin": {
      "network_code": "42507"
    },
    "sms": {
      "num_messages": "1",
      "count_total": "1"
    }
  }

Como armazenar uma mensagem SMS no Rails

Agora que temos todas as informações necessárias com base no nosso modelo de SMS, conforme definido anteriormente, podemos criar uma lógica para armazenar nossas mensagens SMS recebidas. Também vamos adicionar um recurso divertido para mostrar que nosso código está funcionando. Vamos gerar um novo controlador para lidar com isso.

rails g controller InboundSms create

Dentro do nosso controlador, teremos um simples método create que analisa o webhook e insere um SMS em nosso banco de dados. Você notará que definimos is_inbound para true.

# app/controllers/inbound_sms_controller.rb

class InboundSmsController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create

    sms = Sms.create(
      to: params[:to],
      from: params[:from],
      text: params[:text],
      message_uuid: params[:message_uuid],
      is_inbound: true
    )

    # Send a reply
    # reply sms

    # Return an empty HTTP 200 status regardless
    head :ok
  end
end

Para comprovar que recebemos o SMS, vamos enviar uma resposta ao remetente. Vamos nos divertir um pouco, mostrando o texto original primeiro sem vogais e, em seguida, em binário.

private

def reply(sms)
    consonants = sms.text.delete("aeiouAEIOU")
    binary = sms.text.unpack1('B*')

    message = Vonage::Messaging::Message.sms(message: "Your message without vowels is #{consonants} and your message in binary is #{binary}")

    vonage.messaging.send(
      from: sms.to,
      to: sms.from,
      **message
    )
end

O método de resposta depende do cliente Vonage; portanto, precisaremos inicializá-lo da mesma forma que fizemos no primeiro artigo.

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

Veja como todo o código se encaixa no arquivo completo inbound_sms_controller.rb .

Conclusão

Parabéns! Você criou com sucesso um aplicativo de SMS em Ruby on Rails capaz de receber mensagens usando um webhook da Vonage. Com isso, você concluiu a parte dedicada ao SMS do Guia de Início Rápido do Ruby on Rails. Adicionaremos recursos de voz com a Voice API da Vonage em tutoriais futuros.

Se você tiver alguma dúvida ou quiser solicitar um recurso para o aplicativo Quickstart, participe da conversa no Slack da Vonage no Slack da Comunidade Vonage ou entre em contato pelo X (antigo Twitter). Adoraríamos saber o que você vai criar a seguir!