Wie man RCS Standalone Rich Cards mit Node.js versendet

Rich Communication Services (RCS) verändern die Art und Weise, wie Unternehmen mit ihren Kunden in Kontakt treten. Sie ermöglichen es Ihnen, Bilder, Videos und interaktive Elemente zu Nachrichten hinzuzufügen, die in den Standard-Messaging-Apps der Nutzer angezeigt werden. Eine leistungsstarke Funktion von RCS ist die eigenständige Rich Carddie Text, Bilder oder Videos und Antwortvorschläge in einer einzigen interaktiven Nachricht kombiniert.

Mit der weltweit zunehmenden Verbreitung von RCS unter Android und iOS ist jetzt der perfekte Zeitpunkt, um Rich Messaging in Ihre Applications zu integrieren. In diesem Tutorial erfahren Sie, wie Sie eine eigenständige Rich Card mit der Vonage Messages API in einer Node.js-App versenden können.

>> TL;DR: Siehe den vollständigen funktionierenden Code auf GitHub

Was ist eine eigenständige RCS Rich Card?

A eigenständige Rich Card kombiniert mehrere Nachrichtenkomponenten wie Medien, einen Titel, Beschreibungstext und bis zu vier Antwortvorschläge in einer einzigen Rich Message. Diese Nachrichten sind visuell ansprechend und bieten Nutzern sofortige Interaktionsmöglichkeiten, ohne dass sie eine Antwort eingeben müssen.

Eine gültige eigenständige Rich Card muss mindestens einen Titel oder ein Media Element enthalten. Sie kann auch enthalten:

• Eine Beschreibung (max. 2000 Zeichen)

• Ein Bild oder Video (bis zu 100 MB)

• Bis zu vier Antwortvorschläge oder Handlungsvorschläge (nicht beides)

Voraussetzungen

Bevor Sie beginnen, benötigen Sie Folgendes:

• Node.js installiert auf Ihrem Rechner. Node Version 22+

• ngrok installiert um Ihren lokalen Server für das Internet freizugeben.

• Ein Vonage API-Konto.

• Ein registrierter RCS Business Messaging (RBM) Agent, siehe verwaltete Konten unten.

• Ein Telefon 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.

So kontaktieren Sie Ihren Vonage Account Manager

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 Sie Ihr Node.js-Projekt einrichten

Diese Anleitung setzt voraus, dass Sie mit den Grundlagen von JavaScript und Node.js vertraut sind.

Initialisieren Sie das Projekt

Erstellen Sie ein neues Verzeichnis und initialisieren Sie ein Node.js-Projekt:

mkdir rcs-standalone-richcard-node
cd rcs-standalone-richcard-node
npm init -y

Erforderliche NPM-Pakete installieren

Installieren Sie die erforderlichen Node-Pakete mit Node-Paket-Manager (NPM):

npm install express dotenv @vonage/server-sdk

• express: Erzeugt den Webserver

• dotenv: Lädt Ihre Umgebungsvariablen

• @vonage/server-sdk: Versendet Nachrichten über die Vonage Messages API

Erstellen Sie Ihre Projektdateien

Erstellen Sie die Hauptanwendungsdatei und die Umgebungskonfigurationsdatei:

touch index.js .env

So konfigurieren Sie Ihre Umgebung

In der Datei .env Datei fügen Sie Ihre Vonage-Anmeldedaten und Ihre Konfiguration hinzu:

VONAGE_APPLICATION_ID=your_application_id
VONAGE_API_SIGNATURE_SECRET=your_api_secret
VONAGE_PRIVATE_KEY=./private.key
RCS_SENDER_ID=your_rbm_agent_id
PORT=3000

• VONAGE_APPLICATION_ID: Ihre Vonage-Anwendungs-ID.

• VONAGE_API_SIGNATUR_GEHEIMNIS= Ihr Vonage API-Signaturgeheimnis.

• VONAGE_PRIVATE_KEY: Die Datei des privaten Schlüssels Ihrer Vonage-Anwendung.

• RCS_SENDER_ID: Ihre RBM-SenderID (der Name der Marke). Die SenderID erfordert eine besondere Formatierung, z. B. ohne Leerzeichen. Wenden Sie sich an Ihren Account Manager, wenn Sie unsicher sind.

• PORT: Portnummer für den Express-Server.

Sie erhalten Ihre Vonage Anwendungs-ID und private.key-Datei weiter unten im Abschnitt "Erstellen und Konfigurieren der Vonage Anwendung". Ihr API-Signaturgeheimnis finden Sie in Ihren Entwickler-Dashboard-Einstellungen.

So senden Sie eine eigenständige RCS Rich Card

Die index.js Datei bietet Ihrem Express-Server die Möglichkeit, RCS Rich Cards mit Antwortvorschlägen zu versenden.

Abhängigkeiten laden und den Vonage-Client initialisieren

Fügen Sie diesen Code zu Ihrer index.js Datei hinzu:

