Como enviar respostas sugeridas do RCS com Ruby on Rails

Serviços de Comunicação Avançada (RCS) estão transformando a forma como as empresas interagem com os clientes. Como a próxima evolução do SMS, o RCS oferece uma experiência mais rica e interativa com recursos como imagens, vídeos, compartilhamento de arquivos e respostas sugeridas, diretamente no aplicativo de mensagens padrão do usuário. Confira todos os recursos incríveis recursos do RCS.

Com a implantação do suporte ao RCS em todo o mundo, tanto para Android quanto para iOS, agora é o momento perfeito para começar a explorar essa tecnologia. Neste tutorial, você aprenderá a enviar respostas sugeridas pelo RCS usando a Messages API do Vonage em um aplicativo Ruby on Rails, o que o ajudará a criar conversas mais dinâmicas e envolventes com seus usuários.

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

A Vonage RCS chatbot asks the user to choose their preferred ice cream flavor using quick reply buttons.

Pré-requisitos

• Ruby on Rails instalado no seu computador 

• Uma conta no ngrok.

  • Se você ainda não conhece os serviços de tunelamento ou precisa de ajuda para configurar um, confira nosso guia sobre Como usar o ngrok no Rails em 2025 para obter instruções passo a passo sobre como configurar túneis públicos para webhooks.

• Um agente registrado da RBM

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

Como registrar um agente RBM

Para enviar e receber mensagens com recursos RCS no seu aplicativo da Vonage, você precisará ter um agente Rich Business Messaging (RBM) registrado e um telefone com recursos RCS.

Atualmente, o serviço de mensagens RCS via Vonage está disponível apenas para contas gerenciadas. Você precisará entrar em contato com seu gerente de conta para solicitar a ativação do Modo Desenvolvedor para o seu agente RBM. O Modo Desenvolvedor permite que você teste o envio de mensagens RCS para números incluídos na lista de permissões antes de concluir o processo de verificação do agente e iniciar a operação em produção.

Por favor, entre em contato com nossa equipe de vendas caso você não tenha um account gerenciado. 

>> Entenda a diferença entre RCS e RBM.

Como criar uma aplicação em Ruby on Rails

Este tutorial pressupõe que você tenha um conhecimento básico de Ruby e Rails, limitando-se aos comandos necessários, sem entrar em explicações muito detalhadas.

Primeiro, vamos criar nosso novo projeto.

rails new vonage-rails-quickstart

Em seguida, acesse o projeto e adicione a gem Vonage ao seu Gemfile para que possamos acessar o SDK da Vonage. Também vamos adicionar o `dotenv-rails` para que possamos usar variáveis de ambiente com segurança.

# Gemfile

gem 'vonage'
gem 'dotenv-rails', groups: [:development, :test]

Em seguida, execute o bundler para instalar nossas gems.

bundle install

O que é uma resposta sugerida pelo RCS?

Vamos começar analisando como funcionam as respostas sugeridas no RCS. As respostas sugeridas fazem parte de uma mensagem RCS personalizada, um formato flexível que permite definir elementos interativos, como botões de resposta, diretamente no corpo da mensagem. Em vez de enviar texto simples, você pode apresentar aos usuários opções selecionáveis, tornando as conversas mais rápidas, mais ricas e mais fáceis de navegar.

Agora, vamos pensar no nosso modelo RcsMessage, que define seus atributos e como eles são armazenados no banco de dados. As mensagens RCS na Messages API podem ser de um dos 5 tipos: texto, imagem, Vídeo, arquivoou personalizado. As respostas sugeridas são de personalizadas , que possuem a seguinte estrutura básica:

{
   "message_type": "custom",
   "custom": {},
   "to": "447700900000",
   "from": "Vonage",
   "channel": "rcs",
   "ttl": 600,
   "client_ref": "abc123",
   "webhook_url": "https://example.com/status"
}

