Documentation API

Toute requête part de la même URL de base https://api.ng-messaging.com. Créez une clé API dans Développeurs → Clés API, puis envoyez un premier message. L'exemple utilise une clé de test : le message part réellement mais n'est jamais facturé.

curl https://api.ng-messaging.com/v1/messages \
  -H "X-NG-Api-Key: ngmsg_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+221771234567",
    "body": "Bonjour depuis NG Messaging"
  }'

La réponse est un 202 Accepted : le message est validé, débité (sauf clé de test) et mis en file avec le statut queued. L'envoi réel se fait ensuite ; suivez le statut par webhook ou avec GET /v1/messages/:id. Chaque réponse porte un en-tête X-Request-Id à communiquer au support.

Réponse à un SMS (clé de test, extrait : le champ unit_price_fcfa est omis) :

{
  "id": "8f6c1d9e-3a52-4b7f-9d21-5c0e7b44a1f0",
  "channel": "sms",
  "type": "simple",
  "destination": "+221771234567",
  "body": "Votre code est 482913",
  "status": "queued",
  "cost_fcfa": 0,
  "is_test": true,
  "gateway_message_id": null,
  "error_message": null,
  "error_code": null,
  "action_required": false,
  "correlation_id": null,
  "sender": "NG TECH",
  "country": "Senegal",
  "segments": 1,
  "encoding": "GSM-7",
  "scheduled_at": null,
  "sender_id": null,
  "created_at": "2026-10-23T10:00:00"
}

Réponse à un message WhatsApp (clé de test) :

{
  "id": "5d2b7c40-91e3-4a6f-8c1d-0b7e3f9a2c11",
  "channel": "whatsapp",
  "type": "simple",
  "destination": "+221771234567",
  "body": "Bonjour depuis NG Messaging",
  "status": "queued",
  "cost_fcfa": 0,
  "is_test": true,
  "gateway_message_id": null,
  "error_message": null,
  "error_code": null,
  "action_required": false,
  "correlation_id": null,
  "sender": null,
  "country": null,
  "segments": null,
  "encoding": null,
  "scheduled_at": null,
  "sender_id": null,
  "created_at": "2026-10-23T10:00:00"
}

cost_fcfa est le montant réellement débité : 0 avec une clé de test. Les champs sender, country, segments, encoding et unit_price_fcfa concernent le SMS (null en WhatsApp) ; sender_id indique le numéro WhatsApp utilisé. gateway_message_id vaut toujours null : l'identifiant à conserver et à communiquer au support est id.

Chaque requête porte votre clé dans l'en-tête X-NG-Api-Key. Une clé absente, mal formée, invalide ou révoquée reçoit 401.

X-NG-Api-Key: ngmsg_live_xxxxxxxxxxxxxxxx

Il n'y a pas d'URL distincte pour les tests : le préfixe de la clé suffit. La valeur complète d'une clé n'est affichée qu'une seule fois, à sa création. Ne la placez jamais dans un navigateur ou une application mobile : elle appartient à votre serveur.

Permissions

Une clé est créée avec une liste de permissions. Une requête sans la permission requise reçoit 403, avec le nom de la permission manquante.

Clé liée à une application

Une clé peut être rattachée à une application de votre organisation. Elle n'utilise alors que les numéros WhatsApp de cette application pour choisir l'expéditeur (voir Expéditeurs WhatsApp). Une clé sans rattachement peut employer tous les numéros de l'organisation.

Un seul endpoint envoie les messages WhatsApp et SMS. Le champ channel décide du reste, et la permission exigée sur la clé suit le canal (whatsapp:send ou sms:send).

curl https://api.ng-messaging.com/v1/messages \
  -H "X-NG-Api-Key: ngmsg_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+221771234567",
    "sender_id": "snd_ngtech",
    "body": "Bonjour depuis NG Messaging"
  }'

Envoyer un template WhatsApp

curl https://api.ng-messaging.com/v1/messages \
  -H "X-NG-Api-Key: ngmsg_live_xxx" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+221771234567",
    "sender_id": "snd_ngtech",
    "type": "template",
    "template": { "name": "order_confirmed", "language": "fr", "variables": ["Aïda", "ORD-1042"] }
  }'

Programmer un SMS

