Receber uma mensagem de status por SMS com Ruby on Rails

Anteriormente, aprendemos como enviar mensagens SMS usando a integração de SMS do Ruby on Rails. No entanto, enviar um SMS não deve ser como jogar uma mensagem na garrafa. Com aplicativos de SMS no Ruby on Rails, podemos acompanhar a entrega das mensagens e garantir a confiabilidade. Felizmente, temos isso e muito mais com a Messages API e Status de Mensagem SMS.

Este tutorial mostrará como integrar os status de entrega de SMS em um aplicativo Ruby on Rails usando os webhooks da Vonage.

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

Pré-requisitos

• Uma conta no ngrok

• Número virtual da Vonage 

• Aplicativo Ruby on Rails, conforme descrito anteriormente

O que é o status de uma mensagem SMS?

Quando você envia uma solicitação para enviar um SMS, esse é apenas o primeiro passo do processo. Se a solicitação de SMS for bem-sucedida, a Vonage irá colocará o SMS na fila enquanto procura a melhor operadora de rede para entregá-lo. A partir daí, a operadora de rede atenderá à solicitação e enviará o SMS ao destinatário.

Diagram explaining SMS Message Status, showing how messages travel from an application through Vonage and carriers to the user, with delivery status callbacks.

Em seguida, é enviada uma Mensagem de Status (MS) na ordem inversa (Provedor de Rede → Vonage → Seu aplicativo) informando se a mensagem SMS foi entregue com sucesso ou não.

Para receber esse MS em seu aplicativo, você precisará configurar um endpoint de webhook indicando à Vonage para onde enviá-lo.

Como disponibilizar publicamente nosso aplicativo Ruby on Rails com o ngrok

A Vonage precisará enviar os status das nossas mensagens para um endpoint. Nossa aplicação Ruby on Rails está rodando em ambiente de desenvolvimento na porta 3000, portanto, podemos acessá-la localmente em localhost:3000. No entanto, isso só funciona no nosso computador!

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 config.host no arquivo 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']

Agora, no nosso arquivo .env, defina 'VONAGE_SERVER_HOSTNAME' com a sua URL do ngrok.

# .env

# ngrok URL, don't include the protocol (https://)
VONAGE_SERVER_HOSTNAME=''

Também precisaremos editar nosso aplicativo Vonage (do artigo anterior) no painel de controle para adicionar a URL do ngrok aos nossos webhooks. No campo “Status URL”, adicione sua URL do ngrok seguida de /sms_message_status.

Vonage Messages API webhook settings showing an invalid Inbound URL error.Assim que você clicar em “Salvar”, o ngrok passará a encaminhar as solicitações feitas ao endpoint /sms_message_status para o seu aplicativo Rails! Mas há um pequeno problema: nosso aplicativo Rails não possui esse endpoint.

Como lidar com webhooks de confirmação de entrega no Rails

Agora que a Vonage está encaminhando os status para o /sms_delivery_receipts terminal, vamos atualizar nosso aplicativo e criar uma rota para lidar com isso.

# config/routes.rb
Rails.application.routes.draw do

 # For SmsMessageStatus controller, create
  post '/sms_message_status', to: 'sms_message_status#create', as: :sms_message_status

	...previous routes...

Mas o que vai acontecer aí? Nosso aplicativo vai aceitar o Status da Mensagem e analisá-lo para extrair as informações relevantes. Você pode ver como é um Status da Mensagem típico:

{
"to"=>"13215678899",
"from"=>"John",
"channel"=>"sms",
"message_uuid"=>"93cc5afe-2824-4d40-97b1-e6f6ec00249e", 
"timestamp"=>"2025-02-23T14:52:53Z",
"status"=>"delivered", 
"destination"=> {"network_code"=>"42507"}
}

O campo mais importante é o status , pois ele informa se sua mensagem foi entregue e, caso contrário, o que deu errado. Veja mais informações sobre o status da mensagem .

Vamos criar uma lógica para atualizar nosso status de SMS com base nos status das mensagens recebidas. Vamos gerar um novo controlador na linha de comando para lidar com isso.

rails g controller SmsMessageStatus create

Nosso controlador possui um único método simples create . Primeiro, o método analisa o status da mensagem e extrai o `message_uuid`; ele usa esse ID externo para localizar o SMS em nosso banco de dados local. Em seguida, ele atualiza o status desse SMS para o status atual que recebemos no status da mensagem.

class SmsMessageStatusController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
   SmsMessage.where(message_uuid: params[:sms_message_status][:message_uuid])
       .update_all(status: params[:sms_message_status][:status]) if params[:sms_message_status][:message_uuid]

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

Agora você pode enviar um SMS e acompanhar seu servidor Rails para verificar se o webhook é chamado, encaminhado e se o ActiveRecord atualiza o banco de dados!

Console log showing the processing of an SMS delivery receipt in a Vonage Rails application, including a database update query.

Conclusão

Você conseguiu! Você aprendeu a configurar sua aplicação Ruby on Rails para receber um webhook via ngrok, atualizando seu banco de dados nesse processo! Vamos continuar a desenvolver essa aplicação, adicionando a capacidade de receber SMS no próximo post.

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.