Documentation de l'API

Introduction

Toutes les requêtes se font en HTTPS vers la base d'API. Les corps de requête et de réponse sont au format JSON (Content-Type: application/json). L'API suit les conventions REST : verbes HTTP standards, codes de statut explicites et ressources identifiées par un id.

URL de base

Authentification

Authentifiez chaque requête avec votre clé API secrète, transmise dans l'en-tête Authorization au format Bearer. Conservez la clé côté serveur ; ne l'exposez jamais dans un client web ou mobile.

Authorization: Bearer fm_live_xxxxxxxxxxxxxxxxxxxxxxxx

Une requête sans clé valide renvoie 401 Unauthorized. Vous pouvez générer, révoquer et faire tourner vos clés depuis le tableau de bord.

Environnements

Deux environnements isolés, chacun avec ses propres clés :

Quickstart

Envoyez votre premier SMS en une requête. Remplacez $FM_API_KEY par votre clé secrète.

curl https://api.fastermessage.com/v1/sms/send \
  -H "Authorization: Bearer $FM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+221770000000",
    "from": "FasterMsg",
    "text": "Votre code est 480912. Valable 5 min."
  }'

En-têtes recommandés

• Authorization — votre clé API (obligatoire) ;
• Content-Type: application/json — pour les requêtes avec corps ;
• Idempotency-Key — clé unique pour rejouer une requête sans double envoi.

Les horodatages sont au format ISO 8601 UTC (2026-06-27T12:44:01Z). Toute réponse de création renvoie un id et un status.

SMS — Envoyer

Envoie un SMS. Le champ fallback définit une cascade : si le SMS échoue, le message est réémis sur le canal suivant.

Paramètres du corps

curl https://api.fastermessage.com/v1/sms/send \
  -H "Authorization: Bearer $FM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+221770000000",
    "from": "FasterMsg",
    "text": "Votre code est 480912.",
    "fallback": ["whatsapp"]
  }'

{
  "id": "msg_8a1c2e",
  "channel": "sms",
  "status": "queued",
  "to": "+221770000000",
  "segments": 1,
  "created_at": "2026-06-27T12:44:01Z"
}

WhatsApp — Envoyer

Envoie un message WhatsApp. Hors fenêtre de 24 h, utilisez un template approuvé ; à l'intérieur, vous pouvez envoyer du texte de session.

curl https://api.fastermessage.com/v1/whatsapp/send \
  -H "Authorization: Bearer $FM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+221770000000",
    "template": {
      "name": "order_confirm",
      "language": "fr",
      "variables": ["Awa", "#1042"]
    }
  }'

Voix — Envoyer

Déclenche un appel automatisé. Fournissez un audio_url (fichier hébergé) ou un objet tts (synthèse vocale).

curl https://api.fastermessage.com/v1/voice/send \
  -H "Authorization: Bearer $FM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+221770000000",
    "tts": { "text": "Votre code est 4 8 0 9 1 2.", "language": "fr" },
    "fallback": ["sms"]
  }'

E-mail — Envoyer

Envoie un e-mail transactionnel ou marketing depuis une adresse d'expédition vérifiée (SPF/DKIM).

curl https://api.fastermessage.com/v1/email/send \
  -H "Authorization: Bearer $FM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "from": "[email protected]",
    "subject": "Votre reçu #1042",
    "html": "<h1>Merci !</h1>"
  }'

Statut d'un message

Renvoie l'état actuel et l'historique de statut d'un message à partir de son id.

{
  "id": "msg_8a1c2e",
  "channel": "sms",
  "status": "delivered",
  "to": "+221770000000",
  "created_at": "2026-06-27T12:44:01Z",
  "delivered_at": "2026-06-27T12:44:03Z"
}

Lister les messages

Renvoie une liste paginée de messages, triés du plus récent au plus ancien. La pagination se fait par curseur.

Paramètres de requête

{
  "object": "list",
  "has_more": true,
  "data": [
    { "id": "msg_8a1c2e", "status": "delivered" }
  ]
}

Solde du compte

Renvoie le solde disponible par canal (en unités).

{
  "sms": 7733,
  "whatsapp": 0,
  "email": 1250,
  "currency": "XOF"
}

Envoyer un OTP

Génère et envoie un code à usage unique. FasterMessage gère la génération, l'expiration et la validation : vous n'avez pas à stocker le code.

{
  "id": "vrf_3f9a01",
  "to": "+221770000000",
  "channel": "sms",
  "status": "pending",
  "expires_at": "2026-06-27T12:49:01Z"
}

Vérifier un OTP

Valide le code saisi par l'utilisateur. Le code est invalidé après une vérification réussie ou après expiration.

{ "to": "+221770000000", "code": "480912" }

{
  "id": "vrf_3f9a01",
  "status": "approved"
}

Un code erroné renvoie status: "failed" ; un code expiré renvoie une erreur 410 Gone.

Webhooks & DLR

Configurez une URL de webhook dans le tableau de bord (ou par message via callback_url) pour recevoir chaque changement d'état en temps réel. FasterMessage envoie une requête POST JSON à votre endpoint.

Exemple d'événement

{
  "id": "evt_55b7",
  "event": "message.delivered",
  "message_id": "msg_8a1c2e",
  "status": "delivered",
  "channel": "sms",
  "delivered_at": "2026-06-27T12:44:03Z"
}

Sécurité & bonnes pratiques

• Vérifiez la signature de chaque payload : en-tête X-Fastermessage-Signature, de la forme sha256=HMAC-SHA256(corps brut, votre secret de signature). Le secret se génère depuis votre espace, écran « Intégration & API » ;
• Répondez 2xx rapidement ; traitez en asynchrone ;
• Gérez l'idempotence : un même événement peut être livré plusieurs fois.

Statuts de message

Erreurs

L'API utilise les codes de statut HTTP standards. Le corps d'erreur précise un code machine et un message lisible.

{
  "error": {
    "code": "invalid_recipient",
    "message": "Le champ 'to' doit être au format E.164."
  }
}

Limites de débit

Les requêtes sont limitées par clé API. En cas de dépassement, l'API renvoie 429 avec un en-tête Retry-After indiquant le délai avant nouvelle tentative.

• X-RateLimit-Limit — quota sur la fenêtre courante ;
• X-RateLimit-Remaining — requêtes restantes ;
• Retry-After — secondes à attendre après un 429.

Les seuils exacts dépendent de votre plan — valeurs à préciser.

SDK

Des bibliothèques encapsulent l'authentification, les requêtes et la vérification de signature des webhooks. Le code source de chaque SDK est fourni dans le dépôt, dossier sdks/<langage>.

import { FasterMessage } from "fastermessage";
const fm = new FasterMessage(process.env.FM_API_KEY);
await fm.sms.send({ to: "+221770000000", from: "FasterMsg", text: "Votre code est 480912" });

use FasterMessage\Client;
$fm = new Client(getenv("FM_API_KEY"));
$fm->sms->send(["to" => "+221770000000", "from" => "FasterMsg", "text" => "Votre code est 480912"]);

from fastermessage import FasterMessage
fm = FasterMessage(os.environ["FM_API_KEY"])
fm.sms.send(to="+221770000000", sender="FasterMsg", text="Votre code est 480912")

Plugins CMS

Des extensions prêtes à l'emploi connectent votre boutique ou votre site à FasterMessage (notifications de commande, OTP au paiement, campagnes). Le code de chaque plugin est fourni dans plugins/<cms>.