Comment envoyer des carrousels de cartes riches RCS avec Node.js

Introduction

Rich Communication Services (RCS) vous donne les outils nécessaires pour créer des expériences de marque modernes et interactives au sein même de l'application de messagerie par défaut de l'utilisateur. L'une de ses fonctionnalités les plus puissantes est le carrousel de cartes riches: un ensemble de cartes à défilement horizontal pouvant inclure des vidéos, des images, du texte et des actions tactiles.

Dans ce tutoriel, vous apprendrez à envoyer un carrousel RCS à l'aide de Node.js et de l'API Vonage Messages API. Vous combinerez des cartes vidéo et image avec des actions pour stimuler l'engagement.

>> TL;DR : Voir le code de travail complet sur GitHub

Cas d'utilisation : Annonce d'un pop-up de mode

Imaginons que votre marque lance une boutique pop-up de mode à durée limitée. Vous voulez générer du buzz et mettre en avant des articles clés. Avec un carrousel RCS, vous pouvez regrouper tout cela dans un message propre et interactif.

Votre carrousel RCS comprendra des médias et des actions suggérées :

1. Carte 1 : Video de lancement de l'événement

   • Video trailer pour le popup

   • 2 actions : "Réservez la date" et "Voir le lieu".

2. Carte 2 : T-Shirts image :

   • Une image du tee-shirt présenté

   • action : "Voir toutes les chemises

3. Carte 3 : Chapeau image :

   • Une image de votre collection de chapeaux

   • action : "Voir tous les chapeaux

Qu'est-ce qu'un carrousel RCS ?

Un carrousel RCS est un ensemble de cartes riches pouvant être glissées, chacune ayant son propre contenu :

• Un titre (200 caractères maximum)

• Une description (max 2000 caractères)

• Média : image ou Video

• Jusqu'à quatre propositions de réponses ou d'actions

Les cartes apparaissent horizontalement, ce qui permet aux utilisateurs de les parcourir.

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.

Remarques importantes :

• Toutes les cartes d'un carrousel doivent utiliser le même type de suggestion.

• Les fichiers multimédias doivent être accessibles au public et ne pas dépasser 100 Mo.

• Vous pouvez inclure entre 2 et 10 cartes.

Conditions préalables

Avant de commencer, vous aurez besoin de

• Node.js installé sur votre machine.

• ngrok installé pour exposer votre serveur local à l'internet.

• Un compte API Vonage.

• Un agent RCS Business Messaging (RBM) enregistré, voir les comptes gérés ci-dessous.

• Un téléphone avec des fonctionnalités RCS pour les tests.

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Comment contacter votre Account Manager de Vonage

Afin d'envoyer et de recevoir des capacités RCS dans votre application Vonage, vous devez disposer d'un agent Rich Business Messaging (RBM) enregistré et d'un téléphone doté de capacités RCS.

Actuellement, la messagerie RCS via Vonage n'est disponible que pour les comptes gérés. Vous devrez contacter votre Account Manager pour demander l'activation du mode développeur pour votre agent RBM. Le mode développeur vous permet de tester la messagerie RCS vers des numéros inscrits sur la liste d'autorisation avant de terminer le processus de vérification de l'agent et de lancer en production.

Veuillez contacter contacter notre équipe de vente si vous n'avez pas de compte géré.

>> Comprendre la différence la différence entre RCS et RBM.

Comment configurer votre projet Node.js

Ce guide suppose que vous connaissez les bases de JavaScript et de Node.js.

Initialiser le projet

Créez un nouveau répertoire et initialisez un projet Node.js :

mkdir rcs-carousel-node
cd rcs-carousel-node
npm init -y

Installer les paquets NPM requis

Installer les paquets de nœuds nécessaires avec Node Package Manager (NPM) :

npm install express dotenv @vonage/server-sdk

• exprimer: Crée le serveur web

• dotenv: Charge les variables d'environnement

• @vonage/server-sdk: Envoie des messages par l'intermédiaire de l'API Messages de Vonage

Créez vos fichiers de projet

Créer le fichier de l'application principale et le fichier de configuration de l'environnement :

touch index.js .env

Comment configurer votre environnement

Dans le fichier .env ajoutez vos identifiants et votre configuration Vonage :

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: L'identifiant de votre application Vonage.

• VONAGE_API_SIGNATURE_SECRET= Votre secret API Vonage

• VONAGE_PRIVATE_KEY: Le fichier de clé privée de votre application Vonage.

• RCS_SENDER_ID: Votre RBM SenderID (le nom de la marque). Le SenderID nécessite un formatage particulier, comme l'absence d'espaces. Vérifiez avec votre Account Manager si vous n'êtes pas sûr.

• PORT: Numéro de port du serveur Express.

Vous obtiendrez votre ID d'application Vonage et votre fichier private.key ci-dessous, dans la section "Comment créer et configurer l'application Vonage". dans la section "Comment créer et configurer l'application Vonage". Trouvez votre secret API dans la page d'accueil du page d'accueil du tableau de bord du développeur.

Comment envoyer un carrousel RCS

