Receber o status de uma mensagem RCS com Ruby on Rails

Anteriormente, aprendemos como enviar mensagens de resposta sugerida do Rich Communication Services (RCS) usando Ruby on Rails. No entanto, apenas enviar a mensagem não adianta muito se você não souber o que aconteceu do outro lado. Felizmente, com a Messages API e os Status de Mensagens, temos isso e muito mais.

Este tutorial dará continuidade ao artigo anterior e mostrará como integrar os status das mensagens RCS 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.

O que é um status de mensagem RCS?

A Messages API do Vonage oferece o Webhook de Status da Mensagem, que permite que você se conecte diretamente ao status atual de uma mensagem que você enviou. Sempre que o status da mensagem for atualizado, o webhook é acionado. 

Isso significa que você pode saber se sua mensagem foi enviada, entregue, rejeitada,  não entregávelou lida.

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

Como disponibilizar publicamente nosso aplicativo Ruby on Rails com o ngrok

A Vonage precisará enviar o status das nossas mensagens para um endpoint. Nosso aplicativo Ruby on Rails está em execução no ambiente de desenvolvimento na porta 3000, portanto, podemos acessá-lo 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 publicamente 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 VONAGE_SERVER_HOSTNAME no seu arquivo .env .

# .env

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

Em seguida, (re)inicie seu servidor Rails. Para obter mais ajuda, consulte como começar a usar o ngrok no Rails.

Como conectar seu agente RCS ao seu aplicativo da Vonage

Assim que o ngrok estiver em execução, vamos editar nosso aplicativo Vonage (do artigo anterior) no painel de controle para adicionar a URL do ngrok aos nossos webhooks e vinculá-la ao nosso RCS Agent.

Primeiro, vincule seu RCS Agent clicando no botão guia “Vincular contas externas” :

Dashboard view showing the Vonage-Rails-Quickstart application linked to the Vonage RoR RCS external account, with voice and message capabilities enabled.

Em seguida, edite o aplicativo e, no campo “Status URL”, adicione sua URL do ngrok seguida de /rcs_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 /rcs_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 status de mensagens no Rails

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

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


 # For RcsMessageStatus controller, create
  post '/rcs_message_status', to: 'rcs_message_status#create', as: :rcs_message_status

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:

{
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "447700900000",
   "from": "Vonage",
   "timestamp": "2025-02-03T12:14:25Z",
   "status": "read",
   "client_ref": "abc123",
   "channel": "rcs",
   "destination": {
      "network_code": "12345"
   }
}

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 do RCS com base nos status das mensagens recebidas. Vamos gerar um novo controlador na linha de comando para lidar com isso. 

rails g controller RcsMessageStatus create

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

# app/controllers/rcs_message_status_controller.rb

class RcsMessageStatusController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
   RcsMessage.where(message_uuid: params[:rcs_message_status][:message_uuid])
       .update_all(status: params[:rcs_message_status][:status]) if params[:rcs_message_status][:message_uuid]

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

Agora você pode enviar um RCS (conforme o artigo anterior) e observar seu servidor Rails para ver que o webhook é chamado, encaminhado e que o ActiveRecord atualiza o banco de dados! Observe como o /rcs_message_status é acessado 3 vezes. O status da nossa mensagem é atualizado para enviado, depois entregue e, por fim, lida.

Console log output showing RCS message status updates (submitted, delivered, read) handled by a Ruby on Rails application using the Vonage Messages API.

Conclusão

Você conseguiu! Você aprendeu a configurar sua aplicação Ruby on Rails para receber um webhook de status de mensagem via ngrok, atualizando seu banco de dados nesse processo! Vamos completar o ciclo da jornada do usuário no próximo artigo, permitindo que ele selecione uma das respostas sugeridas que enviamos e, em seguida, processá-la em nossa aplicação Rails.

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.