Como enviar mensagens pelo WhatsApp com Ruby on Rails

Introdução

O WhatsApp é uma das plataformas de mensagens mais populares do mundo, com mais de dois bilhões de usuários, e está se tornando rapidamente um canal essencial para atendimento ao cliente, atualizações e automação de marketing.

Neste tutorial, você aprenderá a enviar mensagens pelo WhatsApp a partir de um aplicativo Ruby on Rails usando a Messages API da Vonage. Como bônus, você também aprenderá a adicionar botões de resposta interativos para que os usuários possam responder de forma mais fácil e intuitiva.

Resumo: Baixe o Guia de Início Rápido do Rails para WhatsApp no GitHub

A Ruby on Rails app sending a WhatsApp message through the Vonage Messages API.

Pré-requisitos

Antes de começar, você precisará do seguinte:

• Ruby e Rails estão instalados no seu computador

  • Este tutorial utiliza o Rails 7 ou superior, mas funciona exatamente da mesma forma no Rails 8 ou superior

• Um Account verificado do WhatsApp Business (WABA)

  • Ainda não tem um Account do WhatsApp Business? Comece com o nosso Guia de Início Rápido do Sandbox para o WhatsApp para testar com o mínimo de configuração.

• O gem dotenv-rails para gerenciar credenciais

• Um Account da API da Vonage

Passo 1: Criar uma aplicação Ruby on Rails

Comece criando um novo aplicativo Rails:

rails new vonage-rails-whatsapp
cd vonage-rails-whatsapp

Adicione suas dependências, o SDK Ruby da Vonage e o dotenv:

bundle add vonage dotenv-rails

Criar um modelo WhatsAppMessage

Vamos criar um modelo para armazenar os detalhes de cada mensagem, como remetente, destinatário e status de entrega. Para lidar adequadamente com os diferentes tipos de mensagem e armazenar as informações do remetente, vamos adicionar campos adicionais:

• message_type: Distinguir entre “texto”, “resposta” e outros tipos de mensagem

• nome_do_perfil: Armazenar o nome de exibição do remetente no WhatsApp

• reply_data: Armazena os dados JSON completos para respostas interativas de botões

rails g model WhatsappMessage to:string from:string text:text status:string message_uuid:string is_inbound:boolean message_type:string profile_name:string reply_data:text

Em seguida, execute a migração:

rails db:migrate

Criar um controlador e rotas

Usaremos um controlador para gerenciar o envio de mensagens e a exibição do formulário.

rails g controller OutboundWhatsapp new create

Em seguida, defina as rotas em config/routes.rb:

Rails.application.routes.draw do
  get  '/outbound_whatsapp/new', to: 'outbound_whatsapp#new', as: :new_outbound_whatsapp
  post '/outbound_whatsapp',     to: 'outbound_whatsapp#create', as: :outbound_whatsapp

  # Bonus route for interactive messages
  post '/outbound_whatsapp/interactive', to: 'outbound_whatsapp#interactive', as: :interactive_whatsapp
end

Por que não usar os recursos disponíveis aqui?

Neste tutorial, estamos usando rotas GET/POST explícitas. Isso mantém o mapeamento entre cada URL e a ação do controlador bem explícito para os leitores que talvez ainda estejam se familiarizando com o roteamento do Rails. Em um aplicativo de produção, você pode, sem dúvida, mudar para roteamento resourceful e rotas de coleção , caso prefira um estilo RESTful mais idiomático.

O equivalente seria:

resources :outbound_whatsapp, only: [:new, :create] do
  collection do
    post :interactive
  end
end

Etapa 2: Configure seu aplicativo

Criar uma aplicação da Vonage

Antes de enviar mensagens, você precisará de um aplicativo da Messages API do Vonage.

1. Faça login no seu Painel de Controle da Vonage.

2. Crie uma nova aplicação e habilite o recurso “Mensagens”.

3. Adicione URLs de webhook provisórias para:

   • Inbound: https://example.com/inbound

   • Status: https://example.com/status

4. Clique em “Gerar chave pública e privada”

   • Mova o arquivo baixado private.key para a raiz (vonage-rails-whatsapp) do seu aplicativo Rails.

5. Anote o ID do seu aplicativo para uso posterior.

6. Clique em “Salvar”

7. Vincule seu número do WhatsApp na aba “Vincular contas externas”.

Agora você está pronto para se autenticar e enviar mensagens.

Viewing the WhatsApp-Rails application in the Vonage dashboard with an active WhatsApp number linked.

