Senden von RCS-Vorschlagsantworten mit Ruby on Rails

Rich Communication Services (RCS) verändert die Art und Weise, wie Unternehmen mit ihren Kunden in Kontakt treten. Als Weiterentwicklung der SMS bietet RCS ein reichhaltigeres, interaktives Erlebnis mit Funktionen wie Bildern, Videos, Dateifreigabe und Antwortvorschlägen, und zwar direkt in der Standard-Messaging-App des Nutzers. Sehen Sie sich all die coolen RCS-Funktionen.

Mit der Einführung der RCS-Unterstützung auf der ganzen Welt, sowohl für Android als auch für iOS, ist jetzt der perfekte Zeitpunkt, um sich mit dieser Technologie zu beschäftigen. In diesem Tutorial erfahren Sie, wie Sie mit der Vonage Messages API in einer Ruby on Rails-Anwendung RCS-Antwortvorschläge senden und so dynamischere und ansprechendere Konversationen mit Ihren Nutzern erstellen können.

>> TL;DR Überspringen Sie den Anfang und finden Sie den gesamten Schnellstart-Code auf GitHub.

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

Voraussetzungen

• Ruby on Rails installiert auf Ihrem Rechner

• Ein ngrok Account.

  • Wenn Sie neu im Bereich der Tunneldienste sind oder Hilfe bei der Einrichtung eines solchen Dienstes benötigen, lesen Sie unsere Anleitung zu Verwendung von ngrok in Rails im Jahr 2025 für eine Schritt-für-Schritt-Anleitung zur Konfiguration von öffentlichen Tunneln für Webhooks.

• Ein registrierter RBM-Agent

• Eine Telefonnummer mit RCS-Funktionen für Tests

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.

Wie man einen RBM-Agenten registriert

Um RCS-Funktionen in Ihrer Vonage-Anwendung senden und empfangen zu können, benötigen Sie einen registrierten Rich Business Messaging (RBM)-Agenten und ein Telefon mit RCS-Funktionen.

Derzeit ist RCS Messaging über Vonage nur für verwaltete Accounts verfügbar. Sie müssen Ihren Account Manager kontaktieren, um die Aktivierung des Entwicklermodus für Ihren RBM-Agenten zu beantragen. Der Entwicklermodus ermöglicht es Ihnen, RCS Messaging an zugelassene Numbers zu testen, bevor Sie den Agent-Verifizierungsprozess abschließen und in die Produktion einsteigen.

Bitte kontaktieren Sie unser Verkaufsteam wenn Sie noch keinen verwalteten Account haben.

>> Verstehen Sie den Unterschied zwischen RCS und RBM.

Wie man eine Ruby on Rails-Anwendung erstellt

In diesem Tutorial wird davon ausgegangen, dass Sie über ein grundlegendes Verständnis von Ruby und Rails verfügen, wobei wir uns auf die erforderlichen Befehle beschränken, ohne zu viel zu erklären.

Zunächst erstellen wir unser neues Projekt.

rails new vonage-rails-quickstart

Als Nächstes gehen Sie in das Projekt und fügen das Vonage-Gem zu Ihrem Gemfile hinzu, damit wir auf das Vonage-SDK zugreifen können. Wir fügen auch dotenv-rails hinzu, damit wir Umgebungsvariablen sicher verwenden können.

# Gemfile

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

Führen Sie dann den Bundler aus, um unsere Gems zu installieren.

bundle install

Was ist eine RCS-Vorschlagsantwort?

Schauen wir uns zunächst an, wie vorgeschlagene Antworten in RCS funktionieren. Vorgeschlagene Antworten sind Teil einer benutzerdefinierten RCS-Nachricht, einem flexiblen Format, mit dem Sie interaktive Elemente wie Antwortschaltflächen direkt in Ihrem Nachrichteninhalt definieren können. Anstatt reinen Text zu senden, können Sie Benutzer mit antippbaren Optionen auffordern, Konversationen schneller, reichhaltiger und einfacher zu navigieren zu machen.

Betrachten wir nun unser RcsMessage-Modell, das seine Attribute und deren Speicherung in der Datenbank definiert. RCS-Nachrichten in der Messages API können einen von 5 Typen haben: Text, Bild, Video, Dateioder benutzerdefinierte. Vorgeschlagene Antworten sind von benutzerdefiniert die die folgende Grundstruktur haben:

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

Hier wird es jedoch knifflig, denn das Schema eines benutzerdefinierten Objekts stark variieren kann. Lesen Sie mehr über RCS Custom Messages.

In unserem Anwendungsfall erwartet die API, dass eine ausgehende vorgeschlagene Nachricht diese Struktur hat:

{
 "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"
          }
        }
     ]
  }
 }
}

Und wenn der Benutzer auf die Schaltfläche "Vorgeschlagene Antwort" klickt, sieht die Antwort wie folgt aus:

{
  "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"
  }
}

So erstellen Sie ein RCS-Vorschlagsmodell

