Créer une superbe application de rappel RCS avec Node SDK et Vonage

Les services de communication riches (RCS) arrivent non seulement sur iOS 18, mais aussi sur Vonage. À partir du début de l'automne 2024, vous pourrez activer l'envoi de RCS par l'intermédiaire de l'API Messages API. RCS est tout aussi facile à utiliser que le SDK Vonage Node, et il prend en charge les cartes riches, les carrousels et les réponses suggérées dès le départ.

Rich Communications Services (RCS) est un protocole de messagerie avancé qui améliore les SMS et MMS traditionnels avec des fonctionnalités telles que la messagerie en temps réel, le partage d'images et de vidéos, et les transferts de fichiers. Il prend en charge des éléments interactifs tels que les chats de groupe, les notifications de frappe et les mises à jour de l'état des messages. Contrairement aux SMS, qui utilisent les réseaux cellulaires, RCS fonctionne sur les données cellulaires et le Wi-Fi, offrant une expérience de messagerie plus polyvalente et plus moderne, similaire à celle d'applications populaires comme WhatsApp et Facebook Messenger. Consultez ce lien pour plus d'informations sur le fonctionnement de RCS avec Vonage.

Pour montrer comment vous pouvez utiliser RCS avec l'API de messagerie de Vonage, nous allons créer une application simple pour nous rappeler de boire de l'eau. Le résultat ressemblera à ceci :

Drink Water Reminder

Conditions préalables

• Vous aurez besoin d'un Compte de développeur Vonage

• Vous aurez besoin d'un service de tunneling API. J'utiliserai ngrok. En savoir plus sur comment utiliser ngrok 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.

Enregistrer un agent RCS avec Google Business Messaging

Vous aurez besoin d'un agent RCS lié à votre compte Vonage pour envoyer et recevoir des messages RCS via l'API Messages Vonage. Pour configurer l'agent, contactez l'assistance Vonage ou votre gestionnaire de compte. Une fois l'agent ajouté à votre compte, vous devriez le voir listé sous "Comptes externes" dans votre tableau de bord.

Developer Dashboard

Créer une application Vonage

L'étape suivante consiste à créer une nouvelle Applications Vonage. Celle-ci générera des identifiants et définira des paramètres spécifiques pour notre application de rappel RCS, tels que les URLs des webhooks. Suivez ces étapes pour créer et configurer votre application :

1. Cliquez sur "Générer une nouvelle application".

2. Donnez-lui un nom.

3. Cliquez sur "Générer les clés privée et publique" (la clé privée sera téléchargée sur votre ordinateur ; conservez-la pour plus tard).

4. Activer la fonction "Messages".

   • L'URL des hooks dépendra de ce que vous obtiendrez de ngrok. Mais le chemin devrait être /inbound et /status, respectivement.

A screenshot of the “Create Application” form in the developer dashboard

Nous devons maintenant relier notre agent RCS à l'application Vonage.

L'amorce du projet

Créer un nouveau répertoire pour le projet et l'initialiser avec npm.

npm init -y

Ensuite, nous installerons les paquets dont nous avons besoin.

npm install @vonage/jwt @vonage/auth @vonage/messages @vonage/server-sdk @vonage/jwt cron dotenv express jsonwebtoken uuid

(Note : Certains des paquets vonage sont inclus avec @vonage/server-sdk, mais c'est toujours une bonne idée d'être implicite avec les paquets requis)

Voici une explication rapide de ce que chaque paquet offre :

• @vonage/server-sdk, @vonage/messages, @vonage/auth, et @vonage/jwt seront utilisés pour envoyer et recevoir des messages

• cron est un paquetage utilisé pour exécuter du code selon un calendrier.

• dotenv charge dynamiquement les fichiers .env de manière dynamique,

  qui sera utilisée pour configurer notre application

• express est utilisé comme serveur web pour traiter nos messages

• jsonwebtoken sera utilisé pour valider les jetons JWT

• uuid crée des identifiants uniques

Copiez la clé.privée dans le dossier de notre application, puis créez un fichier .env avec ce qui suit :

VONAGE_APPLICATION_ID=<your application id>
VONAGE_PRIVATE_KEY_FILE=<full path to the private key>
VONAGE_BRAND_NAME=<id of your RBM account>
REMINDER_NUMBER=<your phone number or number you want to send the reminder to>

Créez un fichier appelé server.js et démarrez en utilisant ce boilerplate express.

const Express = require('express');
require('dotenv').config();

const app = new Express();
const port = process.env.PORT || 3000;

// Catches async functions for express
const catchAsync = (fn) => (req, res, next) => {
  fn(req, res, next).catch(next);
};

app.use(Express.json());

