Relier Twilio à votre logiciel métier pour les SMS et la téléphonie

Quels échanges l'API Twilio rend-elle possibles ?

L'API Twilio permet à un logiciel métier d'envoyer des SMS et des MMS, d'en suivre le statut, de programmer un envoi, de recevoir les réponses des clients et de gérer des appels téléphoniques. Selon la documentation de Twilio, un envoi est une requête POST sur la ressource Message (API en version 2010-04-01) ; le logiciel relit ensuite le message par son identifiant, peut en effacer le texte (corps vide) ou annuler un envoi programmé.

Quand un client appelle votre numéro Twilio, Twilio interroge votre application, qui répond en TwiML, le jeu d'instructions vocales de Twilio, pour décider de la suite de l'appel. À la fin d'un enregistrement, un rappel transmet le lien du fichier audio (RecordingUrl).

Clés d'API et Auth Token : qui signe les requêtes ?

Selon la documentation de Twilio, les requêtes à l'API s'authentifient avec l'identifiant (SID) d'une clé d'API et son secret. Twilio distingue trois types de clés :

• Main : accès complet, équivalent à l'identifiant de compte et à l'Auth Token, créé uniquement depuis la console ;
• Standard : accès à tout, sauf aux points d'accès /Accounts et /Keys ;
• Restricted : accès limité aux ressources choisies, par exemple le seul envoi de messages.

Le secret n'est affiché qu'à la création de la clé ; supprimer la clé révoque l'accès et invalide les jetons générés avec elle.

Dans nos intégrations, l'Auth Token ne sert qu'à vérifier la signature des webhooks ; les appels sortants passent par une clé restreinte par usage, rangée dans un coffre de secrets.

Expéditeur, débit, file d'attente : ce qui décide de l'heure d'arrivée

Le type d'expéditeur détermine ce que voit le client, s'il peut répondre et à quel rythme les messages partent.

• Un nom d'entreprise (expéditeur alphanumérique, 11 caractères au plus) rassure le destinataire, mais celui-ci ne peut pas y répondre. Selon Twilio, ce type d'expéditeur est réservé aux comptes payants, indisponible aux États-Unis et au Canada, et certains pays exigent un enregistrement préalable.
• Un numéro de téléphone reçoit les réponses, ce qui rend possible un « répondez OUI pour confirmer » : Twilio transmet chaque SMS entrant à votre application par webhook.
• Un Messaging Service regroupe les réglages d'un usage, dont l'adresse de rappel de statut ; la documentation de Twilio y renvoie pour les gros volumes et les envois programmés.

Le débit dépend du type d'expéditeur et du pays : Twilio cite 100 messages par seconde pour un code court, 1 pour un numéro long américain, jusqu'à 10 pour un numéro long britannique. Au-delà, les messages attendent dans une file (statut queued), 10 heures par défaut (36 000 secondes) ; pour un code de connexion, Twilio suggère une durée de validité courte, par exemple 120 secondes, et le connecteur traite un code expiré comme un échec au lieu de le renvoyer en boucle. Programmer l'après-midi les rappels du soir étale la charge, et un envoi programmé reste annulable si le rendez-vous est déplacé.

Tester l'intégration sans déranger un client

Twilio conseille de garder les identifiants du compte hors du code, dans des variables d'environnement qui distinguent le test de la production. Ses identifiants de test ne facturent rien et ne joignent aucun vrai numéro : ils couvrent l'envoi de SMS, les appels, l'achat de numéros et Lookup, avec des numéros dits magiques (+15005550006 valide, +15005550001 invalide) pour provoquer les erreurs, mais ne déclenchent aucun rappel de statut.

La recette finale se fait donc sur le compte réel, avec deux jeux de clés restreintes (recette et exploitation) et quelques numéros internes : le statut de chaque message (queued, sent, delivered ou undelivered) et chaque webhook reçu sont contrôlés avant la bascule. Twilio rappelle que ses webhooks ne fonctionnent pas sur une adresse HTTPS dotée d'un certificat auto-signé, et recommande de tester avec les certificats de production avant la mise en service.

Pendant la recette, le Debugger de la console signale les erreurs survenues lors de l'envoi d'un webhook à votre application, et l'inspecteur de requêtes montre la requête exacte envoyée par Twilio ; pour les appels vocaux, ces journaux sont conservés 30 jours.

Webhooks Twilio : vérifier, répondre, rattraper