Wie können wir ein flexibles und dynamisches RCS-Nachrichtenmodell erstellen, das beiden Situationen gerecht wird? Glücklicherweise erlaubt uns ActiveRecord die Verwendung von JSON als Datentyp direkt in unserem Modell zu verwenden.

Wir brauchen 7 Felder:

• an: der Empfänger des RCS.

• von: der Absender des RCS.

• StatusStatus: ob ein RCS erfolgreich zugestellt wurde oder nicht.

• nachricht_uuidmessage_uuid: die der Nachricht zugeordnete Vonage-ID, die für die Verfolgung des Status von Nachrichten wichtig ist.

• Zeitstempel: wenn ein Benutzer auf den Vorschlag geantwortet hat.

• benutzerdefinierte: JSON-Objekt, das der Messages API mitteilt, dass es sich um eine vorgeschlagene Antwortnachricht handelt, und das die vorgeschlagene Nachricht zusammen mit Vorschlägen enthält.

• Antwort: JSON-Objekt, das der Messages API mitteilt, dass dies eine Antwort auf eine vorgeschlagene Nachricht ist.

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

Außerdem müssen wir unsere Datenbank mit dem neuen Modell aktualisieren.

rails db:migrate

Erstellen eines Outbound RCS Controllers

Erstellen wir unseren Controller, der unsere Logik verarbeitet.

rails g controller OutboundRcs new create

Zum Schluss legen wir unsere Routen für ausgehende SMS fest.

# 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

So erstellen Sie eine Vonage-Anwendung

Jetzt, wo unsere Rails-App fertig ist, müssen wir auch unsere Vonage-Anwendung erstellen und einrichten. Zuerst müssen wir unsere App im Dashboard von Vonage. Geben Sie der App einen Namen und schalten Sie die Nachrichtenfunktion ein. Sie können für den Moment Platzhalter-URLs für die Webhooks hinzufügen. In weiteren Blogbeiträgen werden wir diese aktualisieren, außerdem müssen Sie Ihre Anwendung mit Ihrem RCS-Agenten verknüpfen. Da in diesem Beitrag nur ausgehende Nachrichten behandelt werden und die Verwendung von Webhooks nicht erforderlich ist, können wir dies vorerst auslassen.

A screenshot of the Vonage Developer dashboard showing the creation of a new application with authentication, privacy, and messaging capabilities settings.Stellen Sie sicher, dass Sie einen privaten Schlüssel generieren, indem Sie auf "Öffentlichen und privaten Schlüssel generieren" klicken. Dadurch wird eine private.key-Datei auf Ihren Computer heruntergeladen. Verschieben Sie dann die private.key-Datei in das Stammverzeichnis Ihrer Rails-Anwendung.

Notieren Sie sich bei der Erstellung Ihrer Anwendung die Anwendungs-ID; Sie benötigen sie im nächsten Schritt.

Erstellen Sie eine .env Datei im Stammverzeichnis Ihrer Rails-Anwendung:

touch .env

Fügen Sie abschließend die folgenden Schlüssel mit Ihren Anmeldeinformationen hinzu.

# .env

VONAGE_APPLICATION_ID=''

VONAGE_PRIVATE_KEY='./private.key'

RCS_SENDER_ID=''

Hinweis: RCS_SENDER_ID ist Ihr RCS-Markenname. Achten Sie auf die Formatierungsanforderungen. Leerzeichen sind zum Beispiel nicht erlaubt. Wenn Ihr RCS Markenname zum Beispiel "Ruby on Rails Quickstart" lautet, dann würde die SENDER_ID "RubyonRailsQuickstart" lauten.

Initialisierung des Vonage Ruby Clients

Bevor wir den Ruby-Client in einer kompletten Rails-Anwendung aktivieren, wollen wir sehen, wie wir ihn allgemein in Ruby-Code verwenden können. Um den Client zu verwenden, müssen wir lediglich eine Instanz mit den in unserer Umgebungsdatei gespeicherten Anwendungsinformationen initialisieren.

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

Möchten Sie einen tieferen Einblick in die sichere Verwaltung von API-Anmeldeinformationen erhalten? Lesen Sie Arbeiten mit Umgebungsvariablen in Ruby.

Wie man eine RCS-Nachricht in Ruby sendet

Nachdem unser Client nun initialisiert ist, wird das Senden einer RCS-Nachricht zu einem recht einfachen Prozess in zwei Schritten. Wir rufen die Nachrichtenübermittlung Methode auf, um dem Client mitzuteilen, dass er die Messages API verwenden soll, und erstellen dann unsere RCS-Nachricht:

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"
          }
        }
      ]
    }
  }
)

Dann übergeben wir unsere Nachricht an die Sendemethode. Beachten Sie, dass die von Feld Ihre RBM SenderID (der Name der Marke) ist. Die SenderID erfordert eine spezielle Formatierung, z. B. ohne Leerzeichen. Erkundigen Sie sich bei Ihrem Account Manager, wenn Sie unsicher sind.

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

Senden von RCS in einer Ruby on Rails-Anwendung

