Documentation API

CLI

Envoyez rapidement des messages WhatsApp, des e-mails et des messages planifiés depuis votre terminal avec notifml-cli.

npm i -g notifml-cli
notif init --key ntf_live_xxx --to +22370000000
notif me "Build failed on prod"
notif "Ship done"
notif send +22370000000 "Check ASAP"
notif run -- npm run build
notif balance
notif doctor
notif me --at "in 10m" "Check deploy"

Vos destinataires fréquents restent des alias locaux dans la configuration du terminal. Notif reste ainsi une API de notification légère, sans dupliquer les contacts et campagnes SMSV.

notif alias set boss +22370000000
notif send boss "Besoin de ton retour"
notif boss "Besoin de ton retour"
tail -n 30 error.log | notif me --title "Prod error"

Les développeurs peuvent consulter leur clé locale, leur compte, leur utilisation et leur solde sans ouvrir le tableau de bord.

notif whoami
notif key
notif key --show
notif balance --transactions
notif status ntf_msg_xxx
notif logs --limit 10

Exemple rapide

Envoyez votre premier message en une seule requête :

curl -X POST https://api.notif.ml/api/send \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890",
    "channel": "whatsapp",
    "message": "Your order #1234 is ready"
  }'

Paramètres de la requête

Exemples

Envoyer un média

{
  "to": "+1234567890",
  "channel": "whatsapp",
  "message": "Here's your invoice",
  "mediaUrl": "https://example.com/invoice.pdf",
  "caption": "Invoice #1234"
}

Envoyer un audio/une vidéo

{
  "to": "+1234567890",
  "channel": "whatsapp",
  "message": "Voice note",
  "mediaUrl": "https://example.com/audio.mp3"
}

Planifier un message

{
  "to": "+1234567890",
  "channel": "whatsapp",
  "message": "Reminder for tomorrow",
  "scheduledAt": "2026-03-05T14:30:00Z"
}

Envoi par lot

{
  "messages": [
    {
      "to": "+1234567890",
      "channel": "whatsapp",
      "message": "Hello #1"
    },
    {
      "to": "+22372830996",
      "channel": "whatsapp",
      "message": "Hello #2",
      "mediaUrl": "https://example.com/video.mp4"
    }
  ],
  "continueOnError": true
}

E-mail transactionnel

{
  "to": "customer@example.com",
  "channel": "email",
  "subject": "Your receipt",
  "message": "Thanks for your order — details inside."
}

Envoyer dans un groupe WhatsApp

{
  "to": "+22372830996",
  "groupId": "120363123456789@g.us",
  "channel": "whatsapp",
  "message": "Hello team! Meeting at 3pm"
}

Test en bac à sable

{
  "to": "+1234567890",
  "channel": "whatsapp",
  "message": "Integration test",
  "sandbox": true
}

Modèle prédéfini

{
  "to": "+1234567890",
  "channel": "whatsapp",
  "preset": "order_confirmed",
  "presetVariables": {
    "orderId": "A-1024",
    "customerName": "Awa"
  }
}

Anciens champs (template/buttons)

{
  "to": "+1234567890",
  "channel": "whatsapp",
  "message": "Your order is ready for pickup",
  "template": "order_ready",
  "buttons": [
    { "type": "reply", "text": "On my way" },
    { "type": "reply", "text": "Reschedule" }
  ]
}

Les anciens champs template / buttons sont acceptés pour la compatibilité ; préférez preset pour le contenu structuré.

Authentification

Utilisez votre clé API dans l’en-tête Authorization ou X-API-Key :

Groupes WhatsApp

Envoyez des messages aux groupes WhatsApp dont votre numéro connecté est membre.

{
  "success": true,
  "groups": [
    { "id": "120363123456789@g.us", "name": "Team Dev", "participants": 12, "isAdmin": true },
    { "id": "120363987654321@g.us", "name": "Marketing", "participants": 25, "isAdmin": false }
  ],
  "count": 2
}

Utilisez la valeur id de cette réponse comme groupId dans POST /api/send.

Points d’accès

Statistiques et journaux d’envoi

