Passerelle SMS

1 · Le principe : une passerelle, un téléphone

La passerelle est un serveur. Elle ne possède ni carte SIM ni antenne : elle ne sait pas émettre un SMS. Son rôle est de collecter les demandes d'envoi, de les mettre dans une file d'attente, puis de les confier à un téléphone Android équipé de l'application SmsGateway. C'est ce téléphone, avec sa carte SIM et son forfait, qui envoie réellement les SMS.

Point important : le serveur n'appelle jamais le téléphone. C'est toujours le téléphone qui appelle le serveur, à intervalle régulier (60 secondes par défaut). Le téléphone peut donc rester derrière une box, un pare-feu ou un réseau mobile, sans aucune ouverture de port.

Deuxième point important : la passerelle expose deux portes d'entrée distinctes, sur deux ports différents. Les agents se connectent avec un identifiant et un mot de passe sur la console web ; les applications tierces se connectent avec une clé API sur l'API publique. Ce sont deux serveurs séparés dans le même conteneur, qui ne partagent que la base.

1. Dépôt par un agent. Un agent se connecte à la console web (port 3251) avec son identifiant et son mot de passe, puis écrit son message. Il est enregistré au statut en attente.
2. Dépôt par une application. Une application tierce appelle l'API publique (port 3250) en présentant une clé « web ». Le message arrive dans la même file, avec son origine notée dans l'historique.
3. Sondage. Le téléphone appelle l'API toutes les 60 secondes en présentant sa clé « passerelle ». Il en profite pour remonter ce qu'il a fait depuis le dernier appel.
4. Attribution. Le serveur lui remet un lot de messages (25 au maximum par appel) et les passe au statut en cours d'envoi pour qu'aucun autre téléphone ne les reprenne.
5. Émission. Le téléphone envoie les SMS par sa carte SIM, comme n'importe quel SMS classique. Les messages longs sont découpés puis réassemblés par l'opérateur.
6. Compte rendu. Au sondage suivant, le téléphone renvoie les statuts (envoyé, remis, échec) ainsi que les SMS reçus sur sa ligne, qui apparaissent dans l'onglet Messages → Reçus.

Les deux portes, en pratique

Comme les deux services écoutent sur des ports différents, il vous faut soit deux URL (typiquement derrière un reverse proxy), soit une seule URL avec deux ports. Les deux fonctionnent ; le choix dépend de ce que vous voulez exposer à l'extérieur.

Deux conséquences pratiques : l'URL à saisir dans l'application Android est celle de l'API (port 3250), pas celle de la console ; et l'URL déclarée dans Synchro carnets pour une passerelle distante est également celle de son API. Si vous placez la passerelle derrière un reverse proxy, renseignez PUBLIC_BASE_URL avec l'adresse publique de l'API, faute de quoi les liens de pièces jointes envoyés dans les SMS pointeront vers une adresse injoignable.

2 · Mettre un téléphone en service

L'application n'est pas publiée sur le Play Store : elle s'installe à partir de son fichier .apk. Android multiplie donc les avertissements, qu'il faut franchir un par un. Le téléphone doit ensuite devenir l'application SMS par défaut — c'est la condition posée par Android pour qu'une application puisse envoyer des SMS sans demander une confirmation à chaque message.

Choisissez un téléphone dédié, avec une ligne dédiée. Une fois l'application définie comme application SMS par défaut, tous les SMS reçus sur cette ligne remontent dans la console et l'application de messagerie habituelle ne reçoit plus rien.

Quel téléphone choisir ?

• Le Wi-Fi suffit, la 4G est inutile. Le téléphone n'a besoin d'Internet que pour joindre la passerelle : un simple Wi-Fi fait parfaitement l'affaire. Le forfait de la carte SIM doit couvrir les SMS, pas nécessairement les données mobiles.
• Un vieux téléphone convient très bien. Modèle ancien, écran fissuré, batterie fatiguée, appareil mis au rebut : sans importance. Il ne fait que sonder la passerelle et émettre des SMS. Android 8 ou plus récent suffit.
• La charge permanente, elle, n'est pas négociable. C'est la seule vraie contrainte matérielle. Une batterie usée se vide en quelques heures, et un téléphone éteint ne sonde plus : plus aucun SMS ne part. Laissez-le branché en permanence, sur une prise qui ne se coupe pas.
• Au total. Une prise de courant, un accès Wi-Fi, une carte SIM active avec un forfait SMS, et Android 8 ou plus récent. Rien d'autre.