Nachdem wir uns nun damit beschäftigt haben, wie man den Vonage Ruby-Client zum Senden von RCS verwendet, wollen wir nun eine Ruby on Rails-Funktionalität zum Senden von RCS in unsere Anwendung mit einem einfachen Formular und Controller integrieren. Wir brauchen eine schöne UI, um die an, contentMessage textund Vorschläge Antwort Felder. RCS kann bis zu 11 Antwortvorschläge verarbeiten, daher haben wir eine Schaltfläche "Einen weiteren Vorschlag hinzufügen" hinzugefügt, mit der Sie so viele Vorschläge erstellen können, wie Sie möchten!

Sie können das Formular kopieren und in Ihre /app/views/outbound_rcs/new.html.erb Ansicht und zugehöriges CSS. Das Formular enthält Platzhalter, damit Sie wissen, welche Art von Eingaben erwartet wird.

User interface for sending an RCS message, showing fields to enter the recipient's phone number, content message, and suggested reply options.Nun wollen wir die Logik implementieren, damit unser Formular funktioniert. Zunächst müssen wir eine leere RCS-Instanz erstellen, um das Formular zu laden. Dann, wenn das Formular abgeschickt wird, lösen wir die create-Methode aus.

Es sollte so einfach sein wie die Übergabe unserer erforderlichen Parameter (an, von, und benutzerdefinierte) aus dem Formular, um eine neue @rcs_message Instanz zu erstellen. Leider ist es ein bisschen komplizierter als das. Aber was passiert da eigentlich?

# 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

Es sieht nämlich ein bisschen unordentlich aus:

1) Unser RCS-Modell verwendet den flexiblen JSON-Datentyp für unsere benutzerdefiniertes Feld, was bedeutet, dass unser Formular dynamisch ist und jeden Vorschlag verpackt. Aber es bedeutet auch, dass wir nicht sicher sind, wie viele Vorschläge übergeben werden.

2) Wir müssen das JSON-Objekt so erstellen, wie es die API erwartet. Unser Formular liefert den Text jedes Vorschlags, aber wir müssen noch das Vorschläge in ein Array mit dem Paar von Text und postbackData.

Um dieses Problem zu lösen, können wir eine private Controller-Methode definieren, construct_custom_messagedefinieren, um unsere benutzerdefinierte Feld zu erstellen und es dann zu der neu erstellten @rcs_message Instanz hinzu.

 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

Nun, da unsere @rcs_message alle erforderlichen Felder enthält, können wir versuchen, sie in unserer Datenbank zu speichern und dann die Messages API bitten, sie zuzustellen.

Die liefern Methode ist weitgehend identisch mit der im vorigen Abschnitt verwendeten Methode, nur dass sie jetzt die Messages Nachricht Objekt verwendet und die API-Antwort verarbeitet.

Wenn die Nachricht erfolgreich gesendet wurde, wird ein Statuscode 202 zusammen mit einer nachricht_uuid. Diese UUID hilft bei der Verfolgung des Zustellungsstatus mit Hilfe der Nachrichtenstatuszu verfolgen, den wir im nächsten Beitrag behandeln werden.

 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

Siehe die vollständige outbound_rcs_controller.rb Datei.

Starten Sie nun Ihren Rails-Server:

rails s

Und öffnen http://localhost:3000/outbound_rcs/new in Ihrem Browser. Sie können nun RCS über Ihre Ruby on Rails-Anwendung senden!

Ruby SDK vs. Messages API

Vielleicht haben Sie bemerkt, dass in unserem liefern Methode, wir verwenden Typ anstelle von nachrichten_typ wie definiert in der Messages API Referenz. Der Grund dafür ist, dass das Ruby SDK die Messages API abstrahiert und einfach verlangt, dass wir den Typ und Nachricht. Zusätzlich können wir alle zusätzlichen Optionen über die opts Parameter übergeben. Siehe mehr Beispiele in der README.

Wenn Sie es vorziehen, können Sie die Abstraktion überspringen und die Messages API direkt über die Senden Methode aufrufen:

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

Schlussfolgerung

Gut gemacht! Sie haben Ihren ersten Schritt zur Erstellung von innovativen Messaging-Erlebnissen mit RCS gemacht und interaktive Antwortvorschläge aus einer Ruby on Rails-Anwendung mit der Vonage Messages API gesendet.

Sind Sie bereit, Ihre Anwendung interaktiv zu gestalten? Lernen Sie, wie Sie Benutzereingaben verarbeiten, indem Sie RCS-Antwortvorschläge in Ruby on Rails empfangen. Sie können auch die Zustellung von Nachrichten in Echtzeit verfolgen, indem Sie RCS-Nachrichtenstatus-Updates in Ruby on Rails erhalten.

Wenn Sie Fragen oder Vorschläge für weitere Ruby- oder RCS-Inhalte haben, beteiligen Sie sich an der Diskussion mit uns in der Vonage Gemeinschaft Slack oder kontaktieren Sie uns auf X, früher bekannt als Twitter. Wir würden uns freuen zu hören, was Sie als nächstes bauen!