Adicione suas variáveis de ambiente

Armazene suas credenciais com segurança em um arquivo arquivo .env :

touch .env

Em seguida, abra o arquivo arquivo .env e atualize-o com suas credenciais:

VONAGE_APPLICATION_ID=your_application_id
VONAGE_PRIVATE_KEY=./private.key
VONAGE_WHATSAPP_NUMBER=14157386102

>> Para obter mais ajuda, confira: Trabalhando com variáveis de ambiente em Ruby

Etapa 3. Enviar uma mensagem de texto pelo WhatsApp

Antes de implementar tudo no Rails, vamos entender o que está acontecendo nos bastidores. O SDK do Vonage para Ruby oferece um único cliente para acessar várias APIs da Vonage, incluindo a Messages API, que usaremos para o WhatsApp.

Como funciona o cliente Vonage em Ruby

O cliente Ruby é inicializado com as credenciais do seu aplicativo, provenientes do arquivo arquivo .env .

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

>> Observação: Para projetos em ambiente de produção, é recomendável armazenar suas credenciais da Vonage com segurança usando Credenciais Criptografadas do Rails

Depois de inicializado, você pode usar esse cliente para enviar qualquer tipo de mensagem compatível (SMS, WhatsApp, Messenger, Viber) por meio do método .

Veja a seguir como funciona o envio de uma mensagem de texto pelo WhatsApp em Ruby puro:

response = vonage.messaging.send(
  to: "14155551234",
  from: ENV["VONAGE_WHATSAPP_NUMBER"],
  channel: "whatsapp",
  message_type: "text",
  text: "Hey, it's your friends from Vonage!"
)

puts response.inspect

Se a mensagem for enviada com sucesso, a Vonage retorna um 202 , juntamente com um message_uuid.

Envio de mensagens pelo WhatsApp em um aplicativo Ruby on Rails

Agora que você já entende como o cliente Vonage funciona isoladamente, vamos conectá-lo à sua aplicação Rails.

Vamos adicionar a lógica ao nosso OutboundWhatsappController para criar e enviar mensagens pelo WhatsApp a partir do formulário da web.

Abrir app/controllers/outbound_whatsapp_controller.rb e substitua o conteúdo por (ignore a mensagem interativa por enquanto):

class OutboundWhatsappController < ApplicationController
  def new
    @whatsapp_message = WhatsappMessage.new
  end

  def create
    @whatsapp_message = WhatsappMessage.new(safe_params)

    if @whatsapp_message.save
      deliver(@whatsapp_message)
      redirect_to :new_outbound_whatsapp, notice: 'WhatsApp message sent!'
    else
      flash[:alert] = 'Something went wrong'
      render :new
    end
  end

  private

  def safe_params
    params.require(:whatsapp_message).permit(:to, :text)
  end

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

    response = vonage.messaging.send(
      message_type: "text",
      text: whatsapp_message.text,
      to: whatsapp_message.to,
      from: ENV['VONAGE_WHATSAPP_NUMBER'],
      channel: "whatsapp"
    )

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

Dentro do método , o processo segue quatro etapas principais. Primeiro, ele inicializa um novo cliente Vonage. Em seguida, ele envia uma mensagem de texto pelo WhatsApp chamando messaging.send com os parâmetros necessários. Neste guia rápido, sempre enviamos a partir de um único número do WhatsApp configurado por meio da variável de ambiente VONAGE_WHATSAPP_NUMBER. Mas, em um aplicativo mais avançado, você poderia expor um campo “de” e permitir que os usuários escolham de qual número enviar a mensagem.

Assim que a solicitação é feita, o método verifica a resposta da API. Se o servidor retornar um código de status HTTP 202 , isso significa que a mensagem foi aceita com sucesso para entrega. Por fim, o método salva o message_uuid retornado pela Vonage.

Adicionar uma visualização simples

Agora crie app/views/outbound_whatsapp/new.html.erb para o formulário de mensagem de texto (ignore a mensagem interativa por enquanto):

<h1>Send a WhatsApp Message</h1>

<%= form_with model: @whatsapp_message, url: outbound_whatsapp_path, local: true do |f| %>
  <div>
    <%= f.label :to, "To (Recipient WhatsApp Number)" %><br>
    <%= f.text_field :to, placeholder: "e.g. 14155551234" %>
  </div>

  <div>
    <%= f.label :text, "Message" %><br>
    <%= f.text_area :text, rows: 4, placeholder: "Type your message..." %>
  </div>

  <%= f.submit "Send Message", class: "btn btn-primary" %>