Maintenant que votre environnement est configuré, écrivons le code qui envoie votre carrousel de cartes riches RCS.

Dans cette étape, vous allez créer un serveur Express qui envoie un message RCS personnalisé à l'aide de l'API Messages de Vonage. Le carrousel contiendra trois cartes de produits à glisser, chacune avec un média (vidéo ou image), un titre et une description, et des boutons d'action sur lesquels vos utilisateurs peuvent appuyer.

Charger les dépendances et initialiser le client Vonage

Nous commencerons par importer les paquets nécessaires, charger vos variables d'environnement et initialiser le client Vonage. Ajoutez le code suivant à votre fichier index.js pour commencer :

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
});

Définir un point de terminaison Express pour envoyer un carrousel RCS

Il convient de connaître quelques détails mineurs mais importants avant d'envoyer le carrousel. Tous les fichiers multimédias doivent être accessibles au public via HTTPS, et idéalement hébergés sur un CDN ou un espace de stockage en nuage. Dans cet exemple, nous utilisons des ressources hébergées sur GitHub pour des raisons de simplicité, mais en production, vous aurez besoin d'un hébergement plus rapide et plus fiable.

>> Les fichiers multimédias individuels ne doivent pas dépasser 100 Mo pour respecter les contraintes du RCS.

Chaque carte comprend un ou plusieurs boutons d'action utilisant postbackData, openUrlActionou createCalendarEventAction. L'action postbackData est une chaîne courte (50 caractères maximum) que votre serveur peut utiliser pour suivre ce que les utilisateurs tapent. Vous pouvez également créer des liens directs vers des cartes ou des événements de calendrier pré-remplis pour plus d'interactivité, de sorte que le carrousel ressemble davantage à une mini-application qu'à un simple message.

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." });
  }
});

Comment recevoir des suggestions d'actions RCS via des Webhooks ?

Envoyer un carrousel, c'est bien ! Mais ne serait-il pas agréable de savoir si votre utilisateur a interagi avec votre carrousel ? Avec les webhooks de Vonage, c'est exactement ce que vous pouvez faire.

Créez le point de terminaison suivant, qui traitera les demandes RCS entrantes de notre application Vonage. Ce code :

• Valide que la demande provient de Vonage à l'aide d'une signature JWT

• Recherche le bouton puisque vous attendez une action au lieu d'une réponse et stocke la charge utile dans la propriété userAction

• Enregistre l'action userAction à notre serveur Node pour voir ce que l'utilisateur a sélectionné

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();
});

Comment définir votre serveur Express

Au bas de votre fichier index.jsajoutez ce code pour construire votre serveur Express.

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

Enfin, lancez votre serveur à partir de la ligne de commande :

node index.js

>> Voir le fichier index.js complet.

Comment exposer votre serveur avec ngrok

Pour recevoir des webhooks de Vonage, votre serveur local doit être accessible sur Internet. Utilisez ngrok pour exposer votre serveur en exécutant la commande suivante dans un onglet séparé de votre serveur Express :

ngrok http 3000

Notez l'URL HTTPS fournie par ngrok (par exemple, https://your-ngrok-subdomain.ngrok.io).

Vous pouvez en savoir plus sur les tests avec ngrok dans notre portail d'outils pour les développeurs.

Comment créer et configurer votre application Vonage

Maintenant que votre application Node est prête, vous devrez également créer et configurer votre application Vonage. Tout d'abord, créez votre application dans le tableau de bord Vonage. Donnez-lui un nom et activez la fonction Messages.

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

Dans les paramètres de votre application Vonage :

1. Définissez l'URL entrante sur https://YOUR_NGROK_URL/inbound_rcs.

2. Définissez l'URL de l'état comme suit https://example.com/rcs_status.
   ** Les statuts des messages seront abordés dans un prochain article.

3. Générez une clé publique et une clé privée en cliquant sur le bouton. Veillez à déplacer votre clé.privée dans le répertoire racine du projet (rcs-carousel-node).

4. Enregistrez les modifications.

Reliez ensuite votre agent RCS en cliquant sur le bouton "Lier des Account externes" l'onglet "Lier des comptes externes" :

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

Comment tester votre application Node

Utilisez cette curl pour déclencher votre point d'accès (remplacez les espaces réservés) :

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

Sur le téléphone du destinataire, le carrousel de cartes s'affiche et il peut sélectionner une action !

Notes finales

Vous avez maintenant construit un carrousel de produits RCS interactif avec Node.js et l'API Messages de Vonage. C'est un excellent moyen de présenter des produits, de promouvoir des événements ou de proposer des choix dynamiques dans un seul message.

Vous voulez aller plus loin ?

• Répondre aux pressions et aux sélections par l'intermédiaire de postbackData

• Charger dynamiquement des fiches produits à partir d'une API

• Ajouter des filtres ou des catégories basés sur la localisation

Venez montrer ce que vous construisez dans le Slack de la communauté Vonage. Communauté Vonage Slack ou marquez-nous sur X (anciennement Twitter). Nous aimerions voir vos carrousels dans la nature !