Le SMS est débité tout de suite et reste au statut scheduled jusqu'à l'heure prévue. Tant qu'il n'est pas parti, vous pouvez l'annuler avec POST /v1/messages/:id/cancel (permission sms:send) : il passe à cancelled et son débit est remboursé. Si le message est déjà transmis ou en cours d'envoi, la réponse est 409.

curl https://api.ng-messaging.com/v1/messages \
  -H "X-NG-Api-Key: ngmsg_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+221771234567",
    "body": "Rappel : votre rendez-vous est demain à 10 h.",
    "scheduled_at": "2026-11-02T08:00:00Z"
  }'

Longueur et segments SMS

Un SMS en alphabet GSM-7 tient dans un segment jusqu'à 160 caractères, puis 153 caractères par segment. Un seul caractère hors GSM-7 (emoji, certains accents) bascule tout le message en UCS-2 : 70 caractères pour un segment, puis 67. Le coût suit le nombre de segments. Avec la signature NG TECH, le nom de votre entreprise est ajouté en tête du message et compte dans la longueur. POST /v1/sms/estimate (permission sms:send, champs to, message, sender) renvoie le nombre de segments, l'encodage et le coût sans rien débiter ni envoyer.

Lire un message

Renvoie le message et sa chronologie (timeline), horodatée. En cas d'échec, error_code et error_message portent le code et le message publics ; action_required vaut true quand rien ne se résoudra sans une action de votre part. Un identifiant inconnu reçoit 404.

{
  "id": "8f6c1d9e-3a52-4b7f-9d21-5c0e7b44a1f0",
  "channel": "sms",
  "status": "delivered",
  "...": "(les champs de la réponse d'envoi)",
  "timeline": [
    { "status": "queued", "at": "2026-10-23T10:00:00" },
    { "status": "sent", "at": "2026-10-23T10:00:02" },
    { "status": "delivered", "at": "2026-10-23T10:00:05" }
  ]
}

Liste paginée : paramètres channel, status, page (1 par défaut) et limit (50 par défaut, 200 au maximum). La réponse contient items et total.

Une organisation peut avoir plusieurs numéros WhatsApp. Chacun est identifié publiquement par un sender_id (snd_…). Le numéro mutualisé de NG TECH, quand votre organisation y a droit, a toujours l'identifiant snd_ngtech.

{
  "senders": [
    { "sender_id": "snd_8c41f0a2", "type": "own", "phone_number": "+221770000000",
      "display_name": "Ma Boutique", "status": "active", "is_default": true },
    { "sender_id": "snd_ngtech", "type": "ngtech", "phone_number": null,
      "display_name": "NG TECH", "status": "active", "is_default": false }
  ]
}

Règle de sélection

En WhatsApp, l'expéditeur est choisi dans cet ordre :

1. Le sender_id de la requête, s'il appartient à votre organisation et est actif (ou snd_ngtech si l'organisation y a droit). Sinon 404 sender_not_found ou 409 sender_unavailable.
2. Sinon l'expéditeur par défaut de l'organisation, s'il est défini. Défini mais inactif : 409 sender_unavailable, sans repli.
3. Sinon l'unique numéro actif de l'organisation.
4. Sinon, plusieurs numéros actifs : 400 sender_required. Précisez sender_id ou définissez un expéditeur par défaut.
5. Sinon, aucun numéro à vous n'est actif : le numéro NG TECH est utilisé si votre organisation y a droit.

Le message renvoyé indique l'expéditeur réellement utilisé dans sender_id. Sur le numéro NG TECH, le destinataire voit NG TECH comme expéditeur : le texte libre est donc précédé du nom de votre entreprise. Pour le SMS, la signature se choisit avec le champ sender.

WhatsApp n'autorise un texte libre que dans les 24 heures qui suivent le dernier message reçu du destinataire sur ce numéro. Chaque message entrant rouvre une fenêtre de 24 heures ; vous êtes prévenu par l'événement message.received.

Sur le numéro mutualisé NG TECH, un message reçu est attribué à l'organisation qui a envoyé le dernier message sortant à ce destinataire depuis ce numéro, dans les 30 derniers jours. La fenêtre n'est ouverte que pour cette organisation.

Règles

