Votre premier SMS

Cette page est conçue pour être lue une fois. Si vous avez déjà parcouru le Démarrage rapide, passez à Envoyer un SMS instantané pour les patterns multi-destinataires.

La requête minimale viable

POST /api/v1/lisoloo/sms-api/send HTTP/1.1
Host: {BASE_URL}
app-key: sk_test_kqz3pX9aB7nT2vR4wY8eD1fH6jM5oU0i
Content-Type: application/json

{
  "to": ["+243998857000"],
  "message": "Bonjour de Lisoloo !"
}

{BASE_URL} est l’hôte sandbox depuis votre portail développeur → Lisoloo → Developer → Clés API.

Deux champs requis :

• to est toujours un tableau — même pour un seul destinataire. Chaque entrée doit être au format E.164 (+CCNNNNNN…). La passerelle rejettera la requête avec 1104 INVALID_PHONE_NUMBER si une entrée échoue à la regex ^\+?\d{1,15}$.
• message est le corps du SMS. UTF-8 simple. La longueur détermine combien de segments SMS seront facturés — voir Limites de caractères.

Tout le reste (sender_id, sending_type, callback_url, scheduled_dates, recurring_schedule) est optionnel. Sans aucun de ces champs, la passerelle traite la requête comme sending_type: "immediate" et la met en file pour expédition immédiate.

La réponse minimale viable

{
  "status_code": 201,
  "data": {
    "message_id": "507f1f77bcf86cd799439011",
    "total_recipients": 1,
    "total_messages": 1,
    "total_cost": 0.02,
    "currency": "USD",
    "status": "pending",
    "sending_type": "immediate"
  }
}

Ce que chaque champ signifie :

Champ	Type	Notes
status_code	int	Reflète le statut HTTP — 201 à la mise en file réussie.
data.message_id	string	L’ID canonique. À utiliser sur GET /status/{message_id} et pour corréler les événements webhook.
data.total_recipients	int	Nombre de numéros uniques dans to.
data.total_messages	int	total_recipients × segments_per_message. Voir Limites de caractères.
data.total_cost	float	Coût pré-TVA dans currency. Déjà déduit de votre solde.
data.currency	string	Code ISO 4217 à trois lettres.
data.status	string	Statut initial. pending pour immédiat, scheduled pour scheduled/recurring. Voir Cycle de vie.
data.sending_type	string	Renvoie le sending_type de la requête (immediate, scheduled ou recurring).

Ce qui se passe côté serveur

1. La passerelle a reçu la requête et validé l’en-tête app-key.
2. Elle a vérifié votre solde — available_sms ≥ total_messages.
3. Elle a mis en file un job de livraison par destinataire contre le connecteur opérateur.
4. Elle a retourné 201 immédiatement. Le handoff réel vers l’opérateur se fait de façon asynchrone ; le statut transite par pending → processing → sent → delivered au cours des prochaines secondes.
5. Si un callback_url ou un webhook_url au niveau marchand est configuré, la passerelle POST un accusé à chaque transition.

Un appel par événement métier

Chaque POST /send est une unité comptable. Si vous voulez envoyer le même message à 500 personnes, faites-le en un seul appel avec un tableau to de 500 éléments — pas 500 appels séparés. Moins de requêtes, moins de heurts avec les limites de débit, un message_id à suivre au lieu de 500.

Ce qui peut mal tourner

Symptôme	Cause probable	Correctif
401 Missing or invalid app-key	En-tête absent, mal tapé ou mauvais environnement.	Vérifiez le nom de l’en-tête (app-key, avec trait d’union, en minuscules) et que le préfixe correspond à l’URL de base.
400 avec 1104 INVALID_PHONE_NUMBER	Une des entrées de to n’est pas au format E.164.	Validez chaque entrée contre ^\+?\d{1,15}$ avant envoi.
400 avec 1109 MISSING_REQUIRED_FIELD	to ou message manque ou est vide.	Les deux champs sont obligatoires ; un tableau vide ne compte pas.
402 avec 1402 INSUFFICIENT_BALANCE	Votre compte n’a pas assez de crédit.	Rechargez via le tableau de bord Bloonio.
429 avec 1301 RATE_LIMIT_EXCEEDED	Plus que le plafond par minute.	Respectez Retry-After. Voir Limites de débit.

La liste complète des codes est dans le catalogue d’erreurs.

Voir aussi

• Envoyer un SMS instantané — patterns multi-destinataires
• Planifier un SMS — ajouter scheduled_dates
• Vérifier le statut — polling
• Présentation des webhooks — accusés asynchrones