const express = require('express');
const fs = require('fs');
const dotenv = require('dotenv');
const { Vonage } = require('@vonage/server-sdk');
const { verifySignature } = require('@vonage/jwt');

dotenv.config();

const app = express();
app.use(express.json());

const PORT = process.env.PORT || 3000;

const VONAGE_API_SIGNATURE_SECRET = process.env.VONAGE_API_SIGNATURE_SECRET;

const privateKey = fs.readFileSync(process.env.VONAGE_PRIVATE_KEY);

const vonage = new Vonage({
  applicationId: process.env.VONAGE_APPLICATION_ID,
  privateKey: privateKey
});

Definieren eines Express-Endpunkts zum Senden eigenständiger RCS-Rich-Cards

Als nächstes erstellen Sie die /send-standalone-rich-card Endpunkt. Diese Route erstellt und sendet eine Rich-Card-Nachricht über die Vonage Messages API. Bei dieser Implementierung müssen Sie in Ihrer Anfrage nur die Telefonnummer des Empfängers angeben.

Rich Cards bestehen aus mehreren Elementen: Medien, Titel, Beschreibung und vorgeschlagene Antworten oder vorgeschlagene Aktionen. In diesem Beispiel versenden wir eine einzelne Karte mit einem GIF von Oscar, unserem Bürohund, zusammen mit interaktiven Schaltflächen. Diese ermöglichen es den Nutzern, schnell mit Optionen wie "Streichle den Welpen" oder "Adoptiere mich!" zu reagieren.

app.post('/send-standalone-rich-card', async (req, res) => {
  const toNumber = req.body.to;

  const message = {
    to: toNumber,
    from: process.env.RCS_SENDER_ID,
    channel: 'rcs',
    message_type: 'custom', // Required for sending rich cards
    custom: {
      contentMessage: {
        richCard: {
          standaloneCard: {
            thumbnailImageAlignment: "RIGHT", // Aligns image on the right in horizontal layouts
            cardOrientation: "VERTICAL", // Stack elements vertically
            cardContent: {
              title: "Meet our office puppy!", // Main headline for the card
              description: "What would you like to do next?", // Secondary text to provide context
              media: {
                height: "TALL", // Height options: SHORT, MEDIUM, TALL
                contentInfo: {
                  fileUrl: "https://raw.githubusercontent.com/Vonage-Community/tutorial-messages-node-rcs_standalone-rich-card/refs/heads/main/puppy_dev.gif",
                  forceRefresh: false // Set to true if media changes often
                }
              },
              suggestions: [
                { reply: { text: "Pet the puppy", postbackData: "pet_puppy" }},
                { reply: { text: "Give a treat", postbackData: "give_treat" }},
                { reply: { text: "Take a selfie", postbackData: "take_selfie" }},
                { reply: { text: "Adopt me!", postbackData: "adopt_puppy" }}
              ]
            }
          }
        }
      }
    }
  };

  try {
    const response = await vonage.messages.send(message);
    console.log('Standalone rich card sent:', response);
    res.status(200).json({ message: 'Standalone rich card sent successfully.' });
  } catch (error) {
    console.error('Error sending standalone rich card:', error);
    res.status(500).json({ error: 'Failed to send standalone rich card.' });
  }
});

Sie können diesen Endpunkt anpassen, indem Sie dynamische Werte wie den Kartentitel, die Beschreibung oder die Liste der vorgeschlagenen Antworten im POST-Text übergeben. So können Sie personalisierte Rich Cards senden, die auf verschiedene Benutzer oder Anwendungsfälle zugeschnitten sind.

Wie man RCS-Antworten über Webhooks empfängt

Wenn ein Benutzer eine der vorgeschlagenen Antworten von Ihrer Rich Card antippt, sendet Vonage einen eingehenden Webhook an Ihre Anwendung. Dieser Webhook enthält strukturierte Daten über die Interaktion des Benutzers, einschließlich der reply.iddie mit der postbackData Wert übereinstimmt, den Sie zuvor definiert haben.

Erstellen Sie eine /inbound_rcs Endpunkt, um diese Antworten zu verarbeiten und mit einer personalisierten Nachricht zu antworten.

app.post('/inbound_rcs', async (req, res) => {
  // Step 1: Extract and verify the JWT signature
  const token = req.headers.authorization?.split(' ')[1];

  if (!verifySignature(token, VONAGE_API_SIGNATURE_SECRET)) {
    res.status(401).end();
    return;
  }

  // Step 2: Parse the inbound message payload
  const inboundMessage = req.body;

  if (inboundMessage.channel === 'rcs' && inboundMessage.message_type === 'reply') {
    const userSelection = inboundMessage.reply.id;
    const userNumber = inboundMessage.from;

    console.log(`User ${userNumber} selected: ${userSelection}`);

    // Step 3: Map each reply ID to a personalized confirmation
    const responseMessages = {
      pet_puppy: "🐶 Oscar loves pets!",
      give_treat: "🍪 Treat accepted! Oscar is wagging his tail.",
      take_selfie: "📸 Smile! Oscar’s photogenic and ready.",
      adopt_puppy: "Wow! Oscar is so lucky! You're a real hero 🦸"
    };

    const confirmationText =
      responseMessages[userSelection] || "Oscar appreciates the love! 🐾";

    // Step 4: Send a confirmation message back to the user
    const confirmationMessage = {
      to: userNumber,
      from: process.env.RCS_SENDER_ID,
      channel: 'rcs',
      message_type: 'text',
      text: confirmationText
    };

    try {
      const response = await vonage.messages.send(confirmationMessage);
      console.log('Confirmation sent:', response);
    } catch (error) {
      console.error('Error sending confirmation:', error);
    }
  }

  res.status(200).end();
});

