Module · Lot 1
BRAX API
L'accès programmatique à WhatsApp Business pensé pour les intégrateurs : une API REST prévisible, des webhooks fiables, des erreurs typées et une documentation exacte.
Un point d'entrée, tous les types de message
Une seule route POST /v1/messages pour le texte, les modèles, les médias, les boutons et les listes. Les erreurs sont typées, les clés d'idempotence empêchent le double envoi, et chaque réponse porte un identifiant de requête que le support retrouve dans les journaux.
- ✓Clés d'API distinctes en test et en production
- ✓Webhooks signés, réessayés sur 24 heures, rejouables
- ✓Modèles créés, soumis et suivis depuis l'API
- ✓Journal de requêtes consultable, secrets masqués
- Pour qui
- Développeur, éditeur de logiciel
- Facturation
- Par connexion
- Lot
- Lot 1
- État
- Disponible
POST /v1/messages Authorization: Bearer bx_live_… Idempotency-Key: cmd-8842-a1 { "connectionId": "cnx_01H9Z…", "to": "2250749050405", "template": { "name": "notif_commande", "language": "fr" } } 201 Created · status: accepted
Un point de terminaison pour tous les messages
Le corps d'un envoi comporte connectionId, to, puis exactement un champ de contenu. Cette conception évite la multiplication de routes et facilite l'évolution : un nouveau type de message n'ajoute pas de point de terminaison.
| Champ de contenu | Usage | Contraintes principales |
|---|---|---|
| template | Modèle approuvé | Seul type autorisé hors fenêtre de service |
| text | Texte libre | Fenêtre ouverte requise · 4 096 caractères |
| image · video · audio | Médias | JPEG/PNG 5 Mo · MP4 16 Mo · audio 16 Mo |
| document | Fichier | 100 Mo · nom de fichier obligatoire |
| buttons · list · cta | Interactif | 3 boutons · 10 sections · appel à l'action vers une URL |
| location · contacts · reaction | Divers | Position, fiche vCard, emoji sur un message cible |
Clés d'API et sécurité
- ✓Préfixe explicite : bx_live_ en production, bx_test_ en environnement de test
- ✓La clé complète n'est affichée qu'une fois ; seuls le préfixe et les quatre derniers caractères sont conservés en clair
- ✓Secret stocké haché, jamais réversible
- ✓Portée à l'organisation entière ou restreinte à une seule entreprise connectée
- ✓Libellé, date de création, dernière utilisation, révocation immédiate, expiration optionnelle avec alerte 15 jours avant
Modèles de messages
Création, soumission et suivi du statut (en attente, approuvé, rejeté, désactivé, en pause). Le statut est mis à jour par webhook entrant, pas par sondage. Le formulaire s'adapte à la catégorie : en authentification, pas de champ de corps libre, seulement des cases à cocher. Le motif de rejet de Meta est restitué tel quel.
- ✓POST /v1/templates — création et soumission, tableau components accepté tel quel
- ✓GET /v1/templates — liste filtrable par entreprise, statut, catégorie, langue
- ✓GET /v1/templates/{id} — détail, avec motif de rejet
- ✓DELETE /v1/templates/{id} — suppression
Fenêtre de service, quotas et idempotence
- ✓L'état de la fenêtre de 24 h est évalué localement : un envoi libre hors fenêtre est rejeté en 409 (service_window_closed) avant tout appel au transport
- ✓Le quota de l'abonnement est vérifié avant émission : dépassement en 402 (plan_limit_messages)
- ✓Tout point de terminaison de création accepte un en-tête Idempotency-Key ; une clé déjà vue renvoie la réponse d'origine pendant au moins 24 heures
- ✓Pagination par curseur exclusivement, jamais par décalage
- ✓Limitation de débit avec en-têtes X-RateLimit-Limit / Remaining / Reset ; l'envoi de messages est mis en file plutôt que rejeté
Webhooks sortants
Chaque livraison est signée par condensé HMAC-SHA256 sur le corps brut, avec horodatage pour prévenir le rejeu (en-tête X-Brax-Signature). Les réessais suivent une progression exponentielle sur au moins 24 heures ; un endpoint en échec durable est désactivé avec notification. Chaque événement porte un identifiant unique pour permettre la déduplication, et chaque livraison est rejouable depuis l'interface.
| Événement | Déclencheur |
|---|---|
| message.received | Message entrant d'un contact |
| message.status.updated | Passage à émis, livré, lu ou échoué |
| conversation.opened · assigned · resolved | Cycle de vie d'une conversation |
| template.status.updated | Approbation, rejet ou désactivation par Meta |
| campaign.completed | Fin d'exécution d'une campagne |
| contact.unsubscribed | Désinscription détectée |
| connection.quality.changed | Changement de note de qualité ou de palier |
| conversion.recorded | Enregistrement d'un événement de conversion |
Journal des requêtes
Chaque appel est journalisé et consultable depuis l'interface : identifiant de requête (X-Request-Id) servant de référence au support, durée de traitement, méthode, chemin, statut. Les corps de requête et de réponse sont conservés pour les erreurs, secrets et jetons masqués à l'écriture. La rétention suit le palier d'abonnement : 7, 30, 90 ou 365 jours.
Questions fréquentes
Sur BRAX API en particulier. Les questions générales sont sur la page d'accueil.
Puis-je tout faire par l'API ?
Oui. Tout ce que propose l'interface graphique est faisable par l'API : c'est une exigence de conception. L'interface ne fait qu'appeler les mêmes routes.
Comment tester sans envoyer de vrais messages ?
Avec une clé bx_test_ et un environnement isolé. Un numéro de test Meta permet un aller-retour complet, sans facturation.
Que se passe-t-il si mon serveur de webhooks tombe ?
Les livraisons sont réessayées en progression exponentielle sur au moins 24 heures, puis l'endpoint est désactivé avec notification. Chaque livraison reste rejouable depuis l'interface.
Prêt à essayer BRAX API ?
Créez un compte, connectez un premier numéro et testez le module en conditions réelles. Quatorze jours d'essai, sans carte, paiement en mobile money.