No entanto, é aqui que a coisa fica complicada, pois o esquema de um objeto personalizado pode variar bastante. Saiba mais sobre as mensagens personalizadas do RCS.

No nosso caso de uso, a API espera que uma mensagem sugerida de saída tenha a seguinte estrutura:

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "custom",
 "custom": {
   "contentMessage": {
     "text": "Which ice-cream flavour do you prefer?",
     "suggestions": [
        {
          "reply": {
            "text": "Vanilla",
            "postbackData": "suggestion_1"
          }
        },
        {
          "reply": {
            "text": "Chocolate",
            "postbackData": "suggestion_2"
          }
        }
     ]
  }
 }
}

E quando o usuário clicar em um botão de resposta sugerida, a resposta ficará assim:

{
  "to": "Vonage",
  "from": "447900000000",
  "channel": "rcs",
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "timestamp": "2024-02-08T10:12:44Z",
  "message_type": "reply",
  "reply": {
    "id": "suggestion_2",
    "title": "Chocolate"
  }
}

Como criar um modelo de resposta sugerida no RCS

Como podemos criar um modelo de mensagem RCS flexível e dinâmico, capaz de se adaptar a ambas as situações? Felizmente, o ActiveRecord nos permite usar JSON como um tipo de dados diretamente em nosso modelo.

Vamos precisar de 7 campos:

• para: o destinatário do RCS.

• de: o remetente do RCS.

• status: se um RCS foi entregue com sucesso ou não.

• message_uuid: o ID da Vonage associado à mensagem, que será importante para acompanhar o status das mensagens.

• carimbo de data/hora: quando um usuário respondeu à sugestão.

• personalizado: objeto JSON que indica à Messages API que se trata de uma mensagem de resposta sugerida e que contém a mensagem sugerida juntamente com as sugestões.

• resposta: objeto JSON que informa à Messages API que esta é uma resposta a uma mensagem sugerida.

rails generate model RcsMessage to:string from:string message_uuid:string timestamp:string message_type:string status:string custom:json reply:json

Também precisaremos atualizar nosso banco de dados com o novo modelo.

rails db:migrate

Como criar um controlador RCS de saída

Vamos criar nosso controlador para lidar com nossa lógica.

rails g controller OutboundRcs new create

Por fim, vamos definir nossas rotas para SMS de saída.

# config/routes.rb

Rails.application.routes.draw do
 # For OutboundRcs controller, new & create
  get  '/outbound_rcs/new', to: 'outbound_rcs#new',    as: :new_outbound_rcs
  post '/outbound_rcs',     to: 'outbound_rcs#create', as: :outbound_rcs
    ... previous routes ...
end

Como criar uma aplicação da Vonage

Agora que nosso aplicativo Rails está pronto, também precisaremos criar e configurar nosso aplicativo Vonage. Primeiro, precisamos criar nosso aplicativo no Painel do Vonage. Dê um nome ao aplicativo e ative o recurso “Mensagens”. Por enquanto, você pode adicionar URLs provisórias para os webhooks. Atualizaremos esses links em posts futuros. Além disso, em posts futuros, você precisará vincular seu aplicativo ao seu Agente RCS. Como este post aborda apenas mensagens de saída e não requer o uso de webhooks, podemos pular essa etapa por enquanto.

A screenshot of the Vonage Developer dashboard showing the creation of a new application with authentication, privacy, and messaging capabilities settings.Certifique-se de gerar um arquivo private.key clicando em “Gerar chave pública e privada”. Isso fará com que um arquivo private.key seja baixado para o seu computador. Em seguida, mova o arquivo private.key para a raiz da sua aplicação Rails.

Quando seu aplicativo for criado, anote o ID do aplicativo; você precisará dele na próxima etapa.

Crie um arquivo .env na raiz da sua aplicação Rails:

touch .env

Por fim, adicione as seguintes chaves com suas credenciais.

# .env

VONAGE_APPLICATION_ID=''

VONAGE_PRIVATE_KEY='./private.key'

RCS_SENDER_ID=''

