Envoyer et ouvrir des fichiers RCS en utilisant les espaces de code de GitHub

Introduction

Ce tutoriel vous montre comment envoyer et ouvrir un fichier via RCS avec l'API Vonage Messages API. Contrairement aux SMS ou MMS, RCS prend en charge des fichiers de meilleure qualité sans limites de taille strictes, ce qui en fait une option appropriée pour les documents tels que les tickets, les factures ou les PDF. Dans cet article, nous allons envoyer un fichier PDF via RCS en utilisant GitHub Codespaces.

open RCS message containing PDF

Conditions préalables

• A Compte GitHub

• A agent RCS Business Messaging (RBM) enregistré

• Un téléphone avec des capacité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.

Espaces de code GitHub

Vue d'ensemble

J'ai récemment exploré les Codespaces de GitHub. Il s'agit d'un environnement de développement hébergé dans un conteneur Docker, fonctionnant sur une machine virtuelle. Je l'utilise principalement en accédant à un dépôt GitHub et en ajoutant /codespaces à l'URL, afin de pouvoir y accéder dans Visual Studio Code via mon navigateur préféré. Vous pouvez également créer une instance d'espace de code à partir d'un modèle, d'une branche ou d'un commit dans un dépôt GitHub.

Ouvrir le projet dans Codespaces

Vous pouvez commencer par en accédant au référentiel que j'ai créé pour ce billet de blog et en ajoutant /codespaces. L'URL ressemblerait à ceci : https://github.com/Vonage-Community/blog-messages-nodejs-rcs-file/codespaces

Cliquez sur "Create codespace on main" en haut à droite de la page. GitHub commencera à mettre en place un nouvel environnement pour vous.

Click “Create codespace on main” to start your environmentUne fois chargé, vous serez dans un éditeur VS Code basé sur un navigateur où vous pourrez exécuter et éditer le projet immédiatement. Utilisez-le pour exécuter votre instance. Cependant, n'hésitez pas à exécuter le code que je vais montrer dans ce billet de blog sur votre IDE ou environnement préféré.

Pour plus de détails, consultez le guide officiel de GitHub : Démarrage rapide pour les espaces de code GitHub.

Apprendre quelques commandes sur Codespaces

Si vous avez de l'expérience avec Visual Studio Code, vous pouvez trouver votre chemin en utilisant Codespaces. Vous pouvez toujours naviguer et trouver ce qui se trouve en dessous dans les menus, mais voici quelques commandes pour vous aider à naviguer plus facilement :

