Comment déclencher une alerte d'utilisation avec la CLI Twilio

Temps de lecture: 6 minutes

May 10, 2021

Rédigé par

Ashley Boucher

Twilion

Révisé par

Miguel Grinberg

Twilion

Comment déclencher une alerte d'utilisation avec la CLI Twilio

La CLI Twilio dispose de nombreuses fonctionnalités, notamment vous pouvez suivre la consommation de l'API Twilio que vous utilisez à des fins de facturation. En plus de vérifier vos montants d'utilisation, vous pouvez également configurer une alerte qui vous indiquera quand vous avez dépensé une certaine somme d'argent. Pour apprendre à le faire, suivez-moi !

Conditions préalables

Pour commencer ce tutoriel, vous aurez besoin des éléments suivants :

Node.js installé sur votre machine
Un compte Twilio gratuit (inscrivez-vous avec ce lien et bénéficiez d'un crédit gratuit de 10 $ lorsque vous mettez à niveau votre compte)
Un numéro de téléphone Twilio
La CLI Twilio
ngrok

Se connecter à la CLI Twilio

Ouvrez un terminal ou une invite de commande et connectez-vous à la CLI Twilio en exécutant la commande suivante :

twilio login

Vous serez alors invité à saisir votre SID de compte Twilio et votre token d'authentification, tous deux disponibles sur la console Twilio.

Capture d'écran montrant le SID de compte et le token d'authentification sur la console Twilio

Après avoir copié et collé vos informations d'identification dans les instructions du terminal (les valeurs collées seront masquées), appuyez sur la touche Retour pour les soumettre.

Maintenant que vous êtes connecté, vous êtes prêt à utiliser la CLI Twilio !

Obtenir des enregistrements d'utilisation à l'aide de la CLI Twilio

Dans votre terminal, si vous exécutez la commande twilio, vous verrez une liste de toutes les commandes de haut niveau disponibles via la CLI.

La commande api vous permet de trouver la plupart des fonctionnalités Twilio que vous avez utilisées par programmation.

N'hésitez pas à explorer la CLI tout au long de ce tutoriel.

Vous pouvez trouver vos données d'utilisation en exécutant la commande suivante :

twilio api:core:usage

Après avoir exécuté cette commande, vous verrez le texte suivant :

Retrieve a list of usage-records belonging to the account used to make the request

USAGE
  $ twilio api:core:usage:COMMAND

COMMANDS
  api:core:usage:records   Twilio account usage records
  api:core:usage:triggers  Webhooks that notify you of usage thresholds

Ce texte vous indique qu'il existe deux sous-commandes disponibles sur la commande usage : records et triggers. Vous allez examiner les deux dans ce tutoriel, mais vous commencerez par records.

Pour voir ce que fait la sous-commande records, exécutez-la dans votre terminal ou dans l'invite de commande :

twilio api:core:usage:records

Cette commande renvoie le texte suivant :

Twilio account usage records

USAGE
  $ twilio api:core:usage:records:COMMAND

COMMANDS
  api:core:usage:records:all-time    Usage records for all time
  api:core:usage:records:daily       Usage records summarized by day
  api:core:usage:records:last-month  Usage records for last month
  api:core:usage:records:list        Retrieve a list of usage-records belonging to the account used to make the request
  api:core:usage:records:monthly     Usage records summarized by month
  api:core:usage:records:this-month  Usage records for this month
  api:core:usage:records:today       Usage records for today
  api:core:usage:records:yearly      Usage records summarized by year
  api:core:usage:records:yesterday   Usage records for yesterday

Cette réponse vous indique toutes les différentes périodes pendant lesquelles vous pouvez consulter vos données d'utilisation :

Tout le temps
Tous les jours
Le mois dernier
Tous les mois
Ce mois-ci
Aujourd'hui
Tous les ans
Hier

Vous pouvez essayer d'exécuter chacune de ces sous-commandes pour voir ce qu'elles renvoient. Ces sous-commandes comportent également des indicateurs que vous pouvez utiliser pour affiner vos résultats.

Par exemple, la sous-commande daily renverra par défaut les données d'utilisation de chaque produit Twilio pour la journée en cours. Si vous souhaitez voir une plage de dates spécifique, vous pouvez passer les dates de début et de fin au format AAAA-MM-JJ :

twilio api:core:usage:records:daily:list --start-date 2021-05-06 --end-date 2021-05-07

Cette commande affiche les données d'utilisation, par produit Twilio, pour le 6 mai 2021.

Vous pouvez également restreindre la réponse de la CLI à une catégorie/un produit Twilio spécifique.

Par exemple, si vous souhaitez uniquement afficher les données d'utilisation du jour, vous pouvez exécuter la commande suivante :

twilio api:core:usage:records:today:list --category sms

L'utilisation de l'indicateur --help après une sous-commande vous permet d'afficher tous les indicateurs disponibles que vous pouvez utiliser, ainsi que d'autres détails utiles.

Maintenant que vous savez comment trouver vos enregistrements d'utilisation, il est temps de configurer une alerte de consommation.

La commande de d’alerte d’utilisation

La commande de base pour configurer une alerte d'utilisation est la suivante :

twilio api:core:usage:triggers:create \
  --callback-url <YOUR CALLBACKURL> \
  --trigger-value <DESIRED TRIGGER VALUE> \
  --usage-category <DESIRED USAGE CATEGORY> \

Il existe d'autres indicateurs que vous pouvez ajouter à cette commande (que vous pouvez trouver en exécutant twilio api:core:usage:triggers:create --help), mais les trois indicateurs indiqués dans la commande ci-dessus sont les indicateurs minimum requis.

Je vais vous expliquer chacun d'entre eux.

URL de rappel

Une alerte d'utilisation est un webhook. Cela signifie qu'une fois que vous avez atteint le seuil d'utilisation, la CLI effectue une requête HTTP. Vous devez fournir la destination souhaitée pour cette requête HTTP afin « d'attraper » l’alerte avant de la traiter.

Par exemple, vous souhaiterez peut-être vous envoyer une notification SMS lorsque votre compte dépense une certaine somme d'argent pour envoyer des SMS aux clients. L'élément callback-url est l'emplacement de l'application où vous recevez cette requête HTTP et créez votre notification SMS personnelle. Il peut s'agir d'une URL créée avec les fonctions Twilio ou d'une URL provenant d'une autre application côté serveur comme une application Express.

Valeur de déclenchement

L'indicateur trigger-value est l'endroit où vous indiquez la valeur de déclenchement. Cet indicateur est souvent utilisé en tandem avec l'indicateur trigger-by, dont la valeur peut être l'une des suivantes :count, usage, price. Si vous n'incluez pas l'indicateur trigger-by, l'indicateur trigger-value sera traité comme une valeur usage.

Usage est la principale façon de mesurer une catégorie de produits Twilio. Par exemple, l'utilisation de Programmable Voice est mesurée en minutes d'appel. L'utilisation de Programmable SMS est mesurée par des messages individuels.

Catégorie d'utilisation

L'indicateur usage-category fait référence au produit Twilio ou à la catégorie d'utilisation pour laquelle vous souhaitez recevoir l'alerte, comme sms ou calls. Pour afficher toutes les catégories d'utilisation disponibles (il en existe un grand nombre), exécutez la commande twilio api:core:usage:triggers:create --help.

Configurer un alerte d'utilisation et une alerte SMS

Construire votre application de serveur Express

Pour ce tutoriel, vous devez utiliser la CLI Twilio pour configurer une alerte d'utilisation qui enverra un SMS à votre numéro de téléphone personnel chaque fois que votre compte effectue un appel vocal. Il s'agit d'un seuil très bas qui a été choisi uniquement pour faciliter le test de votre alerte.

Remarque : la raison pour laquelle vous configurez cette alerte lors d'un appel vocal est que si vous essayez de tester l' alerte après un SMS, vous déclenchez accidentellement une boucle illimitée d'alertes jusqu'à ce que vous fermiez votre serveur.

La première étape consiste à créer un serveur afin que votre application puisse recevoir la requête HTTP lorsque l' alerte se déclenche.

Dans votre terminal, accédez à un emplacement approprié sur votre ordinateur, créez un nouveau répertoire de projet et initialisez un nouveau projet Node.js :

mkdir usage-trigger
cd usage-trigger
npm init -y

Installez Express, dotenv et la bibliothèque Twilio Node Helper :

npm install express dotenv twilio

Vos informations d'identification Twilio seront stockées dans un fichier .env. Créez donc ce fichier dans usage-trigger et ajoutez les éléments suivants, en remplaçant les espaces réservés par les mêmes informations d'identification Twilio que celles utilisées pour vous connecter à la CLI.

TWILIO_ACCOUNT_SID=XXXXXXXXXXXXXXXXXXXXXX
TWILIO_AUTH_TOKEN=XXXXXXXXXXXXXXXXXXXXXX

Enregistrez et fermez ce fichier.

Créez un autre fichier dans le dossier usage-trigger appelé index.js. Ouvrez index.js dans votre éditeur de texte favori et ajoutez le code suivant :

var express = require('express');
var app = express();
require('dotenv').config();

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

app.post('/', function (req, res) {
  //Envoi de la notification SMS
});

app.listen(3000, function () {
  console.log('Trigger app listening on port 3000');
});

Supprimez le commentaire sur la ligne 8, surlignée ci-dessus, et remplacez-le par le code suivant, en prenant soin de remplacer le numéro from par votre numéro de téléphone Twilio, ainsi que le numéro de téléphone to par votre numéro de téléphone personnel, tous deux au format E.164 :

console.log('Alerte d'usage reçue');

const client = require('twilio')(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);
const message = `Vous avez atteint votre seuil d'usage. Votre usage courant est de ${req.body.CurrentValue}`;

client.messages
  .create({body: message, from: '+15017122661', to: '+15558675310'})
  .then(message => console.log(message.sid));

res.end();

Ce code utilise la bibliothèque Twilio Node Helper pour envoyer un SMS à votre numéro personnel avec un message vous informant que vous avez atteint votre seuil d'utilisation. Le message inclut également des informations sur la valeur actuelle de l'utilisation pour votre catégorie d’alerte.

Enregistrez votre fichier et démarrez votre serveur local en exécutant la commande suivante depuis le répertoire usage-trigger de votre terminal :

node index.js

Dans une nouvelle fenêtre de terminal, exécutez la commande suivante pour exposer votre serveur à Internet :

ngrok http 3000

Copiez l'URL de transfert sécurisée : il s'agit de l'URL de rappel que vous utiliserez lors de la configuration de votre alerte.

Créer l' alerte dans la CLI

Avec votre URL de rappel à portée de main, dans une nouvelle fenêtre de terminal, utilisez la CLI pour créer votre alerte, en remplaçant la valeur de l'indicateur callback-url par votre nouvelle URL de ngrok :

twilio api:core:usage:triggers:create \
  --callback-url https://XXXX.ngrok.io \
  --trigger-by count \
  --trigger-value 1 \
  --usage-category calls

Une fois votre alerte créée, il est temps de la tester.

Tester l' alerte

Dans une dernière fenêtre de terminal ou d'invite de commande, exécutez la commande suivante pour créer un appel vocal directement à partir de votre CLI.

Avant d'exécuter la commande, assurez-vous de remplacer les valeurs d'indicateur to et from par votre numéro de téléphone personnel et votre numéro de téléphone Twilio, respectivement :

twilio api:core:calls:create \
--from "+VOTRE_NUMERO_TWILIO" \
--to "+VOTRE_NUMERO_PERSONNEL" \
--twiml "<Response><Say>Ahoy, friend</Say></Response>"

Au bout de quelques minutes, votre téléphone sonne et vous entendez un message indiquant « Ahoy, friend ».

À ce stade, votre alerte doit se déclencher.

Revenez à la fenêtre du terminal qui exécute votre serveur Express. Lorsque la requête HTTP atteint votre serveur, vous voyez un message enregistré indiquant « Usage trigger alert received » (Alerte d’utilisation d'utilisation reçue). Une fois votre notification SMS personnelle envoyée, une ligne de log contenant le SID du message s'affiche. Peu de temps après, vous recevrez un SMS sur votre téléphone.

Normalement, ce processus ne prend que quelques secondes, mais si vous ne le voyez pas immédiatement, veuillez noter que l' alerte peut parfois prendre jusqu'à plusieurs minutes pour atteindre votre serveur.

Félicitations, vous avez configuré votre première alerte d'utilisation avec la CLI Twilio ! Il y a beaucoup de choses que vous pouvez faire avec la CLI Twilio. Dites-moi ce que vous découvrez sur Twitter !

Ashley est éditrice JavaScript pour le blog Twilio. Pour travailler avec elle et partager vos histoires techniques à Twilio, retrouvez-la sur la page @ahl389 sur Twitter. Si elle n'y est pas, c'est probablement qu'elle est quelque part en terrasse avec une tasse de café à la main (ou un verre de vin, selon l'heure).

Articles associés

Ressources connexes

Twilio Docs

Des API aux SDK en passant par les exemples d'applications

Documentation de référence sur l'API, SDK, bibliothèques d'assistance, démarrages rapides et didacticiels pour votre langage et votre plateforme.

Centre de ressources

Les derniers ebooks, rapports de l'industrie et webinaires

Apprenez des experts en engagement client pour améliorer votre propre communication.

Ahoy

Le hub de la communauté des développeurs de Twilio

Meilleures pratiques, exemples de code et inspiration pour créer des expériences de communication et d'engagement numérique.