Como receber uma resposta sugerida pelo RCS no Ruby on Rails

Serviços de Comunicação Avançada (RCS) oferecem respostas sugeridas que ajudam a melhorar a experiência do usuário com botões de resposta interativos e intuitivos. Anteriormente, aprendemos como enviar mensagens de resposta RCS e acompanhar seu status usando Ruby on Rails. Mas também precisamos aceitar as respostas de alguma forma, para saber qual opção nossos usuários selecionam. Neste artigo, vamos mostrar exatamente como configurar isso.

Neste tutorial, você aprenderá como receber uma mensagem de resposta sugerida do RCS implementando um endpoint de webhook em Ruby on Rails.

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

RCS chat interaction with Vonage RoR bot demonstrating conversational capabilities by asking about ice cream flavor preferences

Pré-requisitos

• Você deve ter concluído o tutorial “Como enviar respostas sugeridas do RCS com Ruby on Rails” , que requer:

  • Ruby on Rails instalado no seu computador 

  • Uma conta no ngrok e instalado no seu computador

  • Um número virtual da Vonage

  • Um agente registrado da RBM

  • Um número de telefone com recursos de RCS para testes

Como funciona o RCS de entrada?

Talvez você esteja se perguntando como uma resposta RCS chega do celular de um usuário até sua aplicação Rails. Da mesma forma que acontece com o SMS, a Vonage cuida da interação com a rede móvel. Em seguida, ela encaminha essas informações por meio de um webhook de entrada que você define em sua aplicação Vonage. Neste tutorial, usaremos o ngrok para lidar com o webhook de entrada em nosso aplicativo Rails.

Diagram illustrating the inbound RCS 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 dinâmica VONAGE_SERVER_HOSTNAME, para que você não precise atualizá-la a cada execução. 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.

Para obter mais ajuda, consulte como trabalhar com variáveis de ambiente no Ruby.

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.

Agora, atualize a URL de entrada na seção “Recursos de mensagens”. Adicione sua URL do ngrok seguida de /inbound_rcs.

Screenshot of the Messages settings in the Vonage dashboard showing configuration for inbound and status webhook URLs used for RCS communication.

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

Como lidar com um WebHooks RCS de entrada no Rails

Agora que a Vonage está encaminhando uma carga útil RCS para /inbound_rcs, vamos atualizar nosso aplicativo criando uma rota para lidar com isso.

Rails.application.routes.draw do
 post '/inbound_rcs', to: 'inbound_rcs#create', as: :inbound_rcs
  ....remaining routes...

Quando uma resposta RCS 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 para uma mensagem JSON de resposta RCS recebida terá mais ou menos a seguinte aparência:

{
   "channel": "rcs",
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "Vonage",
   "from": "447700900001",
   "timestamp": "2025-02-03T12:14:25Z",
   "context_status": "none",
   "message_type": "reply",
   "reply": {
      "id": "reply_option_1",
      "title": "9am"
   }
}

Como armazenar mensagens de resposta RCS no Rails

Agora que temos todas as informações necessárias com base no nosso modelo RCS, conforme definido anteriormente, podemos criar uma lógica para armazenar as respostas RCS recebidas. Também enviaremos uma resposta ao nosso usuário para informá-lo de que recebemos sua resposta. Vamos criar um novo controlador para lidar com isso.

rails g controller InboundRcs create

Dentro do nosso controlador, teremos um simples método `create` que analisa o webhook e insere um RCS em nosso banco de dados. Você vai notar que pegamos o carimbo de data/hora, message_type (que será resposta) e a resposta JSON de resposta.

# app/controllers/inbound_rcs_controller.rb

class InboundRcsController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
    rcs = RcsMessage.create(
      message_uuid: params[:message_uuid],
      from: params[:from],
      to: params[:to],
      timestamp: params[:timestamp],
      message_type: params[:message_type],
      reply: params[:reply]
    )

  # send reply to user
    reply(rcs)
    head :ok
   end

Para comprovar que recebemos a resposta RCS, enviaremos uma mensagem de texto de confirmação de volta ao remetente.

def reply(rcs)
    selection = rcs.reply["title"]
    message = vonage.messaging.rcs(
      type: "text",
      message: "#{selection} is a great choice!"
    )

    vonage.messaging.send(
      from: ENV["RCS_SENDER_ID"],
      to: rcs.from,
      **message
    )

end

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

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

Você pode ver como todo o código se encaixa no arquivo completo inbound_rcs_controller.rb .

Conclusão

Parabéns! Você criou com sucesso um aplicativo RCS em Ruby on Rails capaz de receber mensagens de resposta RCS usando um webhook da Vonage. Com isso, você concluiu a seção sobre sugestões de respostas RCS do Guia de Início Rápido do Ruby on Rails. Continuaremos adicionando mais recursos RCS e, posteriormente, funcionalidades do WhatsApp 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!