L'application Android sert de passerelle SMS entre un smartphone et le backend.
Le serveur :
- authentifie l'application avec
api key+api secret - retourne un JWT
- expose des endpoints JSON sous
/api/mobile/... - publie les SMS sortants via Mercure sur
sms/outgoing
L'application :
- récupère un JWT
- écoute Mercure
- envoie physiquement les SMS depuis le téléphone
- remonte au backend les SMS entrants et les statuts
L'app doit d'abord appeler :
POST /api/authentication_token
avec les headers :
X-Api-Key: <api_key>
X-Api-Secret: <api_secret>{
"token": "...jwt...",
"expires_in": 3600,
"expires_at": 1234567890,
"type": "api_key",
"scope": "..."
}L'application n'utilise que token. Les autres champs peuvent être ignorés côté mobile.
Une fois le JWT obtenu, l'app appelle l'API avec :
Authorization: Bearer <jwt>
Content-Type: application/jsonSi une requête métier retourne 401, l'app redemande un JWT puis rejoue la requête.
Les endpoints attendus côté backend sont :
POST /api/mobile/incoming-smsPOST /api/mobile/outgoing-smsPOST /api/mobile/messages/{ulid}/statusGET /api/mobile/messages/{ulid}POST /api/mobile/heartbeat(voir Heartbeat)
Le contrôleur serveur mentionné est :
src/Controller/Api/MobileSmsController.php
Le service de la passerelle envoie un heartbeat au démarrage puis toutes les
4 minutes (HeartbeatReporter.INTERVAL_MS), déclenché par une alarme
ELAPSED_REALTIME_WAKEUP qui réveille le CPU même écran éteint (HeartbeatAlarm,
alarme exacte via USE_EXACT_ALARM ; l'exemption batterie évite que Doze espace
les envois de 9 min). Côté serveur
(ICTools/chapitreneuf#936), l'alerte e-mail « Passerelle SMS hors ligne » part
quand le dernier heartbeat a plus de SMS_GATEWAY_OFFLINE_THRESHOLD_MINUTES
(10 par défaut) ou quand plus personne n'est abonné au topic Mercure
sms/outgoing. Le serveur attend une cadence de 2 à 5 minutes.
Clé API au scope sms_gateway obligatoire. La route refuse tous les autres
scopes avec 403, y compris global (qui garde son accès transitoire aux
autres routes /api/mobile). Avec une clé global, les SMS passent mais le
heartbeat échoue : l'écran de configuration affiche alors
Heartbeat: échec … (403 : la clé API n'a pas le scope sms_gateway).
POST /api/mobile/heartbeat
Authorization: Bearer <jwt>
Content-Type: application/json
{
"batteryLevel": 87,
"charging": true,
"network": "wifi",
"appVersion": "1.0"
}Tous les champs sont facultatifs (null quand l'info manque) :
batteryLevel: 0-100charging: en charge ou batterie pleine sur secteurnetwork:wifi,cellular,ethernet,otherounoneappVersion:versionNamede l'APK
Réponse : {"success": true, "serverTime": "…"}.
{
"phoneNumber": "+32470000000",
"body": "Bonjour",
"deviceMessageId": 123,
"sentAt": "2026-03-31T10:15:00+02:00"
}{
"status": "sent",
"errorMessage": null
}Le backend doit aussi accepter les autres transitions de statut comme delivered ou failed.
L'événement Mercure ne contient qu'un ulid. L'app récupère ensuite le détail via :
GET /api/mobile/messages/{ulid}
Exemple de réponse attendue :
{
"ulid": "01HV...",
"phoneNumber": "+32470000000",
"body": "Bonjour",
"direction": "outgoing",
"createdAt": "2026-03-31T10:15:00+02:00"
}- L'utilisateur saisit
Base URL,API keyetAPI secret. - L'app appelle
POST /api/authentication_token. - Le serveur retourne un JWT.
- L'app ouvre ensuite la connexion Mercure avec ce JWT.
Le serveur ne délègue pas l'envoi à Twilio ou à un autre provider.
Dans :
src/Service/Sms/SmsService.php
le serveur :
- crée le SMS sortant en base
- publie un événement Mercure sur
sms/outgoing
Ensuite, côté mobile :
- l'app reçoit l'événement Mercure
- elle récupère le détail du message via
GET /api/mobile/messages/{ulid} - elle envoie le SMS depuis le téléphone
- elle renvoie les événements backend nécessaires
À minima, le backend doit recevoir :
POST /api/mobile/outgoing-smsPOST /api/mobile/messages/{ulid}/status
- Android reçoit le SMS
- l'app l'enregistre localement
- l'app appelle
POST /api/mobile/incoming-sms
Il faut créer une clé API dans l'admin :
src/Controller/Admin/ApiKeyCrudController.php
pour un utilisateur ayant :
ROLE_API_READER
L'application mobile doit ensuite utiliser cette paire :
api keyapi secret
pour obtenir son JWT.
- une
Base URLjoignable depuis le téléphone - une paire
api key/api secretvalide, au scopesms_gateway(heartbeat) - l'endpoint
POST /api/authentication_token - les endpoints
/api/mobile/... - Mercure accessible sur
/.well-known/mercure - un JWT accepté à la fois par l'API HTTP et par Mercure
- les permissions SMS et notifications acceptées sur Android
- le téléphone peut être hors ligne ; le backend doit tolérer les retards et doublons
- les endpoints mobile doivent être idempotents autant que possible
- la publication Mercure signale un SMS à expédier, pas un SMS déjà envoyé
- la confirmation réelle vient ensuite des callbacks mobiles remontés au backend