Observação: RCS_SENDER_ID é o nome da sua marca RCS. Certifique-se de verificar os requisitos de formatação. Por exemplo, não são permitidos espaços. Se o nome da sua marca RCS for “Ruby on Rails Quickstart”, o SENDER_ID seria “RubyonRailsQuickstart”.

Como inicializar o cliente Ruby da Vonage

Antes de habilitar o cliente Ruby em uma aplicação Rails completa, vamos ver como podemos usá-lo de maneira mais geral em código Ruby. Para usar o cliente, basta inicializar uma instância com as informações da nossa aplicação armazenadas no nosso arquivo de ambiente.

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

Quer saber mais sobre como gerenciar credenciais de API com segurança? Confira Trabalhando com variáveis de ambiente em Ruby.

Como enviar uma mensagem RCS em Ruby

Agora que nosso cliente está inicializado, enviar uma mensagem RCS se torna um processo bastante simples, com duas etapas. Chamamos a método para instruir o cliente a usar a Messages API e, em seguida, criamos nossa mensagem RCS:

message = vonage.messaging.rcs(
  type: 'custom',
  message: {
    contentMessage: {
      text: "Vonage APIs are easy to use.",
      suggestions: [
        {
          reply: {
            text: "Strongly Agree",
            postbackData: "5"
          }
        },
        {
          reply: {
            text: "Agree",
            postbackData: "4"
          }
        },
        {
          reply: {
            text: "Neutral",
            postbackData: "3"
          }
        },
        {
          reply: {
            text: "Disagree",
            postbackData: "2"
          }
        },
        {
          reply: {
            text: "Strongly Disagree",
            postbackData: "1"
          }
        }
      ]
    }
  }
)

Em seguida, passamos nossa mensagem para o método `send`. Observe que o campo “from” é o seu RBM SenderID (o nome da marca). O SenderID exige uma formatação especial, como, por exemplo, não conter espaços. Verifique com seu gerente de Account caso tenha dúvidas.

vonage.messaging.send(
  from: 'VonageRCSAgent',
  to: '447900000000',
  **message
)

Envio de RCS em um aplicativo Ruby on Rails

Agora que já vimos como usar o cliente Ruby da Vonage para enviar RCS, vamos integrar uma funcionalidade de envio de RCS em Ruby on Rails ao nosso aplicativo, usando um formulário e um controlador simples. Precisaremos de uma interface de usuário agradável para lidar com o para, texto da mensagem de conteúdoe campos de sugestões de resposta . O RCS pode lidar com até 11 respostas sugeridas, por isso adicionamos um botão “Adicionar outra sugestão” para que você crie quantas quiser!

Você pode copiar e adicionar o formulário ao seu /app/views/outbound_rcs/new.html.erb e CSS associado. O formulário possui placeholders, para que você saiba que tipo de entradas são esperadas.

User interface for sending an RCS message, showing fields to enter the recipient's phone number, content message, and suggested reply options.Agora, vamos implementar a lógica para que nosso formulário funcione. Primeiro, precisaremos criar uma instância vazia do RCS para carregar o formulário. Em seguida, quando o formulário for enviado, acionaremos o método `create`.

Deve ser tão fácil quanto passar os parâmetros necessários (para, dee personalizado) do formulário para criar um novo instância @rcs_message . Infelizmente, é um pouco mais complicado do que isso. Mas o que está acontecendo ali?

# app/controllers/outbound_rcs_controller.rb 

class OutboundRcsController < ApplicationController
  def new
    @rcs_message = RcsMessage.new
  end

  def create
    @rcs_message = RcsMessage.new(
      to: safe_params[:to],
      from: ENV["RCS_SENDER_ID"],
      message_type: 'custom'
    )

    custom_message = construct_custom_message(params[:rcs_message])
    @rcs_message.custom = custom_message

    if @rcs_message.save
      deliver @rcs_message
      redirect_to :new_outbound_rcs, flash: { notice: 'RCS Sent' }
    else
      flash[:alert] = 'Something went wrong'
      render :new, status: :unprocessable_entity
    end
  end

  private

  def safe_params
    params.require(:rcs_message).permit(:to)
  end