• La progression normale est queued, processing, sent, delivered, read. Un accusé tardif n'écrase jamais un statut plus avancé : un sent reçu après delivered est ignoré.
• « Livré » l'emporte : un échec signalé après delivered ou read est ignoré et ne donne lieu à aucun remboursement.
• Un failed est remboursé, une seule fois. Si un accusé delivered arrive ensuite, le statut redevient delivered et l'erreur disparaît, sans nouveau débit.
• Un message unknown n'est pas remboursé tant que son issue n'est pas connue : un accusé failed ultérieur le rembourse, un accusé delivered ou read le laisse facturé. Un message que le réseau n'a pas pu remettre dans le délai passe à failed avec le code message_expired (remboursé).
• Les statuts scheduled et cancelled ne sont modifiés par aucun accusé du réseau.

Le SMS ne remonte pas read. Pour suivre un message, abonnez-vous aux webhooks message.sent, message.delivered, message.read et message.failed, ou interrogez GET /v1/messages/:id.

WhatsApp exige un template approuvé par Meta pour écrire en premier à un contact ou hors de la fenêtre de 24 h. Créez-le ici ou depuis Messagerie → Templates, attendez la décision de Meta (le délai est fixé par Meta ; vous êtes prévenu par les événements template.approved et template.rejected), puis envoyez-le avec POST /v1/messages. Tous les endpoints ci-dessous exigent la permission whatsapp:send.

curl https://api.ng-messaging.com/v1/templates \
  -H "X-NG-Api-Key: ngmsg_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_confirmed",
    "language": "fr",
    "category": "UTILITY",
    "body": "Bonjour {{1}}, votre commande {{2}} est confirmée. Merci de votre confiance.",
    "example": "Bonjour Aïda, votre commande ORD-1042 est confirmée. Merci de votre confiance."
  }'

Réponse (le champ status vaut ensuite approved, rejected, paused, disabled ou deleted) :

{
  "id": "…",
  "name": "order_confirmed",
  "language": "fr",
  "category": "UTILITY",
  "status": "pending",
  "body": "Bonjour {{1}}, votre commande {{2}} est confirmée. Merci de votre confiance.",
  "rejection_reason": null
}

Templates du numéro NG TECH

Sur le numéro NG TECH (sender_id snd_ngtech), les templates forment un catalogue commun, activé pour votre organisation par NG Messaging. Vous ne pouvez ni les créer, ni les modifier, ni les supprimer : POST /v1/templates, DELETE et sync reçoivent 403. GET /v1/templates?sender_id=snd_ngtech liste ceux qui vous sont ouverts. Envoyer un template qui ne l'est pas donne 403 ngtech_template_not_allowed, et un pays non autorisé pour ce template 400 ngtech_country_not_allowed. Pour créer vos propres templates, connectez votre propre numéro WhatsApp.

NG Messaging génère le code, l'envoie et le vérifie : votre application ne manipule qu'un identifiant de demande, request_id. Le code n'est jamais renvoyé par l'API et n'est conservé que sous forme d'empreinte. Les deux endpoints exigent la permission otp:send.

Une valeur hors bornes est refusée en 400 avec le nom du champ et l'intervalle : elle n'est jamais corrigée en silence. Le canal auto choisit WhatsApp quand un numéro est utilisable et qu'un template d'authentification approuvé existe, et le SMS sinon. Avec une clé de test, le canal auto choisit le SMS. Par SMS, le message est composé par NG Messaging.

curl https://api.ng-messaging.com/v1/otp \
  -H "X-NG-Api-Key: ngmsg_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+221771234567", "channel": "auto" }'

Réponse (avec une clé de test, cost_fcfa vaut 0) :

{
  "request_id": "otp_3f8a1c92b7d4e6f0",
  "message_id": "9594319d-55ab-4a38-b921-34cda240e701",
  "status": "queued",
  "expires_at": "2026-10-23T10:10:00",
  "cost_fcfa": 0
}

curl https://api.ng-messaging.com/v1/otp/verify \
  -H "X-NG-Api-Key: ngmsg_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "request_id": "otp_3f8a1c92b7d4e6f0", "code": "438210" }'

Réponse 200 :

{
  "id": "…",
  "request_id": "otp_3f8a1c92b7d4e6f0",
  "phone_number": "+221771234567",
  "status": "verified",
  "attempts": 1,
  "max_attempts": 5,
  "expires_at": "2026-10-23T10:10:00",
  "verified_at": "2026-10-23T10:01:12",
  "message_id": "9594319d-55ab-4a38-b921-34cda240e701",
  "created_at": "2026-10-23T10:00:00"
}

