Comment envoyer et recevoir des SMS avec Node.js et Google Cloud Run

En 2019, j'ai organisé une série d'événements comprenant un "Cloud Run Club" à Finsbury Square Garden et Victoria à Londres, suivi d'un "Google Cloud Run". Google Cloud Run de Google. Aujourd'hui, il n'y aura pas de course à pied, mais vous apprendrez à construire et à déployer une application SMS à l'aide de Node.js, Expresset l'API Vonage Messages API sur Google Cloud Run.

Malheureusement, en cours d'exécution, je ne peux pas passer à l'échelle zéro, mais Google Cloud Run vous permet de déployer des applications conteneurisées qui passent automatiquement à l'échelle. Vous ne payez que pour ce que vous utilisez. C'est idéal pour créer des webhooks et des API, car vous n'avez pas besoin de gérer des serveurs. Votre application est mise à l'échelle lorsqu'il n'y a pas de trafic.

Schéma et conditions préalables

• Node.js v18 ou plus récent installé

• Google Cloud CLI installé et configuré

• A Compte Google Cloud avec la facturation activée

• Une compréhension de base de JavaScript et de Node.js.

• Le code code complet sur GitHub

Structure du projet

Vous pouvez trouver le code complet sur GitHub. L'arborescence du projet se présente comme suit.

blog-messages_api-cloud_run-sms/

├── index.js, contains our JavaScript

├── package.json, for our dependencies

├── .env.example, you can copy and create a .env from it to add your environment variables

├── .gitignore, for any files or folders not to be committed

└── private.key

Créer une application Vonage

Je vous montrerai comment créer une nouvelle application Vonage à partir du tableau de bord dans les étapes ci-dessous. Vous pouvez également utiliser l'interface de commande pour créer une application.

Capacité de l'API Messages et configuration des Webhooks

Activez l'option Messages dans la rubrique Capacités. Nous utiliserons l'API Messages API v1.

Définissez des URL fictives pour l'instant. Nous les mettrons à jour après le déploiement :

• URL entrant : https://example.com/webhooks/inbound

• URL du statut : https://example.com/webhooks/status

Sauvegardez votre demande et notez votre numéro d'identification de la demande.

Messages Capability

Associer un numéro de téléphone virtuel à l'Applications

Une fois que nous avons choisi notre numéro, il est temps de le lier à notre application Vonage. Allez à Vos Numbers et cliquez sur l'icône en forme de crayon à côté de votre numéro. Sélectionnez votre application sous "Messages". À [00:01:19vous pouvez voir comment acheter et lier un numéro virtuel.

Définir l'API Messages par défaut

Accéder à Paramètres et descendez jusqu'à "Paramètres SMS". Assurez-vous que "Messages API" est sélectionné comme API par défaut pour les SMS, puis cliquez sur "Enregistrer les modifications".

SMS SettingsVonage dispose de deux API pour envoyer des SMS : l'API SMS et l'API Messages. Ce tutoriel utilise l'API Messages API. Si vous ne modifiez pas ce paramètre, vos webhooks recevront un format de charge utile différent et le code ne fonctionnera pas correctement.

Initialiser le projet

Créez un répertoire pour votre application et entrez-y. Exécutez npm init -y pour initialiser votre projet.

mkdir blog-messages_api-cloud_run-sms

cd blog-messages_api-cloud_run-sms

npm init -y

Installer les dépendances

Nous allons utiliser les dépendances suivantes dans notre projet : express, @vonage/server-sdk, @vonage/jwt. Vous pouvez les installer en exécutant la commande suivante à partir de votre terminal ou de l'invite de commande.

npm install express @vonage/server-sdk @vonage/jwt

Configuration du serveur

Créer le fichier index.js et initialisez votre serveur avec les paquets requis. Configurez un client Vonage en utilisant les variables d'environnement qui sont lues à partir du fichier .env à créer à partir du fichier .env.example.

const express = require('express');

const path = require('path');

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

const { verifySignature } = require('@vonage/jwt');

const app = express();

app.use(express.json());

app.use(express.urlencoded({ extended: true }));

// Initialize Vonage client

const vonage = new Vonage({

  applicationId: process.env.VONAGE_APPLICATION_ID,

  privateKey: path.join(__dirname, 'private.key')

});

const FROM_NUMBER = process.env.VONAGE_NUMBER;

Nous utilisons path.join(__dirname, 'private.key') pour obtenir le chemin absolu vers le fichier de clé, de sorte qu'il fonctionne à la fois localement et lorsqu'il est déployé sur Cloud Run.

Ajouter la page d'accueil

Ajoutez le contenu et le style du formulaire que l'utilisateur doit remplir pour envoyer des SMS. L'utilisateur doit saisir son numéro de téléphone et un message, puis cliquer sur le bouton de soumission pour envoyer le SMS.

