Recibir el estado de un mensaje SMS con Ruby on Rails

Anteriormente, aprendimos cómo enviar mensajes SMS utilizando la integración de SMS de Ruby on Rails. Sin embargo, enviar un SMS no debería ser como enviar un mensaje en una botella. Con las aplicaciones Ruby on Rails para SMS podemos hacer un seguimiento de la entrega de los mensajes y garantizar su fiabilidad. Por suerte, tenemos eso y mucho más con Messages API y Estado de los mensajes SMS.

Este tutorial te mostrará cómo integrar estados de entrega de SMS en una aplicación Ruby on Rails utilizando webhooks de Vonage.

TL;DR Saltar adelante y encontrar todo el código de inicio rápido en GitHub.

Requisitos previos

• Una Account ngrok

• Número virtual de Vonage

• Aplicación Ruby on Rails, como se ha descrito anteriormente

¿Qué es el estado de un mensaje SMS?

Cuando realizas una solicitud para enviar un SMS, éste es sólo el primer paso de su viaje. Si realizas una solicitud de SMS correcta, Vonage pondrá en cola el SMS mientras busca el mejor proveedor de red para enviarlo. A partir de ahí, el proveedor de red cumplirá con la solicitud y enviará el SMS a su destinatario.

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

Luego, se envía un estado de mensaje (MS) en el orden inverso (Proveedor de red -> Vonage -> Tu aplicación) con respecto a si el SMS se entregó correctamente o no.

Para recibir este MS en tu aplicación, deberás configurar un punto final de webhook que le indique a Vonage dónde enviarlo.

Cómo exponer públicamente nuestra aplicación Ruby on Rails con ngrok

Vonage necesitará enviar el estado de nuestros mensajes a un endpoint. Nuestra aplicación Ruby on Rails se ejecuta en desarrollo en el puerto 3000, por lo que podemos acceder a ella localmente en localhost:3000. Sin embargo, ¡eso sólo funciona en nuestro ordenador!

Puede utilizar ngrok para exponer de forma segura su servidor local públicamente a través de HTTP. Así que ahora, en una pestaña separada de tu servidor rails, abre un túnel ngrok en el puerto 3000.

ngrok http 3000

Asegúrate de añadir tu URL ngrok como config.host en tu archivo development.rb. Utilizaremos la variable de entorno VONAGE_SERVER_HOSTNAMEpara hacer nuestra aplicación más dinámica.

Para obtener más ayuda, consulte cómo empezar a usar ngrok en Rails.

# config/environments/development.rb

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

Ahora en nuestro archivo .env, establece tu 'VONAGE_SERVER_HOSTNAME' a tu URL ngrok.

# .env

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

También tendremos que editar nuestra aplicación de Vonage (del artículo anterior) en el panel de control para agregar la URL de ngrok en nuestros webhooks. En el campo Status URL, agrega tu URL ngrok seguida de /sms_message_status.

Vonage Messages API webhook settings showing an invalid Inbound URL error.Una vez que pulses guardar, ngrok reenviará las peticiones realizadas al endpoint /sms_message_status a tu aplicación Rails. Pero hay un pequeño problema: nuestra aplicación Rails no tiene ese punto final.

Cómo manejar Webhooks de recepción de entregas en Rails

Ahora que Vonage está reenviando estados al punto final /sms_delivery_receipts endpoint, actualicemos nuestra aplicación y creemos una ruta para manejarlo.

# 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...

Pero, ¿qué va a pasar ahí? Nuestra aplicación aceptará el estado del mensaje y lo analizará para obtener la información relevante. Puedes ver el aspecto típico de un Estado de Mensaje:

{
"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"}
}

El campo más importante es el estado porque le indica si su mensaje ha sido entregado y, en caso negativo, qué ha fallado. Más información sobre Estado del mensaje webhooks.

Vamos a crear algo de lógica para actualizar el estado de nuestros SMS basándonos en los estados de los mensajes recibidos. Vamos a generar un nuevo controlador en la línea de comandos para manejar esto.

rails g controller SmsMessageStatus create

Nuestro controlador tiene un único y sencillo método create simple. En primer lugar, el método analiza el estado de nuestro mensaje y extrae el message_uuid; utiliza este ID externo para encontrar el SMS en nuestra base de datos local. A continuación, actualiza el estado de este SMS con el estado actual que hemos recibido en el estado del mensaje.

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

Ahora puedes enviar un SMS y ver en tu servidor rails que se llama al webhook, se reenvía y ActiveRecord actualiza la base de datos.

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

Conclusión

¡Lo has conseguido! Has aprendido a exponer tu aplicación Ruby on Rails a la escucha de un webhook a través de ngrok, actualizando tu base de datos en el proceso. En la próxima entrada seguiremos desarrollando esta aplicación para que acepte SMS entrantes.

Si tienes alguna pregunta o sugerencia sobre más contenidos de Ruby, envíanos un mensaje a la Slack de la comunidad. También puedes estar al tanto de nuestros contenidos y eventos para desarrolladores en X, antes conocido como Twitter.