Wie man RCS Rich Card Karussells mit Node.js sendet

Einführung

Rich Communication Services (RCS) gibt Ihnen die Werkzeuge an die Hand, um moderne, interaktive Markenerlebnisse direkt in der Standard-Messaging-App eines Nutzers zu erstellen. Eine der leistungsfähigsten Funktionen ist das Rich Card Carousel: ein horizontal scrollbarer Satz von Karten, der Videos, Bilder, Text und antippbare Aktionen enthalten kann.

In diesem Tutorial lernen Sie, wie Sie ein RCS-Karussell mit Node.js und der Vonage Messages API. Sie werden Video- und Bildkarten mit Aktionen kombinieren, um das Engagement zu steigern.

>> TL;DR: Sehen Sie sich den vollständigen Arbeits Code auf GitHub

Anwendungsfall: Mode-Popup-Ankündigung

Angenommen, Ihre Marke lanciert einen zeitlich begrenzten Mode-Pop-up-Shop. Sie möchten für Aufsehen sorgen und die wichtigsten Artikel präsentieren. Mit einem RCS-Karussell können Sie dies alles in einer klaren, interaktiven Botschaft verpacken.

Ihr RCS-Karussell wird Medien und vorgeschlagene Aktionen enthalten:

1. Karte 1: Video zum Start der Veranstaltung

   • Video-Trailer für das Popup

   • 2 Aktionen: "Save the Date" und "See Location"

2. Karte 2: Bild T-Shirts:

   • Ein Bild des vorgestellten T-Stücks

   • Aktion: "Alle Hemden sehen"

3. Karte 3: Bild der Hüte:

   • Ein Bild Ihrer Hutsammlung

   • Aktion: "Alle Hüte sehen"

Was ist ein RCS-Karussell?

Ein RCS-Karussell besteht aus einer Reihe von durchstreichbaren Rich Cards, die jeweils über eine eigene Karte verfügen:

• Ein Titel (max. 200 Zeichen)

• Eine Beschreibung (max. 2000 Zeichen)

• Medien: Bild oder Video

• Bis zu vier Antwort- oder Aktionsvorschläge

Die Karten werden horizontal angezeigt, so dass die Benutzer sie durchstreichen können.

Illustration of an RCS carousel message in the Android Messages app, annotated to show benefits like trusted branding, verified sender ID, richer media cards, time-saving action buttons, and quick-reply suggestions.

Wichtige Hinweise:

• Alle Karten in einem Karussell müssen die gleiche Art von Vorschlägen verwenden.

• Die Mediendateien müssen öffentlich zugänglich sein und dürfen nicht größer als 100 MB sein.

• Sie können zwischen 2 und 10 Karten hinzufügen.

Voraussetzungen

Bevor Sie beginnen, benötigen Sie Folgendes:

• Node.js installiert auf Ihrem Rechner.

• 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-carousel-node
cd rcs-carousel-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-Geheimnis

• 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 Ihre private.key-Datei weiter unten, im Abschnitt "So erstellen und konfigurieren Sie die Vonage-Anwendung" Abschnitt. Ihr API-Geheimnis finden Sie auf der Startseite des Entwickler-Dashboards.

Wie man ein RCS-Karussell sendet

Nun, da Ihre Umgebung eingerichtet ist, schreiben wir den Code, der Ihr RCS-Rich-Card-Karussell tatsächlich sendet.

In diesem Schritt erstellen Sie einen Express-Server, der eine benutzerdefinierte RCS-Nachricht über die Vonage Messages API sendet. Das Karussell enthält drei durchstreichbare Produktkarten, jede mit Medien (Video oder Bild), einem Titel und einer Beschreibung sowie Schaltflächen, auf die Ihre Benutzer tippen können.

Abhängigkeiten laden und den Vonage-Client initialisieren

Wir beginnen mit dem Importieren der notwendigen Pakete, dem Laden der Umgebungsvariablen und dem Initialisieren des Vonage-Clients. Fügen Sie den folgenden Code in Ihre index.js Datei hinzu, um die Dinge in Gang zu bringen:

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 eines RCS-Karussells

Bevor wir das Karussell senden, sollten Sie einige kleine, aber wichtige Details wissen. Alle Mediendateien müssen über HTTPS öffentlich zugänglich sein, idealerweise gehostet in einem CDN oder Cloud-Speicher. In diesem Beispiel verwenden wir der Einfachheit halber auf GitHub gehostete Assets, aber in der Produktion werden Sie ein schnelleres und zuverlässigeres Medienhosting benötigen.

>> Halten Sie einzelne Mediendateien unter 100 MB, um RCS-Beschränkungen einzuhalten.