end

Parece um pouco desorganizado porque:

1) Nosso modelo RCS utiliza o tipo de dados JSON flexível para nossos campo personalizado , o que significa que nosso formulário é dinâmico e agrupa cada sugestão. Mas isso também significa que não temos certeza de quantas sugestões são passadas.

2) Precisamos construir o objeto JSON da forma que a API espera. Nosso formulário fornece o texto de cada sugestão, mas ainda precisamos construir as sugestões em um array com o par de texto e postbackData.

Para resolver esse problema, podemos definir um método privado no controlador, construct_custom_message, para criar nossa mensagem personalizada e, em seguida, adicioná-lo ao recém-criado @rcs_message .

 def construct_custom_message(rcs_message_params)
    content_message = rcs_message_params[:contentMessage]
    suggestions = rcs_message_params[:suggestions]
    {
      contentMessage: {
        text: contentMessage,
        suggestions: Array(suggestions).reject(&:blank?).each_with_index.map do |suggestion, idx|
          {
            reply: {
              text: suggestion,
              postbackData: "value#{idx + 1}"
            }
          }
        end
      }
    }
  end

Agora que nossa @rcs_message tenha todos os campos obrigatórios, podemos tentar salvá-la em nosso banco de dados e, em seguida, solicitar à Messages API que a envie.

A método é basicamente o mesmo que usamos na seção anterior, exceto que agora utilizamos o método Messages objeto e lidamos com a resposta da API.

Se a mensagem for enviada com sucesso, ela retorna um código de status 202, juntamente com um message_uuid. Esse UUID ajuda a rastrear o status da entrega usando o Status da Mensagem, que abordaremos no próximo post.

 def deliver(rcs_message)
    message = vonage.messaging.rcs(
      type: rcs_message.message_type,
      message: rcs_message.custom
    )

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

    puts response

    if response.http_response.code == '202'
      rcs_message.update(
        message_uuid: response.entity.attributes[:message_uuid]
      )
    end
  end

Veja o arquivo completo arquivo outbound_rcs_controller.rb .

Agora inicie seu servidor Rails:

rails s

E abrir http://localhost:3000/outbound_rcs/new no seu navegador. Você já pode começar a enviar RCS pelo seu aplicativo Ruby on Rails!

SDK do Ruby x Messages API

Você deve ter percebido que, em nosso método de entrega , usamos type em vez de message_type , conforme definido na referência da Messages API. Isso ocorre porque o SDK do Ruby abstrai a Messages API e simplesmente exige que passemos o tipo e mensagem. Além disso, podemos passar quaisquer opções adicionais por meio do parâmetro . Veja mais exemplos no README.

Se preferir, você pode ignorar a abstração e chamar a Messages API diretamente por meio do método :

client.messaging.send(
  channel: 'rcs',
  message_type: 'text',
  to: '447700900000',
  from: 'Vonage',
  text: 'Hello world!'
)

Conclusão

Excelente trabalho! Você deu o primeiro passo para criar experiências de mensagens de última geração com o RCS, enviando respostas sugeridas interativas a partir de um aplicativo Ruby on Rails usando a Messages API do Vonage.

Pronto para tornar seu aplicativo interativo? Aprenda a lidar com as entradas do usuário receber respostas sugeridas pelo RCS no Ruby on Rails. Você também pode acompanhar a entrega das mensagens em tempo real ao receber atualizações de status das mensagens RCS no Ruby on Rails.

Se você tiver alguma dúvida ou sugestão sobre mais conteúdos relacionados ao Ruby ou ao RCS, participe da conversa conosco no Vonage no Slack da Comunidade Vonage ou entre em contato pelo X, antes conhecido como Twitter. Adoraríamos saber o que você vai criar a seguir!