app.get('/', (req, res) => {

  res.send(`

    <!DOCTYPE html>

    <html>

    <head>

      <title>Vonage SMS on Cloud Run</title>

      <style>

        body { font-family: Arial, sans-serif; max-width: 600px; margin: 50px auto; padding: 20px; }

        h1 { color: #7b00ff; }

        form { display: flex; flex-direction: column; gap: 15px; }

        input, textarea { padding: 10px; font-size: 16px; }

        button { padding: 12px; background: #7b00ff; color: white; border: none; cursor: pointer; }

      </style>

    </head>

    <body>

      <h1> Send SMS with Vonage </h1>

      <form action="/send" method="POST">

        <label>Phone Number (e.g. 444155551234)</label>

        <input type="tel" name="to" required>

        <label>Message</label>

        <textarea name="text" rows="4" required></textarea>

        <button type="submit">Send SMS</button>

      </form>

    </body>

    </html>

  `);

});

Ajouter le point final d'envoi

Ajoutez le point de terminaison qui envoie le SMS à l'aide de l'API Messages de Vonage. Le point de terminaison vonage.messages.send() accepte un objet avec canal ayant pour valeur 'sms' et le type_message est fixé à 'text'. La réponse comprend un message_uuid que vous pouvez utiliser pour suivre le message.

app.post('/send', async (req, res) => {

  const { to, text } = req.body;

 try {

    const response = await vonage.messages.send({

      message_type: 'text',

      to: to,

      from: FROM_NUMBER,

      channel: 'sms',

      text: text

    });

    console.log('SMS sent:', response.message_uuid);

    res.sendSMS sent! Message ID: ${response.message_uuid});

  } catch (error) {

    console.error('Error sending SMS:', error);

    res.status(500).sendFailed to send SMS: ${error.message});

  }

});

Ajouter des points de terminaison Webhook

Lorsque quelqu'un envoie un SMS à votre numéro virtuel Vonage que vous avez préalablement acheté, le message SMS arrive chez Vonage, Vonage envoie une requête POST à votre Google Cloud Run. /webhooks/inbound et enfin, votre application traite le message et répond par un 200 OKsi tout fonctionne bien. Ajoutez les points de terminaison des webhooks qui utilisent cette vérification, comme indiqué ci-dessous. Le webhook status (/webhooks/status) reçoit les accusés de réception. Vous saurez ainsi si votre message a été délivré ou s'il a échoué.

app.post('/webhooks/inbound', (req, res) => {

  verifyJWT(req);

  console.log('Inbound SMS received:');

  console.log('From:', req.body.from);

  console.log('Text:', req.body.text);

  

  res.status(200).send('OK');

});

app.post('/webhooks/status', (req, res) => {

  verifyJWT(req);

  console.log('Status update:', req.body.status);

  res.status(200).send('OK');

});

const verifyJWT = (req) => {
  // Verify if the incoming request came from Vonage
  const jwtToken = req.headers.authorization.split(" ")[1];
  if(!verifySignature(jwtToken, process.env.VONAGE_API_SIGNATURE_SECRET)) {
    console.error("Signature does not match");
    throw new Error("Not a Vonage API request");
  }

  console.log("JWT verified");
}

npm install @vonage/jwt

Démarrer le serveur

Cloud Run définit le PORT automatiquement, nous l'utilisons donc si elle est disponible. Ajoutez le code pour démarrer le serveur :

const PORT = process.env.PORT || 8080;

app.listen(PORT, () => {

  console.logServer running on port ${PORT});

});

Essais locaux limités

Vous pouvez exécuter l'application localement pour vérifier qu'elle démarre sans erreur, mais vous ne pourrez pas encore envoyer de SMS. L'API Messages de Vonage doit atteindre les URL de vos webhooks pour vérifier les demandes et envoyer des mises à jour d'état. C'est pourquoi nous déployons d'abord sur Cloud Run.

Si vous voulez vérifier que l'application fonctionne, exécutez le fichier JavaScript.

node index.js

Ouvrez http://localhost:3000 pour voir le formulaire. L'app devrait démarrer sans erreur, mais l'envoi de messages échouera tant que nous n'aurons pas déployé et configuré les webhooks.

Déployer sur Google Cloud Run

Maintenant que l'application fonctionne localement, déployons-la sur Google Cloud Run, afin qu'elle soit accessible sur Internet et qu'elle puisse recevoir des webhooks de Vonage.

Configuration de Google Cloud

Si vous n'avez pas encore de compte Google Cloud, créez-en un comme indiqué dans les conditions préalables.

Installer l'interface de programmation de Google Cloud

Téléchargez et installez le logiciel Google Cloud CLI pour votre système d'exploitation. Dans la prochaine sous-section, je montrerai comment procéder sur macOS, mais vous pouvez vous référer au lien ci-dessus pour les autres systèmes d'exploitation. J'ai voulu montrer les étapes que j'ai effectuées moi-même parce que j'ai rencontré quelques erreurs, et partager quelques astuces qui pourraient vous aider.

Sur macOS

# Download the archive (Apple Silicon)

curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-arm.tar.gz

# Extract it

tar -xzf google-cloud-cli-darwin-arm.tar.gz

# Run the install script

