Wie man WhatsApp-Nachrichten mit Ruby on Rails versendet

Einführung

WhatsApp ist mit über zwei Milliarden Nutzern eine der beliebtesten Messaging-Plattformen der Welt und entwickelt sich schnell zu einem wichtigen Kanal für Kundensupport, Updates und Marketing-Automatisierung.

In diesem Tutorial lernen Sie, wie Sie WhatsApp-Nachrichten von einer Ruby on Rails-Applikation aus versenden können, indem Sie die Vonage Messages API. Als Bonus lernen Sie auch, wie Sie interaktive Antwortschaltflächen hinzufügen, damit Benutzer einfacher und intuitiver antworten können.

TL;DR: Holen Sie sich den kompletten Rails WhatsApp Schnellstart auf GitHub

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

Voraussetzungen

Bevor Sie beginnen, benötigen Sie Folgendes:

• Ruby und Rails auf Ihrem Rechner installiert sind

  • Dieses Tutorial verwendet Rails 7+, aber es funktioniert identisch mit Rails 8+

• Ein verifizierter WhatsApp Business Account (WABA)

  • Sie haben noch keinen WhatsApp Business Account? Beginnen Sie mit unserem Sandbox-Schnellstart für WhatsApp um mit minimaler Einrichtung zu testen.

• Die dotenv-rails gem für die Verwaltung von Anmeldeinformationen

• Ein Vonage API-Konto

Vonage API-Konto

Um dieses Tutorial durchzuführen, benötigen Sie ein Vonage API-Konto. Wenn Sie noch keines haben, können Sie sich noch heute anmelden und mit einem kostenlosen Guthaben beginnen. Sobald Sie ein Konto haben, finden Sie Ihren API-Schlüssel und Ihr API-Geheimnis oben auf dem Vonage-API-Dashboard.

Sind Sie bereit, mit dem Bau zu beginnen?

Erleben Sie nahtlose Konnektivität, Echtzeit-Messaging und kristallklare Sprach- und Videoanrufe - alles auf Knopfdruck.

Schritt 1: Erstellen einer Ruby on Rails-Anwendung

Beginnen Sie mit der Erstellung einer neuen Rails-Anwendung:

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

Fügen Sie Ihre Abhängigkeiten, das Vonage Ruby SDK und dotenv:

bundle add vonage dotenv-rails

Ein WhatsAppMessage-Modell erstellen

Wir werden ein Modell erstellen, um die Details jeder Nachricht zu speichern, z. B. den Absender, den Empfänger und den Zustellungsstatus. Um verschiedene Nachrichtentypen richtig zu behandeln und Absenderinformationen zu speichern, fügen wir zusätzliche Felder hinzu:

• nachrichten_typ: Unterscheidung zwischen "Text", "Antwort" und anderen Nachrichtentypen

• profil_name: Speichert den WhatsApp-Anzeigenamen des Absenders

• Antwort_Daten: Speichern Sie die vollständigen JSON-Daten für interaktive Schaltflächenantworten

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

Und führen Sie dann die Migration durch:

rails db:migrate

Erstellen Sie einen Controller und Routen

Wir werden einen Controller verwenden, um das Senden von Nachrichten und das Anzeigen des Formulars zu verwalten.

rails g controller OutboundWhatsapp new create

Dann definieren Sie die Routen in 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

Warum nicht die Ressourcen hier nutzen?

In diesem Tutorial verwenden wir explizite get/post-Routen. Dies hält die Zuordnung zwischen jeder URL und Controller-Aktion sehr explizit für die Leser, die neu in Rails-Routing sein kann. In einer produktiven Anwendung können Sie durchaus zu Resourceful Routing und Sammelrouten wechseln, wenn Sie einen idiomatischeren RESTful-Stil bevorzugen.

Das Äquivalent würde lauten:

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

Schritt 2: Konfigurieren Sie Ihre Anwendung

Erstellen einer Vonage-Anwendung

Bevor Sie Nachrichten versenden können, benötigen Sie eine Vonage Messages API-Anwendung.

1. Melden Sie sich bei Ihrem Vonage Dashboard an.

2. Erstellen Sie eine neue Anwendung und aktivieren Sie die Nachrichtenfunktion.

3. Fügen Sie Platzhalter-URLs für Webhooks hinzu:

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

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

4. Klicken Sie auf Öffentlichen und privaten Schlüssel generieren

   • Verschieben Sie den heruntergeladenen private.key Datei in das Stammverzeichnis (vonage-rails-whatsapp) Ihrer Rails-Anwendung.

5. Notieren Sie sich Ihre Anwendungs-ID zur späteren Verwendung.

6. Speichern anklicken

7. Verknüpfen Sie Ihre WhatsApp-Nummer unter der Registerkarte Externe Konten verknüpfen.

Jetzt können Sie sich authentifizieren und Nachrichten senden.

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

Fügen Sie Ihre Umgebungsvariablen hinzu

Speichern Sie Ihre Anmeldedaten sicher in einer .env Datei:

touch .env

Öffnen Sie dann die .env Datei und aktualisieren Sie sie mit Ihren Anmeldedaten:

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

>> Weitere Hilfe finden Sie unter: Arbeiten mit Umgebungsvariablen in Ruby

Schritt 3. Senden Sie eine WhatsApp-Textnachricht

Bevor wir alles in Rails einbauen, sollten wir verstehen, was hinter den Kulissen passiert. Die Vonage Ruby SDK bietet Ihnen einen einzigen Client für den Zugriff auf mehrere Vonage-APIs, einschließlich der Messages API, die wir für WhatsApp verwenden werden.

So funktioniert der Vonage-Client in Ruby