1. Autoriser les sources inconnues. Paramètres → Applications → Accès spécial → Installer des applications inconnues, puis autoriser l'application avec laquelle vous ouvrirez le fichier (le navigateur, ou le gestionnaire de fichiers). Sans cela, l'installation est bloquée sans explication.
2. Télécharger l'APK. Le navigateur affiche « ce type de fichier peut endommager votre appareil » : choisissez Télécharger quand même. L'avertissement est générique, il s'applique à tout APK.
3. Installer malgré Play Protect. À l'ouverture du fichier, Google Play Protect signale une « application non reconnue ». Choisissez Installer quand même (ou Plus de détails → Installer quand même). Si l'analyse est proposée, vous pouvez l'accepter puis installer.
4. Accorder les autorisations. Au premier démarrage du service, l'application demande l'envoi de SMS, la réception de SMS et MMS, et les notifications. Toutes sont nécessaires : un refus empêche l'envoi automatique ou la remontée des SMS reçus.
5. Définir l'application SMS par défaut. Bouton Définir comme app SMS par défaut, qui ouvre Paramètres → Applications par défaut → Application SMS. Choisissez Passerelle SMS. L'écran doit ensuite afficher « Statut : app SMS par défaut ✓ ».
6. Saisir la première passerelle. Dans les paramètres de l'application : un nom libre, l'URL de l'API sous la forme http://192.168.1.10:3250 (le port de l'API, pas celui de la console), et la clé API créée dans l'onglet Clés API avec le type « Passerelle ». Puis Enregistrer.
7. Ajouter d'autres passerelles. Le bouton + ajoute un profil. Répétez l'opération pour chaque passerelle à servir, avec à chaque fois l'URL de cette passerelle et une clé créée sur cette passerelle. Un même téléphone peut ainsi desservir plusieurs collectivités.
8. Démarrer le service. Basculez l'interrupteur Service. Une notification permanente apparaît, et la ligne « Dernière connexion API » doit se mettre à jour dans la minute.
9. Vérifier côté console. Dans l'onglet Passerelles, le téléphone apparaît avec son dernier contact et sa version d'APK, et la pastille en haut de page passe au vert.
10. Envoyer un SMS de test. Le champ de test de l'application envoie un SMS réel à un numéro de votre choix : c'est la vérification de bout en bout la plus rapide.

• Neutraliser les mises en veille. Désactivez l'optimisation de batterie pour l'application et, si la marque en propose un, son gestionnaire d'applications en arrière-plan : sinon Android finit par suspendre le service au bout de quelques heures.
• Après un redémarrage. Le service repart tout seul au démarrage du téléphone et après une mise à jour de l'application ; il n'y a rien à relancer à la main.
• Mettre à jour l'APK. Réinstallez simplement la nouvelle version par-dessus : les profils API, la clé et l'identifiant d'appareil sont conservés. La version installée remonte dans l'onglet Passerelles.
• En HTTP ou en HTTPS. L'application accepte les deux. En dehors d'un réseau interne maîtrisé, utilisez HTTPS : la clé de passerelle circule à chaque sondage.

3 · Plusieurs téléphones pour une même passerelle

Un téléphone envoie un SMS toutes les quelques secondes : au-delà de quelques centaines de messages, il devient le goulot d'étranglement. Il suffit alors de déclarer une clé « passerelle » par téléphone et de les faire pointer vers le même serveur. Aucune configuration supplémentaire n'est nécessaire côté serveur : la répartition est automatique.

• Répartition automatique. À chaque tour de 60 secondes, le serveur compte les téléphones actifs et n'accorde à chacun qu'environ 1/N des messages en attente. Le débit est donc multiplié par le nombre de téléphones.
• Rattrapage. Si un message attend depuis plus d'un intervalle, il devient prenable par n'importe quel téléphone : une panne de terminal ne bloque jamais la file.
• Reprise des blocages. Un message resté « en cours d'envoi » plus de 10 minutes (téléphone éteint, hors réseau) est automatiquement remis à disposition d'un autre téléphone.
• Supervision. L'onglet Passerelles indique pour chaque téléphone son dernier contact, sa version d'APK et son compteur d'envois ; la pastille verte en haut de page compte les téléphones actifs.