// Hello World
app.all('/', catchAsync(async (req, res) => {
  console.log('Hello World', req.body);
  res.status(200).json({hello: 'World'});
}));

// Setup a 404 handler
app.all('*', (req, res) => {
  res.status(404).json({
	status: 404,
	title: 'Not Found',
  });
});

// Setup an error handler
app.use((err, req, res, next) => {
  res.status(500).json({
	status: 500,
	title: 'Internal Server Error',
	detail: err.message,
  });
});

Ensuite, mettez à jour package.json pour avoir un script de démarrage :

{
  // ...
  "scripts": {
    "start": "node server.js"
  }
}

Vous pouvez maintenant lancer npm run start et ngrok, puis naviguer vers l'URL de ngrok. Vous devriez voir "Hello World" au format JSON. Cela signifie que nous avons réussi à démarrer Express.

Comment envoyer des messages de rappel

Nous allons maintenant envoyer le rappel. Nous allons programmer une fonction pour qu'elle s'exécute à intervalles réguliers à l'aide de la commande cron pour programmer une fonction qui s'exécutera à intervalles réguliers. Les expressions cron sortent du cadre de ce billet, mais si vous voulez jouer avec la fréquence d'envoi du rappel, je vous suggère le fichier Crontab.guru pour vous aider à construire l'expression.

Comment configurer le SDK de Vonage Node

Commençons par configurer le SDK pour qu'il envoie des messages. Vous devrez entrer l'identifiant de l'application et la clé privée. En général, vous pouvez indiquer le chemin d'accès à la clé privée, et le SDK la lira. Cependant, nous aurons besoin de la clé privée dans l'étape suivante, nous lirons donc le fichier et le stockerons dans une variable à la place.

// Add this to the top of the file
const { Auth } = require('@vonage/auth');
const { Vonage } = require('@vonage/server-sdk');
const { readFileSync } = require('fs');

// This can go anywhere else
const key = readFileSync(process.env.VONAGE_PRIVATE_KEY_FILE).toString();

const auth = new Auth({
  applicationId: process.env.VONAGE_APPLICATION_ID,
  privateKey: key,
});

const vonage = new Vonage(auth);

Comment envoyer un rappel de carte riche

Nous allons générer notre propre jeton JWT, qui peut ensuite être utilisé pour le webhook entrant afin de s'assurer que nous recevons des messages de Vonage, mais aussi parce qu'ils ont une expiration intégrée. Nous voulons donner à l'utilisateur un délai déterminé pour répondre. En utilisant un JWT, nous répondons à ces deux exigences.

Tout d'abord, nous allons nous inscrire à la tâche cron. Nous l'exécuterons toutes les cinq minutes pour vérifier si le destinataire a reconnu avoir bu un verre d'eau.

// Add to top of the file
const { CronJob } = require('cron');

// Setup the cronjob
const job = new CronJob(
  // Run every 5 minutes
  '5 * * * * *',
  () => {
    sendReminder(reminderNumber);
  },
  null, // Data to pass into the cron function
  true, // Automatically start
  process.env.TZ || 'America/New_York', // The timezone
);

Ensuite, nous écrirons quelques fonctions pour vérifier si nous devons envoyer un message. Nous stockons le rappel dans un tableau avec le jeton généré par l'envoi du message.

// Storage for sent reminders
const reminders = [];

// Check to see if we have sent a reminder 
const checkForReminders = (number) => {
  const search = reminders.find((reminder) => reminder.number === number);
  if (!search) {
	console.log('No reminder found');
	return false;
  }

  const { token } = search;
  console.log('Checking token', token);
  return validateToken(token);
};

// Send the reminder
const sendReminder = async (number) => {
  console.log('Checking for reminders');

  if (checkForReminders(number)) {
	console.log('Reminder already sent');
	return;
  }

  const token = await sendMessage(number, (job.nextDate() / 1000) + 10000);
  reminders.push([{number, token}]);
};

Passons maintenant à l'envoi du message. La messagerie RCS propose de nombreux types de messages différents, notamment Cartes riches. Ces cartes contiennent tout le contenu dont le client a besoin pour rendre le message. Dans le canal RCS de l'API Messages de Vonage, les Rich Cards sont envoyées en utilisant le type de message "personnalisé" avec un bouton pour répondre par "OUI". Nous créons un jeton et envoyons le message.

