Documentation API Notiwa

Adresse de base

https://notiwa.io/api/public/v1

Utilisez /api/public/v1 pour les appels externes : ce chemin ne nécessite pas de session Notiwa. L’alias /v1 fonctionne aussi lorsque le site publié est accessible publiquement.

Authentification

Envoyez Authorization: Bearer VOTRE_CLÉ_API. Chaque clé appartient à une organisation. Limite par défaut : 60 requêtes/minute, configurable à sa création ; POST et GET partagent cette limite. Une clé révoquée est immédiatement refusée.

Déclencher une notification

POST /v1/messages

Le contact doit déjà exister avec un opt-in enregistré. Le modèle doit être approuvé dans la langue demandée. Les variables sont un objet à clés numériques correspondant exactement à {{1}}, {{2}}… Aucun consentement n’est créé par l’API.

to

Téléphone E.164 d’un contact de votre organisation.

template

Nom exact d’un modèle utilitaire.

language

fr ou en.

variables

Valeurs texte par numéro de variable ; utilisez {} sans variable.

idempotency_key

Clé unique par organisation (200 caractères maximum). Une répétition retourne le même message, sans nouvel envoi.

scheduled_at

Optionnel : date ISO 8601 avec fuseau, au plus un an à l’avance.

curl 'https://notiwa.io/api/public/v1/messages' \
  -H "Authorization: Bearer $NOTIWA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"to":"+221771234567","template":"confirmation_commande","language":"fr","variables":{"1":"CMD-42"},"idempotency_key":"commande-CMD-42"}'

{ "id": "message-uuid", "status": "queued", "error_code": null }

Consulter le statut

GET /v1/messages/:id

Retourne uniquement un message de l’organisation de la clé. Un statut queued n’est pas une preuve de livraison ; les statuts sent, delivered et read proviennent de Meta. Un message invalide est enregistré comme skipped avec un error_code.

curl "https://notiwa.io/api/public/v1/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $NOTIWA_API_KEY"

Erreurs

401 : clé absente, invalide ou révoquée. 404 : contact, modèle ou message introuvable. 415 : JSON requis. 422 : champs invalides. 429 : limite atteinte, respectez Retry-After. 500 : erreur temporaire interne.

{ "error": { "code": "UNAUTHORIZED", "message": "Missing, invalid or revoked API key." } }

Recevoir les événements

Notiwa adresse un POST JSON à votre destination HTTPS. Vérifiez X-Notiwa-Signature = sha256=HMAC_SHA256(secret, timestamp + '.' + corps brut), avec X-Notiwa-Timestamp. Refusez les signatures invalides et les horodatages de plus de 5 minutes. Utilisez une comparaison en temps constant. Dédupliquez par X-Notiwa-Delivery et répondez 2xx après stockage durable.

message.sent · message.delivered · message.read · message.failed

{
  "id": "delivery-uuid",
  "event": "message.delivered",
  "created_at": "2026-10-25T12:00:00Z",
  "data": { "id": "message-uuid", "status": "delivered" }
}

Les livraisons sont reprises jusqu’à 5 tentatives, avec des délais de 1, 2, 4 et 8 minutes, à la prochaine vérification active. Des doublons peuvent arriver après un délai réseau. Les contrôles sont désactivés après vidage ; les événements en attente les réactivent.