Chaque SMS reçu, appel entrant ou changement de statut déclenche une requête de Twilio vers votre application. Pour un SMS ou un appel entrant, Twilio attend du TwiML en retour (une réponse vide si le logiciel ne répond pas au client) ; pour un rappel de statut, un simple 200 OK.

1. Vérifier la signature : l'en-tête X-Twilio-Signature contient un HMAC-SHA1 calculé avec l'Auth Token sur l'URL et tous les paramètres. Twilio déconseille d'écrire sa propre vérification et renvoie vers celle de ses SDK ; l'URL ne doit pas être réencodée.
2. Servir en HTTPS avec un certificat reconnu : Twilio refuse les certificats auto-signés.
3. Oublier le filtrage par adresse IP : Twilio n'a pas de plage fixe d'adresses émettrices, et suggère plutôt un équilibreur de charge exposé qui relaie vers le réseau interne.
4. Rattraper : un statut manqué se relit sur la ressource Message par son identifiant ; le connecteur relit chaque nuit les messages restés sans statut final.

Pour la mécanique générale, voir notre définition du webhook.

Quatre usages concrets de Twilio dans un logiciel métier

• Rappel de rendez-vous avec confirmation. La veille, le logiciel programme un SMS par rendez-vous depuis un numéro de téléphone Twilio. Le client répond « OUI » ou « NON » ; le webhook de message entrant retrouve le rendez-vous par le numéro et met à jour le planning, un « NON » libérant le créneau. Voir notre page sur la prise de rendez-vous en ligne.
• Avis de passage du technicien. Quand le technicien démarre sa tournée dans l'application terrain, chaque client reçoit un SMS au nom de l'entreprise avec l'heure estimée, et le statut « delivered » remonte sur l'intervention. Ce cas prolonge notre page sur les applications pour équipes terrain.
• Ligne d'astreinte. Un appel arrive sur le numéro d'astreinte ; le logiciel cherche la personne de garde dans le planning et répond en TwiML pour orienter l'appel. Le statut « completed » horodate l'intervention.
• Appels enregistrés rattachés au dossier. Quand l'appelant a été informé de l'enregistrement, le rappel d'enregistrement fournit le lien du fichier, rangé dans le dossier du client.

Désinscription, données personnelles et coût des segments

La CNIL rappelle que la prospection par SMS vers des particuliers exige leur consentement préalable, sauf clients existants sollicités pour des produits analogues, et que chaque message doit indiquer l'émetteur et offrir un moyen simple de refuser les envois suivants. Avec un expéditeur alphanumérique, le mot STOP ne fonctionne pas, rappelle Twilio : la désinscription passe alors par un autre moyen (contact, numéro ou code à envoyer). Un rappel de rendez-vous ne vise pas à vendre, mais la frontière avec la prospection dépend du contenu : en cas de doute sur un message, sa qualification relève de votre conseil juridique. Dans tous les cas, le numéro de téléphone est une donnée personnelle à inscrire au registre, comme le détaille notre guide RGPD et logiciel métier.

Côté coût, au-delà de 160 caractères GSM-7, ou de 70 en Unicode (UCS-2), un SMS est découpé en segments facturés chacun : Twilio indique leur nombre pour chaque message (num_segments), et le journal du connecteur les suit pour repérer un modèle de message trop bavard. Le tarif se relève sur la grille officielle de Twilio au moment du cadrage, pour chaque pays visé.

Ce que YMHB Web met en place avec Twilio

Twilio n'est pas toujours nécessaire : pour quelques SMS de rappel depuis un logiciel du marché, son module SMS intégré suffit souvent. Twilio prend l'avantage quand SMS et appels doivent dialoguer, dans les deux sens, avec un logiciel spécifique. Nous cadrons alors les messages, les expéditeurs et les pays, puis nous chiffrons.

• le compte Twilio, les numéros et les clés restreintes à votre nom ;
• un Messaging Service par usage (rappels, alertes, codes), avec son adresse de rappel de statut ;
• le code du connecteur et du point de réception des webhooks, documenté et déposé chez vous ;
• un journal de chaque message (identifiant, statut, nombre de segments) et une alerte en cas d'échecs répétés ;
• la mise à jour du connecteur quand Twilio fait évoluer son API, dans la maintenance évolutive.

Pour relier plusieurs outils autour du même logiciel, voir connecter ses logiciels par API.