Même authentification que POST /api/send: X-API-Key: ntf_live_… ou Bearer, ou une session de tableau de bord authentifiée.

Mode bac à sable

Utilisez le bac à sable sans connecter WhatsApp/SMSV : aucun trafic opérateur, réponses prévisibles SANDBOX et événements webhook simulés facultatifs.

• JSON "sandbox": true
• En-tête X-Notif-Sandbox: 1
• Variable serveur NOTIF_SANDBOX=1 (global)

Les clés préfixées par ntf_test_ renvoient toujours la simulation historique TEST sans contacter SMSV ; le bac à sable complète ce fonctionnement pour les clés ntf_live_ .

Idempotence

Les relances sont sûres. Ajoutez une clé d’idempotence à POST /api/send et la première requête reçue crée le message ; les requêtes suivantes utilisant la même clé renvoient le message enregistré sans nouvel envoi.

• En-tête Idempotency-Key: <your-key> — recommandé.
• Ou le champ JSON "idempotencyKey". Si les deux sont présents, l’en-tête est prioritaire.
• Les espaces en début et fin de clé sont supprimés. Une clé vide ou composée d’espaces est ignorée et le message est envoyé normalement.

curl -X POST https://api.notif.ml/api/send \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: order-1234-confirmed" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+22370123456",
    "channel": "whatsapp",
    "message": "Your order #1234 is confirmed"
  }'

Réponse lors d’un rejeu

Un rejeu renvoie le message enregistré avec "deduplicated": true pour le distinguer d’un nouvel envoi. Le statut vaut 200, ou 409 si le message enregistré s’est terminé en FAILED. Un rejeu d’envoi planifié renvoie également 200 dans ce format, et non 202 de la requête initiale.

{
  "success": true,
  "messageId": "msg_...",
  "notifMessageId": "msg_...",
  "channel": "whatsapp",
  "to": "+22370123456",
  "status": "SENT",
  "deduplicated": true
}

Portée et durée de vie

• Les clés sont limitées à votre compte et ne peuvent pas entrer en conflit avec celles d’un autre client.
• La correspondance porte uniquement sur la clé, pas sur le destinataire, le canal ou le contenu. Réutiliser une clé avec un contenu différent renvoie le message initial sans nouvel envoi.
• Les clés n’expirent pas : une clé utilisée il y a plusieurs mois déduplique encore aujourd’hui. Utilisez une clé unique par événement.

Modèle recommandé

Dérivez la clé de l’événement concerné — identifiant de commande, facture ou événement — et du type de message, par exemple order-1234-confirmed. Ne générez pas un nouvel UUID à chaque tentative : un nouvel UUID lors d’une relance crée une nouvelle clé et un double envoi.

Sur POST /api/send/batch, une clé par élément idempotencyKey est utilisée telle quelle ; sinon, l’en-tête de requête Idempotency-Key reçoit le suffixe correspondant à l’index de l’élément (:0, :1, …), afin que chaque élément garde sa propre clé.

Limites de débit et HTTP 429

Lorsque le quota quotidien est dépassé, POST /api/send renvoie 429 avec messagesUsed, limit, et upgradeUrl.

Si votre compte a un plafond quotidien par destinataire, les envois au même téléphone/e-mail peuvent renvoyer 429 avec recipientLimit lorsque ce plafond est atteint.

Les limites et l’utilisation de votre offre sont également disponibles sur GET /api/me (cookie de session).

Webhooks

Enregistrez une valeur webhookUrl sur votre compte notif.ml. Une fois définie, notif.ml envoie les événements de livraison et de réception à votre URL HTTPS. L’appel authentifié GET /api/me renvoie l’URL actuelle ; contactez l’assistance ou utilisez votre accès administrateur pour la modifier tant que les réglages autonomes ne sont pas disponibles dans le tableau de bord.

{
  "event": "message.received",
  "messageId": "wamid.HBg...",
  "from": "+22370000000",
  "to": "+22372830996",
  "channel": "whatsapp",
  "type": "text",
  "text": "Bonjour",
  "timestamp": "2026-03-04T13:37:00.000Z"
}