Antifraude

Avant tout envoi et tout débit, NG Messaging applique des limites contre le détournement des codes. Un refus est une réponse 429, avec un en-tête Retry-After (en secondes) quand une attente a un sens, et un corps contenant error, message et retry_after. Aucun message n'est créé et rien n'est débité.

Les seuils exacts sont fixés par NG Messaging et peuvent être ajustés pour votre organisation sur demande au support.

Configurez une URL HTTPS depuis Développeurs → Webhooks et choisissez les événements auxquels vous vous abonnez : un événement non coché n'est jamais envoyé. Le secret de l'endpoint (préfixe ngwhsec_) sert à vérifier la signature ; il se renouvelle depuis la même page. L'URL ne doit pas pointer vers un réseau interne et les redirections ne sont pas suivies.

Événements

Forme de la requête

Chaque livraison est un POST JSON dont data dépend de l'événement. Pour les événements message.*, data.message_id est l'identifiant renvoyé par l'envoi, et error_code / error_message ne sont renseignés qu'en cas d'échec (avec en plus error et errors).

{
  "id": "evt_6b79e8b422f9432e",
  "event_type": "message.delivered",
  "source": "ng_messaging",
  "version": "1.0",
  "company_id": "0e5ad9db-a30e-45e7-a69d-6daa476961a0",
  "occurred_at": "2026-10-23T10:00:05.103787Z",
  "received_at": "2026-10-23T10:00:05.103787Z",
  "correlation_id": "corr_61d340fcddac42ca",
  "data": {
    "message_id": "9594319d-55ab-4a38-b921-34cda240e701",
    "channel": "whatsapp",
    "to": "221771234567",
    "status": "delivered",
    "correlation_id": "7c9eb28e-8055-40a0-bd01-c9615cfa1d85",
    "error_code": null,
    "error_message": null,
    "timestamp": "2026-10-23T10:00:05.103787Z"
  }
}

En-têtes et signature

La signature est le HMAC-SHA256, avec le secret de l'endpoint comme clé, de {timestamp}.{corps brut}. Calculez-la sur les octets reçus, avant tout décodage JSON, et refusez les horodatages trop anciens.

import crypto from "node:crypto"
import express from "express"

const app = express()

// Le corps BRUT est indispensable : ne le passez pas par express.json() avant la vérification.
app.post("/webhooks/ng-messaging", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.header("X-NG-Timestamp") ?? ""
  const signature = req.header("X-NG-Signature") ?? ""

  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.sendStatus(400)

  const attendu =
    "sha256=" +
    crypto
      .createHmac("sha256", process.env.NG_WEBHOOK_SECRET)
      .update(Buffer.concat([Buffer.from(timestamp + "."), req.body]))
      .digest("hex")

  const a = Buffer.from(attendu)
  const b = Buffer.from(signature)
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401)

  res.sendStatus(200) // accusez réception d'abord, traitez ensuite
  const event = JSON.parse(req.body.toString("utf8"))
  // dédoublonnez sur req.header("X-NG-Event-Id") puis traitez event.event_type
})

import hashlib
import hmac
import time

def verifier(secret: str, timestamp: str, signature: str, raw_body: bytes) -> bool:
    # Refuser un horodatage trop ancien : protège du rejeu d'un appel intercepté.
    if abs(time.time() - int(timestamp)) > 300:
        return False
    message = timestamp.encode() + b"." + raw_body
    attendu = "sha256=" + hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(attendu, signature)

Réponses, reprises et rejeu

Répondez par un code 2xx en moins de 8 secondes puis traitez l'événement. Toute autre réponse, ou une erreur réseau, est un échec : NG Messaging retente après 30 secondes, 2 minutes, 10 minutes, 1 heure puis 6 heures, soit 6 tentatives au total. Ensuite la livraison passe à l'état dead et reste consultable. Un même événement peut arriver plusieurs fois : dédoublonnez sur X-NG-Event-Id. Un échec de webhook n'affecte jamais l'envoi du message qui l'a déclenché.

Journal des livraisons, les plus récentes d'abord. Paramètres : status (pending, delivered ou dead) et limit (50 par défaut, 200 au maximum). Chaque entrée porte id, event_id, event_type, status, attempts, last_http_status, last_error, next_attempt_at et delivered_at.

