Comment envoyer des cartes riches autonomes RCS avec Node.js

Les services de communication riches (RCS) remodèlent la façon dont les entreprises se connectent avec leurs clients, en vous permettant d'ajouter des images, des vidéos et des éléments interactifs aux messages qui s'affichent nativement dans les apps de messagerie par défaut des utilisateurs. L'une des fonctionnalités les plus puissantes de RCS est la carte richequi combine du texte, des images ou des vidéos et des suggestions de réponses en un seul message interactif.

Avec l'adoption globale de RCS qui se développe sur Android et iOS, c'est le moment idéal pour intégrer la messagerie riche dans vos Applications. Dans ce tutoriel, vous apprendrez à envoyer une carte riche autonome à l'aide de l'API Messages de Vonage dans une application Node.js.

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

Qu'est-ce qu'une carte riche RCS autonome ?

A carte riche autonome combine plusieurs éléments de message tels que des médias, un titre, un texte de description et jusqu'à quatre suggestions de réponses, en un seul message riche. Ces messages sont visuellement attrayants et offrent aux utilisateurs des options d'interaction immédiates sans qu'ils aient besoin de taper une réponse.

Une carte enrichie autonome valide doit comprendre au moins un titre ou un élément média ou un élément média. Elle peut également contenir :

• Une description (max 2000 caractères)

• Une image ou une vidéo (jusqu'à 100 Mo)

• Jusqu'à quatre suggestions de réponses ou d'actions (pas les deux)

Conditions préalables

Avant de commencer, vous aurez besoin de

• Node.js installé sur votre machine. Node version 22+

• 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-standalone-richcard-node
cd rcs-standalone-richcard-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 de signature de l'API de 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". Trouvez votre secret de signature API dans les paramètres de votre paramètres du tableau de bord du développeur.

Comment envoyer une carte riche RCS autonome ?

L'index index.js permettra à votre serveur Express d'envoyer des RCS Rich Cards avec des suggestions de réponses.

Charger les dépendances et initialiser le client Vonage

Ajoutez ce code à votre index.js fichier :

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 des cartes riches RCS autonomes

Ensuite, construisez la carte /send-standalone-rich-card . Cette route construira et enverra un message de carte riche en utilisant l'API Messages de Vonage. Dans cette implémentation, tout ce que vous devez transmettre dans votre requête est le numéro de téléphone du destinataire.

Les cartes enrichies sont composées de plusieurs éléments : média, titre, description, et des suggestions de réponses ou d'actions. Dans cet exemple, nous envoyons une carte unique contenant un GIF d'Oscar, notre chiot de bureau, ainsi que des boutons interactifs. Ceux-ci permettent aux utilisateurs de répondre rapidement en proposant des options telles que "Caressez le chiot" ou "Adoptez-moi !".

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

Vous pouvez personnaliser ce point de terminaison en transmettant des valeurs dynamiques telles que le titre de la carte, la description ou la liste des réponses suggérées dans le corps du POST. Cela vous permet d'envoyer des cartes personnalisées adaptées à différents utilisateurs ou cas d'utilisation.

Comment recevoir des réponses RCS via des Webhooks ?

Lorsqu'un utilisateur tape sur l'une des réponses suggérées par votre carte enrichie, Vonage envoie un webhook entrant à votre application. Ce webhook contient des données structurées sur l'interaction de l'utilisateur, y compris l'élément reply.idqui correspond à l'élément postbackData que vous avez définie précédemment.

Créer un fichier /inbound_rcs pour traiter ces réponses et y répondre par un message personnalisé.

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

Que se passe-t-il dans ce code ?

Tout d'abord, la demande de webhook est vérifiée à l'aide du jeton JWT pour s'assurer qu'elle provient bien de Vonage. Ensuite, nous récupérons la sélection de l'utilisateur à l'aide de reply.idqui correspond à l'identifiant postbackData de la carte riche. Sur la base de cet identifiant, nous sélectionnons un message correspondant dans la section responseMessages de l'objet responseMessages. Il s'agit d'un exemple simple de la manière dont vous pouvez adapter l'expérience de l'utilisateur en fonction du bouton sur lequel il tape.

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.

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

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_statusLes statuts des messages feront l'objet d'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-standalone-richcard-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-standalone-rich-card \
  -H "Content-Type: application/json" \
  -d '{"to": "YOUR_RCS_TEST_NUMBER"}'

Sur le téléphone du destinataire, la carte riche autonome avec les boutons GIF et réponse devrait apparaître.

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

Conclusion

Vous avez envoyé avec succès une carte riche autonome RCS avec des médias, un titre, une description et des suggestions de réponses en utilisant Node.js et l'API Messages de Vonage.

Les cartes riches sont un excellent moyen de proposer des expériences interactives accrocheuses directement dans les apps de messaging. Dans les prochains tutoriels, vous apprendrez à utiliser les carrousels, à suivre l'état des messages et à combiner les cartes riches avec la logique des robots.

Montrez ce que vous construisez avec RCS et demandez du contenu futur sur le site Communauté Vonage Slack. Vous pouvez également nous contacter sur X (anciennement Twitter). Nous aimerions voir vos chiots RCS !