const sendMessage = async (number, exp) => {
  console.log('Sending message to', number);
  const token = tokenGenerate(
    auth.applicationId,
    auth.privateKey,
    {
      reminderId: uuid(),
      ...(exp ? {exp: exp} : {}),
    },
  );

  const message = new RCSCustom({
    to: number,
    from: process.env.VONAGE_BRAND_NAME,
    custom: {
  	contentMessage: {
    	  richCard: {
           standaloneCard: {
           cardOrientation: 'VERTICAL',
           cardContent: {
              title: 'Drink Water Reminder',
              description: 'Did you drink water today?',
              media: {
                height: 'SHORT',
                contentInfo: {
// Add a 
                  fileUrl: 'https://as1.ftcdn.net/jpg/02/22/48/50/220_F_222485075_uAeqmITGagEGdy9D4nWVou0a6dj6EuUz.jpg',
                },
              },
              suggestions: [
                {
                  reply: {
                    text: 'Yes',
                    postbackData: token,
                  },
                },
              ],
            },
          },
    	  },
       },
    },
  });

  console.log('Sending reminder', message);
  try {
	const res = await vonage.messages.send(message);
	console.log('Message sent', res);
	return token;
  } catch (err) {
	console.error('Error sending message');
	err.response.text().then((text) => {
  	console.log(text);
	});
  }
};

Maintenant, lorsque nous lançons npm run start après environ cinq minutes, notre téléphone reçoit un message nous demandant si nous avons bu de l'eau.

Accusé de réception du message

Alors, comment empêcher le message d'être envoyé à nouveau ? C'est là qu'intervient le Webhook. Lorsque l'utilisateur appuie sur "Oui", le client répond à l'agent RCS, qui est ensuite transmis à Vonage. Nous appelons alors un webhook avec les données attachées pour que vous puissiez les traiter. Le message ressemblera à ceci :

{
   "channel": "rcs",
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "Vonage",
   "from": "<Number>",
   "timestamp": "2020-01-01T14:00:00.000Z",
   "context_status": "none",
   "message_type": "reply",
   "reply": {
  	"payload": "<The JWT Token>",
  	"text": "Yes"
   }
}

Notez que de et à ont été intervertis depuis que ce message a été envoyé par le téléphone. En utilisant cette charge utile, nous pouvons trouver notre rappel et le supprimer. (Nous validons également le jeton signé par nous, qui ne peut pas être facilement falsifié).

app.all('/inbound', catchAsync(async (req, res) => {
  console.log('Inbound', req.body);

  const {channel, message_type, reply, from} = req.body;
  if (channel !== 'rcs') {
	console.log('Not RCS');
	res.status(200).json({ok: true});
	return;
  }

  if (message_type !== 'reply') {
	console.log('Not reply');
	res.status(200).json({ok: true});
	return;
  }

  const { id } = reply|| {};

  console.log('Id', id);

  if (!id) {
	console.log('No id');
	res.status(200).json({ok: true});
	return;
  }

  if (!validateToken(id)) {
	console.log('Invalid id');
	res.status(200).json({ok: true});
	return;
  }

  const index = reminders.findIndex((reminder) => reminder.number === from);
  reminders.splice(index, 1);
  console.log('Reminder removed', reminders);

  res.status(200).json({ok: true});
}));

Et voilà ! Envoyer et recevoir des messages RCS est un jeu d'enfant avec l'API de messages. Vous pouvez désormais créer des applications de messagerie riches avec quelques lignes de code. Il est préférable que ces messages soient conversationnels plutôt que transactionnels. De cette façon, vous pouvez améliorer l'expérience de vos utilisateurs en les guidant plutôt qu'en les informant.

Prochaines étapes

RCS est prêt à améliorer les expériences de messagerie avec des fonctionnalités avancées et des possibilités d'intégration. Avec l'API Messages de Vonage, vous pouvez facilement incorporer RCS dans vos applications, apportant une messagerie en temps réel et des éléments interactifs riches à vos utilisateurs. À partir du début de l'automne 2024, Vonage facilitera l'activation de RCS par le biais de sa plateforme. Cela ouvre des opportunités passionnantes pour créer des solutions de messagerie attrayantes et riches en fonctionnalités.

Pour commencer, consultez la Documentation sur les messages personnalisés RCS pour plus d'informations sur l'intégration d'autres types de messages RCS avec Vonage. Pour une interactivité RCS plus avancée, vous pouvez également explorer :

• Comment envoyer et recevoir des réponses suggérées RCS avec Node.js pour permettre aux utilisateurs d'interagir rapidement avec les boutons de réponse suggérés.

• Comment envoyer envoyer des carrousels de cartes riches RCS avec Node.js pour afficher plusieurs rappels, promotions ou options dans un format permettant de les faire défiler.

Vous pouvez également consulter ce dépôt GitHub pour voir une version complète de ce code.

Rejoignez la conversation sur notre Communauté Vonage Slack ou envoyez-nous un message sur X, anciennement connu sous le nom de Twitter.