Rejoue une livraison avec un compteur de tentatives remis à zéro. Une livraison inconnue reçoit 404, et une livraison déjà réussie 409.

Une clé d'idempotence garantit qu'une même opération métier crée un seul message et un seul débit, même si votre code réessaie après un délai d'attente. Elle s'applique à tous les envois : messages, templates et OTP. Transmettez-la dans l'en-tête Idempotency-Key ou dans le champ idempotency_key du corps.

• Rejouer la même clé ne renvoie pas d'erreur : l'API retourne le message déjà créé, sans rien renvoyer ni débiter de nouveau.
• En-tête et corps fournis ensemble avec deux valeurs différentes : 400 idempotency_key_mismatch.
• Un message refusé faute de solde (402) ne réserve pas sa clé : après avoir rechargé, vous pouvez réessayer avec la même.
• Pour un OTP, la clé détermine le request_id quand vous n'en fournissez pas : un rejeu ne renvoie pas de nouveau code.

Choisissez un identifiant stable et propre à l'opération (un numéro de commande), pas un horodatage.

Toute erreur de l'API a le même corps JSON : detail (chaîne, objet ou liste, selon l'erreur), error (code stable sur lequel brancher votre code), message (texte lisible, en français) et request_id. Ce dernier est aussi renvoyé dans l'en-tête X-Request-Id : communiquez-le au support.

{
  "detail": "Hors fenêtre de 24 h : ce destinataire ne vous a pas écrit récemment. Utilisez un template approuvé.",
  "error": "service_window_closed",
  "message": "Hors fenêtre de 24 h : ce destinataire ne vous a pas écrit récemment. Utilisez un template approuvé.",
  "request_id": "3f9a0c7e41b84d2e9a1c5f60"
}

Solde insuffisant (402)

Un solde insuffisant est une réponse 402 avec le code insufficient_balance. Selon le circuit, detail est un objet qui donne le montant requis et le solde disponible, ou une chaîne.

{
  "detail": { "error": "insufficient_balance", "required": 15, "available": 4 },
  "error": "insufficient_balance",
  "message": "Solde insuffisant.",
  "request_id": "3f9a0c7e41b84d2e9a1c5f60"
}

Codes par statut HTTP

Quand une erreur n'a pas de code public propre, error reprend le code de son statut HTTP :

Codes publics

Ces codes décrivent un refus de votre requête (colonne HTTP renseignée) ou l'échec d'un message après la réponse 202. Dans ce second cas, vous les lisez dans error_code et error_message sur GET /v1/messages/:id et dans l'événement message.failed ; le statut HTTP ne s'applique pas. Le message est toujours celui du tableau, jamais un texte brut d'un tiers. Un code absent du tableau doit être traité comme messaging_temporarily_unavailable.

Codes Meta normalisés

Ces codes en majuscules concernent votre compte WhatsApp Business. action_required vaut true sur le message quand aucun réessai ne servira tant que vous n'avez rien changé.

Autres codes

Voici ce que l'API applique. Les valeurs par défaut peuvent être ajustées pour votre organisation par NG Messaging.

Indépendamment de NG Messaging, Meta applique ses propres limites à chaque numéro WhatsApp : palier d'envoi, note de qualité, cadence. Un envoi trop rapide donne le code RATE_LIMIT_HIT.

Les tarifs dépendent du canal, de la destination et de la catégorie. La grille en vigueur est publiée sur la page Tarifs ; elle est aussi lisible sans clé avec GET /v1/billing/message-pricing. Aucun prix n'est donné ici pour ne jamais diverger de la facturation.

• Montant débité. Le coût de chaque message est fixé à l'acceptation et renvoyé dans cost_fcfa ; il vaut 0 avec une clé de test. Un message en échec est remboursé.
• SMS. Le prix suit le pays et le nombre de segments (voir Longueur et segments SMS). La signature utilisée compte aussi : NG TECH ou la signature approuvée de votre compte. POST /v1/sms/estimate donne le devis exact sans rien débiter.
• WhatsApp. Le prix suit la catégorie du message :

La catégorie d'un template est celle que Meta lui attribue, pas celle que vous espérez : déclarer un message promotionnel comme utility conduit Meta à le reclasser. Le tarif appliqué suit la catégorie réelle.