• Ouvrir des fichiers : Control + ` sur Mac ou Windows/Linux.

• Ouvrez le terminal : Command + Shift + P sur Mac ou Ctrl + Shift + P sur Windows/Linux.

Installation à l'aide de npm

Exécutez npm install dans le terminal Codespaces pour installer les paquets suivants qui se trouvent dans le fichier package.json.

• dotenv: charge vos variables d'environnement à partir d'un fichier .env, préservant ainsi la confidentialité des informations sensibles telles que les clés d'API.

• @vonage/server-sdk: le SDK Node.js de base de Vonage. Il vous aide à authentifier et à initialiser le client Vonage.

• @vonage/messages: une bibliothèque dédiée à l'envoi de messages par l'intermédiaire de l'API Messages de Vonage. Nous l'utilisons pour envoyer des messages RCS (texte, images, fichiers, etc.).

npm install dotenv @vonage/server-sdk @vonage/messages

Ajouter les variables d'environnement

Certaines variables contiennent des informations sensibles, je ne voudrais donc pas ajouter publiquement les clés API, les secrets ou même le numéro de téléphone que j'utiliserai pour les tests. Nous les ajouterons donc à un fichier .env. Voici plus d'informations sur l'utilisation des variables d'environnement dans Node.

Créer un fichier .env

Copiez le fichier .env.example dans un nouveau fichier .env que vous devez créer maintenant. Depuis le terminal codespaces :

touch .env

Dans l'extrait de code ci-dessous, j'énumère toutes les variables d'environnement dont nous aurons besoin. Je les expliquerai une par une et où les trouver.

VONAGE_APPLICATION_ID=000000-0000-0000-0000-0000000000

VONAGE_PRIVATE_KEY=./private.key

RCS_SENDER_ID=NameOfYourAgent

MESSAGES_FILE_URL=https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf

• Connectez-vous à votre compte Vonage et procédez à la création d'une nouvelle application.

  • Pour créer une application, allez à la page Créer une application sur le tableau de bord de Vonage, et définissez un nom pour votre application.

    

  • Si vous avez l'intention d'utiliser une API qui utilise des Webhooks, vous aurez besoin d'une clé privée. Cliquez sur "Générer une clé publique et privée", votre téléchargement devrait démarrer automatiquement. Conservez-la en lieu sûr ; cette clé ne peut pas être retéléchargée si elle est perdue. Elle suivra la convention de nommage suivante private_<votre identifiant d'application>.key. Cette clé peut maintenant être utilisée pour authentifier les appels à l'API. Remarque : votre clé ne fonctionnera pas tant que votre application n'aura pas été sauvegardée.

  • Choisissez les fonctionnalités dont vous avez besoin (par exemple, Voice, Messages, RTC, etc.) et fournissez les webhooks requis (par exemple, URL d'événement, URL de réponse ou URL de message entrant). Ces éléments seront décrits dans le tutoriel.

  • Pour sauvegarder et déployer, cliquez sur "Générer une nouvelle application" pour finaliser la configuration. Votre application est maintenant prête à être utilisée avec les API de Vonage.

• Dans la vue des applications, chaque application contient un ID d'application. Copiez cette chaîne et collez-la dans votre variable VONAGE_APPLICATION_ID variable.

• Cliquez sur pour générer une clé privée. Un fichier sera téléchargé dans votre dossier de téléchargements. Ajoutez-le à la racine de votre fichier sur GitHub Codespaces. Nommez-le private.key.

• Les messages RCS sont envoyés à partir d'un agent, qui se trouve sous l'onglet "lier des comptes externes" une fois que vous l'avez créé. Comprendre la messagerie RCS.

• Le message MESSAGES_FILE_URL contient l'URL d'un fichier à envoyer par message RCS. J'ai utilisé ce chemin d'accès au fichier PDF public pour mes tests.

Comprendre la logique

Ouvrez le fichier index.js qui se trouve dans le menu de gauche de GitHub Codespaces.

Importer des dépendances

En haut de votre fichier, vous verrez l'importation des deux paquets Vonage : @vonage/server-sdk et @vonage/messagesqui ont été expliqués précédemment dans la section "Installation à l'aide de Npm".

import "dotenv/config";

const { Vonage } = require('@vonage/server-sdk');

const { Channels } = require('@vonage/messages');

Initialiser le client Vonage

Initialiser le client Vonage en lui transmettant l'identifiant de l'application et la clé privée.

const vonage = new Vonage({

  applicationId: process.env.VONAGE_APPLICATION_ID,

  privateKey: process.env.VONAGE_PRIVATE_KEY,

});

Envoyer le message RCS

Pour envoyer un message RCS avec l'API Messages, nous utiliserons la méthode vonage.messages.send de la bibliothèque bibliothèque Node.js de Vonageen spécifiant le ‘RCS’ canal. Cette méthode accepte des objets comme paramètres, avec des informations sur le destinataire, l'expéditeur et le contenu.

J'ai défini le MessageType comme un file. Vous pouvez vérifier tous les Types de médias pris en charge.

vonage.messages.send({

  messageType: 'file',

  channel: Channels.RCS,

  file: {

    url: process.env.MESSAGES_FILE_URL,

  },

  to: process.env.PHONE_NUMBER,

  from: process.env.RCS_SENDER_ID,

})

  .then(({ messageUUID }) => console.log(messageUUID))

  .catch((error) => {

  console.error("Error sending RCS message:", error);

});

Exécutez votre code

Depuis le terminal de GitHub Codespaces, exécutez le fichier index.js. Lorsque nous exécutons ce fichier, un message RCS sera envoyé au numéro de téléphone spécifié. Vous verrez un message appelé "attachment" sur l'appareil spécifié, et lorsque vous cliquez, vous pouvez voir le fichier que vous avez spécifié sur le fichier MESSAGES_FILE_URL.

node index.js

Bonnes pratiques et extension possible

Si vous souhaitez aller plus loin, vous pouvez envisager de d'installer et d'exécuter ngrok pour exposer votre serveur local et permettre à Vonage d'envoyer des requêtes webhook directement à votre environnement de développement. Il est ainsi plus facile de tester les interactions en temps réel, telles que les messages entrants et les accusés de réception. Vous pouvez également mettre en œuvre la vérification JWT pour valider les webhooks entrants et vous assurer qu'ils proviennent de sources fiables.

Conclusion

Maintenant que vous avez appris à envoyer des fichiers via RCS, vous pouvez envisager d'étendre votre solution en mettant en œuvre les éléments suivants des réponses suggérées ou carrousels de cartes riches. Actuellement, il suffit d'envoyer une pièce jointe avec le nom du fichier. Vous pouvez utiliser des solutions de cartes enrichies pour rendre le message et les fichiers partagés encore plus descriptifs et plus faciles à consulter.