4 · Plusieurs passerelles, plusieurs téléphones

Chaque entité (mairie, CCAS, police municipale…) peut disposer de sa propre passerelle, avec sa base, ses comptes et ses carnets. Mais les téléphones, eux, n'ont pas à être dédiés : l'application Android accepte plusieurs profils API. Un même téléphone interroge alors tour à tour chaque passerelle configurée et envoie les SMS des unes et des autres.

La relation est donc de plusieurs à plusieurs : une passerelle peut être servie par plusieurs téléphones, et un téléphone peut servir plusieurs passerelles.

• Un profil = une passerelle. Dans l'application Android, chaque profil porte un libellé, l'URL de la passerelle (port API) et la clé « passerelle » créée sur cette passerelle. Les profils s'ajoutent et se retirent sans réinstaller l'APK.
• Des clés distinctes. Le même téléphone reçoit une clé différente sur chaque passerelle. Révoquer la clé sur une passerelle ne coupe pas les autres.
• Les passerelles s'ignorent. Elles ne communiquent pas entre elles pour les envois : chacune tient sa propre file, ses propres statuts, son propre journal. Seuls les carnets d'adresses peuvent être partagés (voir ci-dessous).
• Une SIM, un forfait. Les SMS des différentes passerelles partagent la même ligne : c'est le point à surveiller lors du dimensionnement, pas la puissance du serveur.

5 · Synchronisation des carnets entre passerelles

Les carnets d'adresses sont souvent tenus à jour à un seul endroit (les élus, les agents d'astreinte, une liste de diffusion). L'onglet Synchro carnets permet à une passerelle d'aller recopier automatiquement des carnets hébergés sur une autre passerelle.

