Pour envoyer des SMS depuis votre logiciel avec SageMessaging, il faut quatre choses : un compte gratuit, un téléphone Android avec sa carte SIM, l'application SageMessaging installée sur ce téléphone, et une clé API. Avec le SDK de votre langage, une ligne suffit ensuite, client.sms.send(), et le SMS part de votre propre numéro, au tarif de votre forfait.
Ce guide reprend chaque étape, de l'inscription au premier SMS, puis les envois différés, les campagnes et la gestion des erreurs.
Comment fonctionne SageMessaging
SageMessaging relie la carte SIM de votre téléphone Android à une API. Votre logiciel envoie une requête à l'API ; l'application installée sur le téléphone reçoit l'ordre et envoie le SMS depuis sa carte SIM. Les réponses de vos clients reviennent dans une boîte de réception web, et peuvent être transmises à votre logiciel.
Concrètement, le chemin d'un SMS est le suivant :
- votre logiciel appelle l'API SageMessaging avec votre clé ;
- SageMessaging transmet l'envoi à votre téléphone appairé ;
- le téléphone envoie le SMS depuis sa carte SIM ;
- votre client le reçoit, avec votre numéro comme expéditeur.
C'est ce qui le distingue d'une passerelle SMS classique : vous n'achetez pas de crédits, et vos clients reconnaissent votre numéro au lieu d'un expéditeur inconnu.
Ce qu'il vous faut avant de commencer
- Un compte SageMessaging, gratuit.
- Un téléphone Android avec une carte SIM qui a du crédit ou un forfait SMS. Ce téléphone enverra vos SMS : il doit rester allumé et connecté à internet.
- L'application SageMessaging pour Android. Elle est en test fermé sur Google Play : on y accède en laissant son e-mail.
- Une clé API avec la permission d'envoyer des SMS.
Créer votre compte
Rendez-vous sur messaging.sagecoders.com et cliquez sur « Créer un compte ». L'inscription est gratuite. Vous arrivez ensuite sur votre tableau de bord, d'où vous connecterez vos canaux et créerez vos clés.
Installer l'application Android
L'application est en version de test fermée sur Google Play. Sur la page Application Android, indiquez l'adresse e-mail du compte Google utilisé sur le téléphone : vous recevez le lien de la version de test, puis vous l'installez depuis Google Play, comme n'importe quelle application.
Installez-la sur le téléphone dont la carte SIM enverra les SMS.
Appairer votre téléphone
L'appairage relie le téléphone à votre compte. Il se fait en six étapes, décrites dans la documentation de SageMessaging :
- Activer les SMS. Dans le tableau de bord, cliquez sur « Activer les SMS », puis sur « QR de la clé » pour afficher le QR code de votre clé.
- Ouvrir l'application sur le téléphone.
- Scanner la clé. Touchez « Scanner mon QR code » et visez le QR code affiché à l'écran. Vous pouvez aussi coller la clé dans le champ « Clé API ».
- Indiquer vos numéros. Saisissez le numéro de la SIM 1 au format international (+225…), et celui de la SIM 2 si le téléphone en a deux. Touchez « Se connecter avec la clé API ».
- Laisser l'application vérifier les numéros. Elle envoie un SMS à chaque numéro pour le vérifier.
- Contrôler le résultat. Vos numéros s'affichent dans l'application : ✓ pour un numéro vérifié, ? pour un numéro non vérifié. Seuls les numéros vérifiés peuvent envoyer.
Créer une clé API pour votre logiciel
Votre logiciel s'identifie avec une clé API. Dans l'onglet « Clés API » du tableau de bord, créez une clé et cochez uniquement la permission**sms:send** : elle autorise l'envoi de SMS, un par un ou en campagne. Une clé limitée à ce qu'elle doit faire limite aussi les dégâts si elle venait à fuiter.
Envoyer votre premier SMS
Le plus simple est d'utiliser le SDK officiel de votre langage : il gère l'authentification, les erreurs et les envois à votre place.
Avec le SDK JavaScript
Le SDK fonctionne avec Node 20 ou plus récent, Bun et Deno, en ESM comme en CommonJS, sans aucune autre dépendance.
npm install sage-messaging
import { SageMessaging } from 'sage-messaging'
// La clé est lue dans la variable SAGE_MESSAGING_API_KEY
const client = new SageMessaging()
await client.sms.send({ phone: '+2250700000000', message: 'Votre commande est prête.' })
Avec le SDK Python
Le SDK Python fonctionne avec Python 3.9 ou plus récent, en version synchrone ou asynchrone.
pip install sage-messaging
from sage_messaging import SageMessaging
client = SageMessaging() # clé lue dans SAGE_MESSAGING_API_KEY
client.sms.send(phone="+2250700000000", message="Votre commande est prête.")
Le numéro du destinataire s'écrit au format international, avec l'indicatif du pays.
Votre langage n'a pas de SDK ? Utilisez l'API REST
PHP, Java, C#, Go, Dart ou Ruby n'ont pas encore de SDK : votre logiciel appelle directement l'API REST, par une simple requête HTTP. La clé se place dans l'en-tête Authorization.
curl -X POST https://messaging.sagecoders.com/api/sms/send \
-H "Authorization: Bearer $SAGE_MESSAGING_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"phone": "+2250700000000", "message": "Votre commande est prête."}'
Les fonctions présentées ci-dessous existent aussi en REST, avec les mêmes paramètres : la référence complète, avec un testeur intégré, se trouve dans l'onglet « Documentation » de votre espace.
Aller plus loin
Choisir le téléphone émetteur
Si vous avez appairé plusieurs téléphones ou plusieurs SIM, indiquez l'émetteur avec le champ from : le numéro d'une de vos SIM vérifiées, au format international, tel qu'il s'affiche dans l'application.
await client.sms.send({ phone: '+2250700000000', message: 'Votre commande est prête.', from: '+2250500000000' })
Programmer un SMS
Le champ send_at diffère l'envoi, jusqu'à 20 jours à l'avance : pratique pour un rappel de rendez-vous la veille.
await client.sms.send({
phone: '+2250700000000',
message: 'Rappel : votre rendez-vous est demain à 10 h.',
send_at: new Date(Date.now() + 24 * 3600_000),
})
Envoyer une campagne
bulkSend (bulk_send en Python) envoie le même message à 1 à 100 destinataires par appel. L'envoi différé n'est pas disponible pour les campagnes. En REST, c'est la route POST /api/sms/bulk-send.
await client.sms.bulkSend({
phones: ['+2250700000000', '+2250500000000'],
message: 'Nos nouveaux horaires : 8 h – 20 h, du lundi au samedi.',
})
Recevoir les réponses
Les réponses de vos clients arrivent dans la boîte de réception SageMessaging, où votre équipe peut répondre à la main.
Pour que votre logiciel les reçoive aussi, déclarez une adresse dans l'onglet « Webhooks » de votre espace. SageMessaging y envoie les événements message.received et message.sent, signés en HMAC-SHA256 et relancés trois fois en cas d'échec. Vérifiez toujours la signature, sur le corps brut de la requête, avant de traiter le message.
Gérer les erreurs
L'API répond avec des codes HTTP explicites :
| Code | Signification | Que faire |
|---|---|---|
| 422 | Requête invalide ou canal pas encore prêt | Corriger le champ indiqué, ou terminer l'appairage du téléphone |
| 403 | La clé n'a pas la permission requise | Ajouter sms:send à la clé |
| 502 | La passerelle SMS a refusé l'envoi | Vérifier le téléphone, sa connexion et le crédit de la SIM |
Les envois ne sont jamais relancés automatiquement, ni par l'API ni par les SDK. C'est volontaire : un envoi dont la réponse s'est perdue a pu partir, et le relancer enverrait le SMS en double. Si vous ajoutez une relance dans votre logiciel, limitez-la aux erreurs dont vous êtes sûr qu'elles n'ont rien envoyé.
Des usages concrets
Une fois l'intégration faite, chaque événement de votre logiciel peut déclencher un SMS : un code de vérification à la connexion, la confirmation d'une commande, un rappel de rendez-vous ou d'échéance, une alerte de stock bas envoyée au gérant.
C'est ce que nous faisons dans nos propres produits. SageHotel envoie à l'hôtelier son résumé du soir par WhatsApp ou par SMS. Ce site s'en sert aussi : les codes de connexion partent par WhatsApp, avec un repli par SMS si WhatsApp échoue.
Récapitulatif
| Étape | Où |
|---|---|
| Créer un compte gratuit | messaging.sagecoders.com |
| Installer l'application Android | Page « Application », test fermé sur Google Play |
| Activer les SMS et appairer le téléphone | Tableau de bord, puis l'application |
Créer une clé avec sms:send | Onglet « Clés API » |
| Installer le SDK | npm install sage-messaging ou pip install sage-messaging |
| Envoyer le premier SMS | client.sms.send(), ou POST /api/sms/send sans SDK |
La référence complète de chaque route, avec un testeur intégré, se trouve dans l'onglet « Documentation » de votre espace SageMessaging. Pour WhatsApp, lisez notre guide pour envoyer des messages WhatsApp par API gratuitement. Et si vous préférez qu'on s'en charge, notre équipe développe des logiciels sur mesure avec les SMS déjà branchés.