./google-cloud-sdk/install.sh

En cas d'erreur de version de Python : le CLI gcloud nécessite Python 3.10 ou plus. Si vous voyez une TypeError à propos de type(s) d'opérande(s) non supporté(s) pour |votre Python est trop ancien. Installez une version plus récente avec Homebrew comme indiqué ci-dessous (ou de toute autre manière que vous préférez) et dirigez gcloud vers elle :

brew install python@3.12

export CLOUDSDK_PYTHON=$(brew --prefix python@3.12)/bin/python3.12

./google-cloud-sdk/install.sh

Le script d'installation vous demandera si vous souhaitez ajouter gcloud à votre PATH. Choisissez oui. Redémarrez ensuite votre invite de commande/terminal ou exécutez :

source ~/.zshrc

Initialisez maintenant gcloud :

gcloud init

Cela ouvrira une fenêtre de navigateur pour vous connecter à votre compte Google et sélectionner ou créer un nouveau projet Google Cloud.

Créer un projet Google Cloud

Si vous n'avez pas encore de projet, créez-en un. Les identifiants de projet doivent être globalement uniques, vous pouvez donc ajouter des caractères aléatoires.

gcloud projects create vonage-sms-yourname --name="Vonage Messages API Demo"

gcloud config set project vonage-sms-yourname

Vous pouvez également créer un projet à partir de la Google Cloud Console.

Activation d'un compte de facturation Google Cloud

Cloud Run nécessite l'activation de la facturation. Accédez à la page Page de facturation et associez un compte de facturation à votre projet.

Activer les API Google Cloud requises

Activer les API Cloud Build et Cloud Run :

gcloud services enable cloudbuild.googleapis.com run.googleapis.com

Déployer sur Google Cloud Run

Pour les applications de production, envisagez d'utiliser Google Secret Manager pour stocker des valeurs sensibles. Pour ce tutoriel, nous transmettrons les variables d'environnement directement.

Assurez-vous que votre "private.key" se trouve dans le répertoire du projet. Il est regroupé avec votre code source lors du déploiement.

Déployer :

gcloud run deploy vonage-sms \

  --source . \

  --region us-central1 \

  --allow-unauthenticated \

  --set-env-vars "VONAGE_APPLICATION_ID=your_app_id" \

  --set-env-vars "VONAGE_NUMBER=444155551234" \

  --set-env-vars "VONAGE_API_SIGNATURE_SECRET=your_signature_secret"

Premier déploiement : vous verrez une invite concernant la création d'un dépôt Artifact Registry nommé cloud-run-source-deploy pour stocker vos images de conteneurs. Tapez y pour continuer.

Le premier déploiement prend quelques minutes. Une fois le déploiement terminé, vous verrez une URL du type https://vonage-sms-abc123-uc.a.run.app.

Mise à jour des Webhooks de Vonage

Maintenant que vous avez votre URL Cloud Run, retournez à votre Applications Vonage et mettez à jour les URL des webhooks :

• URL entrant : https://your-cloud-run-url/webhooks/inbound

• URL du statut : https://your-cloud-run-url/webhooks/status

N'oubliez pas de cliquer sur Enregistrer les modifications en bas à droite de la page.

Testez-le

Il est temps de tester tout ce que nous avons mis en place et de faire fonctionner les choses !

Envoyer un SMS

Ouvrez votre URL Cloud Run dans un navigateur (l'URL que vous avez obtenu après le déploiement, comme https://vonage-sms-abc123-uc.a.run.app). Vous devriez voir le formulaire SMS que nous avons construit. Saisissez votre numéro de téléphone et un message, puis appuyez sur envoyer. Si tout est configuré correctement, vous recevrez le SMS sur votre téléphone en quelques secondes. Vous pouvez vérifier les caractéristiques et restrictions propres à chaque pays.

Recevoir un SMS

Testez maintenant dans l'autre sens. Envoyez un SMS depuis votre téléphone vers le numéro Vonage que vous avez acheté et lié à l'application que vous avez créée. Cela déclenche le webhook entrant que nous avons mis en place. Vous pouvez vérifier les journaux à deux endroits :

A partir de la ligne de commande

gcloud run logs read vonage-sms --region us-central1

À partir du tableau de bord de Vonage

Allez à votre Application Vonagecliquez sur votre application et vérifiez la section des journaux pour voir l'activité des messages et toute erreur de crochet Web. Vous devriez voir votre message entrant enregistré avec le numéro et le texte de l'expéditeur.

Conclusion

Vous avez créé et déployé une application SMS sur Google Cloud Run à l'aide de l'API Messages de Vonage. L'appli peut envoyer des messages via un formulaire web et recevoir des messages entrants via des webhooks.

Pour en savoir plus

• Documentation de l'API Messages de Vonage

• Documentation sur Google Cloud Run

• Comment envoyer et recevoir des SMS avec Node.js et Express

• Envoyer des SMS avec les fonctions cloud pour Firebase Gen 2

• Comment utiliser les variables d'environnement dans Node.js