• Sens unique. La passerelle qui synchronise tire les contacts depuis la source. La source n'est jamais modifiée et n'a rien à configurer, hormis fournir une clé « web ».
• Mise en place. Onglet Synchro carnets → déclarer la source (libellé, URL sur le port API, clé « web » de l'autre instance) → parcourir ses carnets → cocher ceux à reprendre.
• Rafraîchissement. Automatique toutes les heures, ou à la demande via le bouton de relance. Le contenu local du carnet synchronisé est remplacé à chaque passage : il ne se modifie pas à la main.
• Visibilité. Les carnets synchronisés sont réservés aux administrateurs ; ils n'apparaissent pas dans l'interface d'envoi des groupes.
• Réciprocité. Rien n'empêche A de synchroniser un carnet de B en parallèle : chaque passerelle choisit ce qu'elle importe.

6 · La vie d'un message

Chaque message porte un statut, visible dans l'onglet Messages et filtrable. Comprendre cet enchaînement suffit à diagnostiquer la quasi-totalité des situations.

7 · La liste noire

La liste noire recense les numéros que la passerelle doit refuser : une personne qui a demandé à ne plus être contactée, une ligne résiliée qui a été réattribuée à quelqu'un d'autre, le numéro d'un agent parti. Elle évite d'avoir à purger les carnets à la main à chaque envoi.

• Elle vaut pour toute l'instance. Un numéro blacklisté l'est pour tous les groupes, sans cloisonnement : c'est une décision qui engage la collectivité entière, pas un service.
• Tout le monde peut l'alimenter. Un utilisateur comme un administrateur peut ajouter ou retirer un numéro, depuis le bouton Numéros blacklistés de l'écran des carnets d'adresses. La console note qui a fait l'ajout.
• Les contacts concernés sont signalés. Dans un carnet, un contact dont le numéro figure sur la liste apparaît marqué : inutile de comparer les deux listes à la main.
• Le contact n'est pas supprimé. Il reste dans le carnet, avec sa fiche complète ; seul l'envoi est bloqué. Retirer le numéro de la liste noire le rend de nouveau joignable immédiatement.

Où la liste noire s'applique

À retenir : la liste noire protège les envois en masse, qui sont le vrai risque, mais elle n'intercepte pas un message unitaire ni un appel à l'API. Ne la considérez pas comme une garantie absolue de non-sollicitation.

8 · La vérification de flotte

Vérifier une flotte, c'est répondre à une question que l'inventaire ne sait pas trancher : ces téléphones sont-ils réellement en service, et leurs porteurs répondent-ils ? La passerelle envoie un SMS de test à tout un carnet, puis attend une réponse pendant 72 heures et dresse le bilan, contact par contact.

C'est l'outil des astreintes et des téléphones de service : il détecte les lignes coupées, les appareils éteints depuis des mois, les numéros erronés dans le carnet, et les porteurs qui ne consultent pas leurs messages.

1. Choisir le carnet à contrôler. Tous ses contacts sont proposés ; vous pouvez n'en cocher qu'une partie.
2. Exclure un second carnet si besoin. Pratique pour ne pas retester les contacts déjà vérifiés le mois précédent, ou pour épargner une liste de responsables.
3. Rédiger le message de test. Les mêmes variables que les campagnes sont disponibles ({prénom}, {service}, {imei}…), ce qui permet de demander une confirmation personnalisée.
4. Lancer la vérification. Les messages partent par la file normale, comme n'importe quelle campagne — ils consomment donc des SMS du forfait.
5. Laisser courir 72 heures. Chaque réponse reçue sur la ligne de la passerelle est rattachée automatiquement au contact qui l'a envoyée.
6. Lire le bilan. Le tableau donne, par contact, l'état, la date de remise, la date de réponse, le délai écoulé et le texte de la réponse. L'export CSV reprend le tout avec l'identité, l'entité, le service, la direction, l'IMEI et le PUK.

• Le délai part de la remise. Un contact ne bascule en « sans réponse » que 72 heures après l'accusé de remise. Un porteur qui rallume son téléphone deux jours plus tard reste donc dans les temps.
• Sans accusé de remise, pas de verdict. Si l'opérateur ne renvoie jamais d'accusé, le contact reste au stade précédent : il ne sera pas compté « sans réponse » à tort, mais il ne pourra pas non plus être compté « répondu ». C'est la limite de l'exercice, et elle dépend de l'opérateur, pas de la passerelle.
• N'importe quelle réponse compte. L'appariement se fait sur le numéro de l'expéditeur, quel que soit le texte renvoyé. Les formats +33, 0033 et 06… sont ramenés à une forme unique avant comparaison.
• Une réponse pour une vérification. Si le même numéro est engagé dans plusieurs vérifications en attente, la réponse est rattachée à la plus ancienne. Évitez de lancer deux contrôles simultanés sur le même carnet.
• Les états se recalculent à l'ouverture. Le passage en « sans réponse » est évalué au moment où vous consultez l'écran : un bilan affiché juste après l'échéance est à jour.
• Le porteur reçoit un vrai SMS. Prévenez les agents avant un contrôle de grande ampleur, faute de quoi vous récolterez surtout des appels au standard.

9 · Mail vers SMS : transformer un e-mail en SMS

L'onglet Mail → SMS permet de déclarer des boîtes mail (IMAP) que la passerelle surveille régulièrement. Un e-mail reçu sur une boîte active, s'il provient d'un expéditeur autorisé et respecte le format décrit ci-dessous, est transformé en SMS envoyé par les téléphones de la flotte. Quelques minutes plus tard, un compte-rendu est renvoyé par e-mail à l'expéditeur.

Le format attendu

• Le sujet de l'e-mail devient le contenu du SMS. 1000 caractères maximum ; au-delà, l'e-mail est refusé et l'expéditeur reçoit un compte-rendu d'erreur.
• Le corps indique les destinataires. Des numéros de téléphone (un par ligne, ou séparés par des espaces, virgules ou points-virgules) et/ou le nom d'un carnet d'adresses : une ligne carnet : Astreinte, ou #Astreinte, ou le nom exact du carnet sur sa propre ligne.
• Les pièces jointes deviennent des liens. Jusqu'à 5 pièces jointes de 10 Mo chacune sont conservées et un lien de téléchargement public est ajouté au SMS (jusqu'à la limite des 1000 caractères).
• Le compte-rendu. Envoyé à l'expéditeur après le délai configuré (5 minutes par défaut) : nombre de SMS demandés, statut de chacun (remis, envoyé, en attente, échec, annulé), horaires et éventuelles erreurs.

Déclarer une boîte

