Vérifier le statut d'un message

GET /status/{message_id} retourne l’état actuel d’un SMS précédemment soumis. Le paramètre de chemin est le message_id retourné par POST /send.

Requête

cURL

curl $BASE_URL/api/v1/lisoloo/sms-api/status/507f1f77bcf86cd799439011 \
  -H "app-key: $LISOLOO_API_KEY"

Python

r = requests.get(
    f"{API_URL}/status/{message_id}",
    headers={"app-key": API_KEY},
    timeout=10,
)
r.raise_for_status()
print(r.json())

JavaScript

const r = await fetch(`${API_URL}/status/${messageId}`, {
  headers: { "app-key": API_KEY },
});
console.log(await r.json());

PHP

$ch = curl_init("$apiUrl/status/$messageId");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["app-key: $apiKey"],
]);
echo curl_exec($ch);

Réponse

{
  "status_code": 200,
  "data": {
    "message_id":       "507f1f77bcf86cd799439011",
    "status":           "delivered",
    "total_recipients": 1,
    "delivered":        1,
    "failed":           0,
    "pending":          0,
    "created_at":       "2026-05-27T10:15:00Z",
    "updated_at":       "2026-05-27T10:15:08Z"
  }
}

Champ	Description
status	Statut agrégé sur tous les destinataires. Voir Cycle de vie pour l’enum complet.
total_recipients	Nombre de destinataires dans le tableau to d’origine (depuis OPS_SMS_MESSAGE.total_recipients).
delivered / failed / pending	Compteurs par état, dérivés des lignes OPS_SMS_MESSAGE_CONTACT sous-jacentes. pending inclut les contacts dans tout état non-terminal.
created_at	Quand POST /send a retourné.
updated_at	Dernier horodatage de changement d’état.

Pattern de polling

La bonne cadence dépend de la forme du trafic. Pour les flux interactifs (OTP, confirmations à destinataire unique), interrogez 3 fois puis abandonnez :

import time
import requests

def wait_for_delivery(message_id, max_attempts=3, delay=2):
    for _ in range(max_attempts):
        r = requests.get(f"{API_URL}/status/{message_id}", headers=HEADERS)
        data = r.json()["data"]
        if data["status"] in ("delivered", "failed"):
            return data
        time.sleep(delay)
    return data  # dernier état vu

Pour les flux en lot, passez aux webhooks — interroger 1 000 message_id brûle le budget de limite de débit.

N'interrogez les états terminaux que si vous y êtes obligé

Si vous avez des webhooks configurés, l’endpoint de statut est pour « j’ai perdu l’événement webhook, qu’est-il arrivé ? » — pas le signal primaire. Traitez-le comme un fallback, pas le défaut.

404 — message ID inconnu

HTTP/1.1 404 Not Found

{
  "detail": "Message not found"
}

Retourné quand :

• Le message_id n’existe pas.
• Le message_id appartient à un autre marchand — la recherche est bornée à votre sys_organization_id, donc les IDs cross-tenant apparaissent en 404 et ne fuitent jamais d’existence.

États terminaux mixtes entre destinataires

Un envoi multi-destinataires peut se terminer avec certains destinataires delivered et d’autres failed. Le champ status agrégé reflète la machine d’états au niveau du message (voir Cycle de vie) ; les compteurs delivered et failed donnent la répartition exacte.

Voir aussi

• Cycle de vie d’un message — diagramme d’états complet
• Présentation des webhooks — push au lieu de polling
• Erreurs — valeurs error_code sur les échecs par destinataire