Jede Karte enthält eine oder mehrere Aktionsschaltflächen mit postbackData, openUrlActionoder createCalendarEventAction. Die postbackData Wert ist eine kurze Zeichenkette (max. 50 Zeichen), die Ihr Server verwenden kann, um zu verfolgen, worauf die Benutzer tippen. Sie können auch direkt auf Karten oder vorausgefüllte Kalenderereignisse verlinken, um die Interaktivität zu erhöhen, so dass sich das Karussell eher wie eine Mini-App anfühlt als eine bloße Nachricht.

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

  const message = {
    to: toNumber,
    from: process.env.RCS_SENDER_ID,
    channel: 'rcs',
    message_type: 'custom',
    custom: {
      contentMessage: {
        richCard: {
          carouselCard: {
            cardWidth: "MEDIUM",
            cardContents: [
              {
                title: "Fashion Popup Launch 🎉",
                description: "Join us this weekend for limited drops & exclusive looks.",
                media: {
                  height: "TALL",
                  contentInfo: {
                    fileUrl: "https://raw.githubusercontent.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/main/rcs-fashion-video.gif",
                    thumbnailUrl: "https://raw.githubusercontent.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/main/rcs-fashion-thumbnail.png",
                    forceRefresh: true
                  }
                },
                suggestions: [
                  {
                    "action": {
                      "text": "Save the Date",
                      "postbackData": "save_event",
                      "fallbackUrl": "https://www.google.com/calendar",
                      "createCalendarEventAction": {
                        "startTime": "2024-06-28T19:00:00Z",
                        "endTime": "2024-06-28T20:00:00Z",
                        "title": "Fashion Popup Launch",
                        "description": "Join us this weekend for limited drops & exclusive looks."
                      }
                    }
                  },
                  {
                    action: {
                      text: "See Location",
                      postbackData: "view_location",
                      openUrlAction: {
                        url: "https://maps.google.com/?q=Galleria+Vittorio+Emanuele+II,+Milan,+Italy"
                      }
                    }
                  }
                ]
              },
              {
                title: "Drop 01: T-Shirts",
                description: "Bold graphics. Oversized fit. Designed to stand out.",
                media: {
                  height: "TALL",
                  contentInfo: {
                    fileUrl: "https://raw.githubusercontent.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/main/rcs-fashion-tshirt.png"
                  }
                },
                suggestions: [
                  {
                    action: {
                      text: "See All",
                      postbackData: "see_tshirts",
                      openUrlAction: {
                        url: "https://github.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/blob/main/rcs-fashion-tshirt.png"
                      }
                    }
                  }
                ]
              },
              {
                title: "Drop 02: Hats",
                description: "Top off your look. Fresh colors, bold logos.",
                media: {
                  height: "TALL",
                  contentInfo: {
                    fileUrl: "https://raw.githubusercontent.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/main/rcs-fashion-hat.png",
                  }
                },
                suggestions: [
                  {
                    action: {
                      text: "See All",
                      postbackData: "see_hats",
                      openUrlAction: {
                        url: "https://github.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/blob/main/rcs-fashion-hat.png"
                      }
                    }
                  }
                ]
              }
            ]
          }
        }
      }
    }
  };

  try {
    const response = await vonage.messages.send(message);
    console.log("Carousel sent:", response);
    res.status(200).json({ message: "Carousel sent successfully." });
    console.log("Vonage API response:", JSON.stringify(response, null, 2));
  } catch (error) {
    console.error("Error sending carousel:", error);
    res.status(500).json({ error: "Failed to send carousel." });
  }
});

Wie man RCS-Aktionsvorschläge über Webhooks empfängt

Ein Karussell zu verschicken ist großartig! Aber wäre es nicht schön zu wissen, ob Ihr Nutzer mit dem Karussell interagiert hat? Mit Vonage Webhooks können Sie genau das tun.

Erstellen Sie den folgenden Endpunkt, der eingehende RCS-Anfragen von unserer Vonage-Anwendung verarbeiten wird. Dieser Code:

• Bestätigt, dass die Anfrage von Vonage kommt, indem es eine JWT-Signatur verwendet

• Sucht nach der Schaltfläche Eigenschaft, da Sie eine Aktion erwarten, anstatt einer Antwort Eigenschaft, und speichert die Nutzlast in userAction

• Protokolliert die userAction an unseren Node-Server, um zu sehen, was der Benutzer ausgewählt hat

app.post('/inbound_rcs', async (req, res) => {
  const token = req.headers.authorization?.split(' ')[1];

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

  const inboundMessage = req.body;

  if (inboundMessage.channel === 'rcs' && inboundMessage.message_type === 'button') {
    const userAction = inboundMessage.button.payload;
    const userNumber = inboundMessage.from;

    console.log(`User ${userNumber} tapped action: ${userAction}`);
  }

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

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.

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 von Ihrem Express-Server aus 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_status.
   ** Der Status von Nachrichten 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-carousel-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-rcs-carousel \
  -H "Content-Type: application/json" \
  -d '{"to": "YOUR_RCS_TEST_NUMBER"}'

Auf dem Handy des Empfängers erscheint das Rich Card Karussell und er kann eine Aktion auswählen!

Abschließende Anmerkungen

Sie haben nun ein interaktives RCS-Produktkarussell mit Node.js und der Vonage Messages API erstellt. Dies ist eine großartige Möglichkeit, Produkte zu präsentieren, Veranstaltungen zu bewerben oder dynamische Auswahlmöglichkeiten in einer einzigen Nachricht anzubieten.

Möchten Sie weiter gehen?

• Reagieren Sie auf Tippen und Auswählen über postbackData

• Produktkarten dynamisch von einer API laden

• Ortsbezogene Filter oder Kategorien hinzufügen

Zeigen Sie, was Sie bauen, im Vonage Community Slack oder markieren Sie uns auf X (früher Twitter). Wir würden uns freuen, Ihre Karussells in freier Wildbahn zu sehen!