1. Ouvrir l'onglet Mail → SMS puis Nouvelle boîte mail.
2. Identifiants IMAP. Nom de la boîte, adresse e-mail, serveur IMAP (hôte, port 993 par défaut, dossier INBOX), identifiant et mot de passe. Pour une boîte Google, utilisez un mot de passe d'application.
3. Expéditeurs autorisés. Un motif par ligne, avec « * » pour remplacer n'importe quelle suite de caractères — par exemple m*@ivry94.fr. Tout e-mail venant d'une autre adresse est ignoré (et noté dans l'historique).
4. Options de relevé. Période du relevé (60 secondes par défaut), boîte active ou non.
5. Compte-rendu. Activer ou non la réponse, délai avant envoi, préfixe de l'objet, et serveur SMTP — laisser vide pour réutiliser le serveur et les identifiants IMAP.
6. Enregistrer puis vérifier. Le bouton Tester contrôle la connexion IMAP (nombre de messages, non lus) ; le bouton Scanner relève la boîte immédiatement. Les boîtes actives sont relevées automatiquement.

• Chaque e-mail n'est traité qu'une fois. Seuls les e-mails non lus sont examinés ; une fois transformés en SMS, ils sont déplacés dans un dossier IMAP — SMS Traités par défaut (créé automatiquement, nom configurable dans le formulaire). Ils ne sont donc jamais retraités. Les e-mails déjà traités mais encore présents dans la boîte de réception (relevé interrompu) sont repris et déplacés au relevé suivant.
• Relevés bornés. Chaque relevé traite au plus 50 e-mails (variable MAIL2SMS_MAX_PER_SCAN) pour rester rapide ; les e-mails restants sont pris au relevé suivant. Le bouton Scanner affiche le nombre de traités / ignorés / erreurs.
• Envoi du compte-rendu (SMTP). En cas d'échec de connexion, l'envoi retente automatiquement sur le port 587 (STARTTLS) puis 465 (TLS) ; le bouton Tester SMTP vérifie chaque variante et affiche l'erreur exacte (port bloqué, identifiants invalides…).
• La liste noire s'applique. Les numéros blacklistés sont exclus des destinataires. Si aucun destinataire n'est valide, l'e-mail est refusé et l'expéditeur reçoit un compte-rendu d'erreur qui rappelle le format attendu.
• Traçabilité. L'onglet E-mails traités liste chaque e-mail avec sa boîte, son expéditeur, son sujet, le nombre de SMS créés, le statut du traitement et celui du compte-rendu. Un e-mail rejeté (expéditeur non autorisé, format invalide…) apparaît aussi, avec le motif.

10 · Qui fait quoi — les rôles

Deux mondes cohabitent : les comptes humains, qui se connectent avec un identifiant et un mot de passe sur la console (port web), et les clés API, qui authentifient des machines sur le port API. Les deux sont gérés depuis cette console.

11 · Ce que peut faire un utilisateur

Un utilisateur travaille dans l'interface d'envoi, cloisonnée à son groupe. Il ne voit jamais les messages des autres groupes, ni la configuration technique de la passerelle.

12 · Ce que peut faire un administrateur

L'administrateur dispose de tout ce qui précède, sans cloisonnement par groupe, plus la totalité de la configuration et de la supervision.

13 · Matrice des droits

14 · Glossaire

Passerelle

Selon le contexte : l'instance serveur complète (« la passerelle de la mairie »), ou un téléphone déclaré sur cette instance, tel qu'il apparaît dans l'onglet Passerelles.

Groupe

Unité de cloisonnement. Ses membres partagent les mêmes carnets et ne voient que les messages partis du groupe.

Carnet d'adresses

Liste de contacts appartenant à un groupe, avec les champs métier entité, service, direction, IMEI et PUK.

Campagne

Envoi groupé issu d'un carnet. Les messages restent regroupés dans l'historique, avec leurs compteurs et une annulation d'ensemble.

Variable

Marqueur du type {prénom} remplacé, pour chaque destinataire, par la valeur de sa fiche contact.

Liste noire

Numéros interdits d'envoi sur toute l'instance. Une campagne qui en contient est refusée avant tout départ.

Vérification de flotte

Campagne de test attendant une réponse des porteurs, pour contrôler qu'un parc de téléphones est bien en service.

Pièce jointe

Fichier téléversé sur la passerelle et diffusé sous forme de lien ajouté au SMS, avec date d'expiration et suivi des ouvertures.

Profil API

Couple URL + clé enregistré dans l'application Android. Un profil par passerelle servie.

Sondage

Appel périodique du téléphone vers le serveur. Il n'existe aucune connexion entrante vers le téléphone.

15 · Dépannage courant