Was passiert in diesem Code?

Zunächst wird die Webhook-Anfrage mithilfe des JWT-Tokens überprüft, um sicherzustellen, dass sie wirklich von Vonage stammt. Dann wird die Auswahl des Benutzers mit reply.idab, die mit der postbackData aus der Rich Card übereinstimmt. Basierend auf dieser ID wählen wir eine passende Nachricht aus den responseMessages Objekt. Dies ist ein einfaches Beispiel dafür, wie Sie das Benutzererlebnis auf der Grundlage der getippten Schaltfläche anpassen können.

So definieren Sie Ihren Express Server

Am Ende der Datei index.jsfügen Sie diesen Code hinzu, um Ihren Express-Server zu erstellen.

app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

Und schließlich starten Sie Ihren Server über die Befehlszeile:

node index.js

>> Siehe die vollständige index.js-Datei.

Terminal output from a Node.js application sending an RCS standalone rich card, showing server activity and user interaction response with message UUIDs.

Wie Sie Ihren Server mit ngrok freilegen

Um Webhooks von Vonage zu empfangen, muss Ihr lokaler Server über das Internet erreichbar sein. Verwenden Sie ngrok, um Ihren Server freizugeben, indem Sie den folgenden Befehl ausführen in einer separaten Registerkarte Ihres Express-Servers ausführen:

ngrok http 3000

Beachten Sie die von ngrok bereitgestellte HTTPS-URL (z. B. https://your-ngrok-subdomain.ngrok.io).

Sie können mehr lesen über Testen mit ngrok in unserem Entwicklerportal nachlesen.

So erstellen und konfigurieren Sie Ihre Vonage-Anwendung

Jetzt, wo Ihre Node-App fertig ist, müssen Sie auch Ihre Vonage-Anwendung erstellen und einrichten. Erstellen Sie zunächst Ihre App im Vonage Dashboard. Geben Sie der App einen Namen und schalten Sie die Nachrichtenfunktion ein.

Vonage dashboard showing the creation of a new application configured for RCS messaging.

In den Einstellungen Ihrer Vonage-Anwendung:

1. Setzen Sie die Eingangs-URL auf https://YOUR_NGROK_URL/inbound_rcs.

2. Setzen Sie die Status-URL auf https://example.com/rcs_statusDer Nachrichtenstatus wird in einem späteren Artikel behandelt.

3. Erzeugen Sie einen öffentlichen und einen privaten Schlüssel, indem Sie auf die Schaltfläche klicken. Stellen Sie sicher, dass Sie Ihren private.key Datei in das Stammverzeichnis des Projekts (rcs-standalone-richcard-node).

4. Speichern Sie die Änderungen.

Verknüpfen Sie dann Ihren RCS-Agenten, indem Sie auf die Schaltfläche "Externe Konten verknüpfen" Registerkarte:

Dashboard view showing the Vonage-Node-RCS application linked to the Vonage RoR RCS external account, with voice and message capabilities enabled.

Wie Sie Ihre Node-Anwendung testen

Verwenden Sie diese curl Befehl, um Ihren Endpunkt auszulösen (Platzhalter ersetzen):

curl -X POST https://YOUR_NGROK_URL/send-standalone-rich-card \
  -H "Content-Type: application/json" \
  -d '{"to": "YOUR_RCS_TEST_NUMBER"}'

Auf dem Telefon des Empfängers sollte die eigenständige Rich Card mit den GIF- und Antworttasten erscheinen.

Interactive RCS chat showcasing Vonage bot's playful engagement with users through options like petting, feeding, or adopting a virtual office puppy.

Schlussfolgerung

Sie haben mit Node.js und der Vonage Messages API erfolgreich eine RCS Standalone Rich Card mit Medien, einem Titel, einer Beschreibung und Antwortvorschlägen versendet.

Rich Cards sind eine großartige Möglichkeit, auffällige, interaktive Erlebnisse direkt in Messaging-Apps bereitzustellen. In zukünftigen Tutorials erfahren Sie, wie Sie Karussells verwenden, den Nachrichtenstatus verfolgen und Rich Cards mit Bot-Logik kombinieren können.

Zeigen Sie, was Sie mit RCS bauen und fordern Sie zukünftige Inhalte auf der Vonage Community Slack. Sie können sich auch auf X (früher Twitter). Wir würden uns freuen, Ihre RCS-Welpen zu sehen!