Der Ruby-Client wird mit den Anmeldedaten Ihrer Anwendung initialisiert, die aus der Datei .env Datei stammen.

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

>> Hinweis: Für produktive Projekte sollten Sie Ihre Vonage-Anmeldedaten sicher speichern, indem Sie Rails Verschlüsselte Zugangsdaten

Nach der Initialisierung können Sie diesen Client verwenden, um jeden unterstützten Nachrichtentyp (SMS, WhatsApp, Messenger, Viber) über die Funktion messaging.send Methode.

So sieht das Senden einer WhatsApp-Textnachricht in Ruby aus:

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

Wenn die Nachricht erfolgreich gesendet wurde, gibt Vonage eine 202 Statuscode zusammen mit einer eindeutigen nachricht_uuid.

Versenden von WhatsApp-Nachrichten in einer Ruby on Rails-Anwendung

Da Sie nun wissen, wie der Vonage-Client isoliert funktioniert, können wir ihn mit Ihrer Rails-Anwendung verbinden.

Wir fügen die Logik zu unserem OutboundWhatsappController um WhatsApp-Nachrichten über das Webformular zu erstellen und zu versenden.

Öffnen Sie app/controllers/outbound_whatsapp_controller.rb und ersetzen Sie den Inhalt durch (ignorieren Sie vorerst die interaktive Meldung):

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

Im Inneren der liefern Methode durchläuft der Prozess vier wichtige Schritte. Zunächst wird ein neuer Vonage-Client initialisiert. Anschließend wird eine WhatsApp-Textnachricht durch den Aufruf von messaging.send mit den erforderlichen Parametern aufruft. In diesem Quickstart senden wir immer von einer einzigen WhatsApp-Nummer, die über die Umgebungsvariable VONAGE_WHATSAPP_NUMBER konfiguriert wird. Aber in einer fortgeschrittenen App könnte man eine von Feld einrichten und die Benutzer wählen lassen, von welcher Nummer gesendet werden soll.

Sobald die Anfrage gestellt ist, prüft die Methode die API-Antwort. Wenn der Server eine HTTP 202 Statuscode zurück, bedeutet dies, dass die Nachricht erfolgreich zur Zustellung angenommen wurde. Schließlich speichert die Methode die eindeutige message_uuid die von Vonage zurückgegeben wurde.

Eine einfache Ansicht hinzufügen

Erstellen Sie nun app/views/outbound_whatsapp/new.html.erb für das Textnachrichtenformular (ignorieren Sie vorerst die interaktive Nachricht):

<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 %>

Schritt 4: Ausführen und Testen

Starten Sie Ihren Rails-Server:

rails s

Dann öffnen Sie http://localhost:3000/outbound_whatsapp/new.

Sie sollten in der Lage sein, eine WhatsApp-Nachricht über ein Formular zu senden, das wie folgt aussieht:

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

Bonus: Interaktive Antwort-Schaltflächen hinzufügen

Jetzt können Sie Ihre Nachrichten noch ansprechender gestalten, indem Sie interaktive Antwortschaltflächen. Bei diesen Nachrichten können die Nutzer auf eine von mehreren Optionen tippen, anstatt zu tippen, wodurch sich Ihre App mehr wie ein Chatbot anfühlt.

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

Eine interaktive Aktion hinzufügen

In Ihrem bestehenden OutboundWhatsappControllerfügen Sie diese neue Methode hinzu:

 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

Ein Formular zum Auslösen hinzufügen

Aktualisierung app/views/outbound_whatsapp/new.html.erb einfügen:

<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 %>

Probieren Sie es aus

Laden Sie Ihren Browser neu, fügen Sie eine Empfängertelefonnummer hinzu und klicken Sie auf "Interaktive Nachricht senden".

Sie erhalten eine WhatsApp-Nachricht und können die Bestätigung auf Ihrem Rails-Server sehen:

Terminal output confirming successful delivery of an interactive WhatsApp message using the Vonage Messages API in a Ruby on Rails app.Doch was ist mit dieser Nachricht geschehen? Wurde sie geöffnet? Wurde sie gelesen? Welche Option hat der Benutzer ausgewählt? Wir haben keine Möglichkeit, das herauszufinden. Lesen Sie weiter, um herauszufinden, wie wir mit den Aktionen unserer Nutzer umgehen.

Weiter erforschen

Unsere aktuelle Anwendung ist unvollständig. Wir verarbeiten keine eingehenden Nachrichten, keinen Nachrichtenstatus und keine Nachrichten-Payloads, die uns die Auswahl des Benutzers mitteilen.

Im nächsten Tutorium, Wie man WhatsApp-Nachrichten in Rails empfängtwerden wir all diese Themen behandeln, die es Ihnen ermöglichen werden, dynamischere Applications zu erstellen.

Schlussfolgerung

Sie haben nun eine Ruby on Rails-Anwendung erstellt, die sowohl WhatsApp-Textnachrichten als auch interaktive Antwortbutton-Nachrichten über die Vonage Messages API versendet.

Sie haben gelernt, wie das geht:

• Konfigurieren Sie eine Vonage WhatsApp-Anwendung

• Ausgehende Textnachrichten von Rails aus senden

• Hinzufügen von interaktiven Schaltflächen für mehr Unterhaltung

An welchen anderen Rails-Themen sind Sie interessiert? Haben Sie schon RCS (Rich Communications Services) gespielt? Versuchen Sie das Senden von RCS Suggested RepliesSie sind wie WhatsApp-Antworten, aber direkt in Ihrer Standard-Messaging-App.

Haben Sie Fragen oder Ideen? Treten Sie uns auf dem Vonage Community Slack oder folgen Sie @VonageDev auf X (früher Twitter).