<% end %>

Etapa 4: Executar e testar

Inicie seu servidor Rails:

rails s

Em seguida, abra http://localhost:3000/outbound_whatsapp/new.

Você deve conseguir enviar uma mensagem pelo WhatsApp a partir de um formulário parecido com este:

A Rails form for sending WhatsApp messages using the Vonage Messages API.

Bônus: Adicione botões de resposta interativos

Agora, vamos tornar suas mensagens mais envolventes enviando botões de respostabotões de resposta interativos. Essas mensagens permitem que os usuários toquem em uma das várias opções em vez de digitar, fazendo com que seu aplicativo pareça mais um chatbot.

A Ruby on Rails app sending an interactive WhatsApp message with reply buttons using the Vonage Messages API.

Adicionar uma ação interativa

No seu OutboundWhatsappController, adicione este novo método:

 def interactive
    unless params[:to].present?
      redirect_to :new_outbound_whatsapp, alert: "Recipient number is required!"
      return
    end

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

    interactive_message = {
      from: ENV["VONAGE_WHATSAPP_NUMBER"],
      to: params[:to],
      channel: "whatsapp",
      message_type: "custom",
      custom: {
        type: "interactive",
        interactive: {
          type: "button",
          header: {
            type: "text",
            text: "Delivery time"
          },
          body: {
            text: "Which time would you like us to deliver your order at?"
          },
          footer: {
            text: "Please allow 15 minutes either side of your chosen time."
          },
          action: {
            buttons: [
              {
                type: "reply",
                reply: { id: "slot-1", title: "15:00" }
              },
              {
                type: "reply",
                reply: { id: "slot-2", title: "16:30" }
              },
              {
                type: "reply",
                reply: { id: "slot-3", title: "17:15" }
              }
            ]
          }
        }
      }
    }

    response = vonage.messaging.send(**interactive_message)
    Rails.logger.info("📤 Sent interactive message to #{params[:to]}: #{response.inspect}")

    redirect_to :new_outbound_whatsapp, notice: "Interactive message sent to #{params[:to]}!"
  end

Adicione um formulário para acioná-lo

Atualização app/views/outbound_whatsapp/new.html.erb para incluir:

<hr>
<h3>Try an Interactive Message</h3>
<p>Send a sample interactive WhatsApp message with reply buttons.</p>

<%= form_with url: interactive_whatsapp_path, method: :post, local: true do |f| %>
  <div>
    <%= f.label :to, "To (Recipient WhatsApp Number)" %><br>
    <%= f.text_field :to, placeholder: "e.g. 14155551234", required: true %>
  </div>
  
  <%= f.submit "Send Interactive Message", class: "btn btn-secondary" %>
<% end %>

Experimente

Atualize a página do seu navegador, insira o número de telefone do destinatário e clique em “Enviar mensagem interativa”.

Você receberá uma mensagem pelo WhatsApp e poderá ver a confirmação no seu servidor Rails:

Terminal output confirming successful delivery of an interactive WhatsApp message using the Vonage Messages API in a Ruby on Rails app.No entanto, o que aconteceu com essa mensagem? Ela foi aberta? Foi lida? Qual opção o usuário selecionou? Não temos como saber. Continue lendo para descobrir como lidamos com as ações dos nossos usuários.

Saiba mais

Nosso aplicativo atual está incompleto. Não processamos mensagens recebidas, nem o status das mensagens, nem o conteúdo das mensagens que nos indicam a escolha do usuário.

No próximo tutorial, Como receber mensagens do WhatsApp no Rails, abordaremos todos esses tópicos, o que permitirá que você desenvolva Applications mais dinâmicas.

Conclusão

Você acabou de criar um aplicativo em Ruby on Rails que envia tanto mensagens de texto pelo WhatsApp quanto mensagens com botões de resposta interativos usando a Messages API do Vonage.

Você aprendeu a:

• Configurar o aplicativo WhatsApp da Vonage

• Enviar mensagens de texto a destinatários externos a partir do Rails

• Adicione botões interativos para conversas mais ricas

Em quais outros tópicos do Rails você está interessado? Você já experimentou o RCS (Rich Communications Services)? Experimente enviar as “Respostas Sugeridas” do RCS; são como as respostas do WhatsApp, mas diretamente no seu aplicativo de mensagens padrão.

Tem dúvidas ou sugestões? Junte-se a nós na Slack da Comunidade Vonage ou siga @VonageDev no X (antigo Twitter).