Connecter votre logiciel à WhatsApp

La gestion des API, c’est la façon dont un autre système — votre logiciel de facturation, votre boutique en ligne, votre propre backend — envoie des messages WhatsApp via WizMessage. Vous lui délivrez ici une clé API, vous lui indiquez quel modèle WhatsApp approuvé il a le droit d’envoyer, et vous le reliez à un webhook pour que les réponses vous reviennent. Ce guide parcourt tout le chemin, puis documente l’API REST que vos développeurs appelleront.

Le tableau de bord

Où se trouvent vos clés API

Toutes les clés que vous avez délivrées apparaissent ici, sous « API Keys ». Chaque ligne indique le statut de la clé, son préfixe public (la seule partie de la clé qui vous sera encore affichée après sa création) et le nombre d’appels qu’elle a effectués aujourd’hui. « Manage » ouvre la clé ; l’interrupteur la met en pause sans la supprimer.

1. ▶ Où se trouvent vos clés API
2. ▶ Une clé qui n’est pas encore terminée

Une clé qui n’est pas encore terminée

Une clé à laquelle aucun modèle n’est associé porte le badge « Needs setup ». Elle peut s’authentifier, mais elle ne peut pas envoyer de message modèle tant que vous n’en avez pas associé un — une intégration à moitié configurée se repère donc d’un coup d’œil, au lieu d’échouer plus tard au moment de l’envoi.

Configuration guidée

Étape 1 — Que connectez-vous ?

« Connect your software » ouvre un assistant en quatre étapes. Commencez par donner à la clé le nom du système qui l’utilisera, puis choisissez le préréglage correspondant. Les préréglages se contentent de suggérer des noms de champs pertinents — la facturation propose invoice_number, amount, due_date, customer_name — ils ne limitent en rien ce que vous pouvez associer.

1. ▶ Étape 1 — Que connectez-vous ?
2. ▶ Étape 2 — Choisir le message
3. ▶ Étape 3 — Où envoyer les réponses ?
4. ▶ Étape 4 — Passer en production

Étape 2 — Choisir le message

Choisissez l’un de vos modèles WhatsApp approuvés. Les modèles sont hébergés chez Meta, pas ici — cette liste est récupérée en direct depuis votre compte WhatsApp connecté, et seuls les modèles APPROUVÉS peuvent être envoyés. Cette étape est facultative : ignorez-la si la clé n’envoie jamais que du texte brut, et associez un modèle plus tard.

Étape 3 — Où envoyer les réponses ?

Lorsqu’une personne répond à votre message, ou qu’un rapport de livraison nous revient, nous l’envoyons en POST à une URL que vous contrôlez. Laissez cette option désactivée si votre système ne fait jamais qu’envoyer. Vous pourrez l’ajouter plus tard depuis l’onglet « Webhooks » de la clé — rien n’est définitif ici.

Étape 4 — Passer en production

C’est en appuyant sur « Next » à l’étape précédente que la clé est réellement créée — cet écran n’en est que la confirmation. Copiez dès maintenant les trois valeurs : la clé API, le secret d’API et le secret de signature du webhook ne sont affichés qu’une seule fois et ne peuvent plus être récupérés ensuite. Si vous perdez le secret, vous devrez le renouveler, ce qui implique de mettre à jour le système qui l’utilisait.

Gérer une clé

Vue d’ensemble

L’ouverture d’une clé donne sur l’onglet « Overview » : ce qu’elle est autorisée à faire, l’intensité de son utilisation et les points de terminaison qu’elle peut appeler. Les compteurs d’utilisation sont lus dans le journal des requêtes : ils reflètent donc le trafic réel.

1. ▶ Vue d’ensemble

Une clé qui reste à configurer

Une clé sans modèle associé s’ouvre à la place sur un onglet « Setup » — le même assistant, intégré. Notez que les onglets diffèrent de la capture précédente : tant qu’une clé n’a pas au moins un modèle, les onglets « Templates » et « Webhooks » ne sont pas proposés, car ils n’auraient encore rien sur quoi agir.

1. ▶ Une clé qui reste à configurer

Modèles

Dans l’onglet « Templates », chaque carte correspond à un modèle que cette clé peut envoyer. Le corps du texte est le message tel qu’il a été approuvé chez Meta, et les étiquettes en dessous sont les noms des variables que votre système fournira. « Try it » envoie un test, « Get code » génère une requête prête à l’emploi dans huit langages.

1. ▶ Modèles
2. ▶ Lire les variables — le point qui mérite qu’on s’y attarde

Lire les variables — le point qui mérite qu’on s’y attarde

Regardez la carte payment_failed_alert. Son message enchaîne {{1}}, puis {{3}}, puis {{2}} — dans le texte, les espaces réservés ne sont PAS dans l’ordre numérique. Les étiquettes en dessous, elles, sont listées dans l’ordre numérique : customer_name remplit {{1}}, renewal_date remplit {{2}}, plan_name remplit {{3}}. Faites correspondre vos valeurs au NUMÉRO, jamais à l’ordre dans lequel les espaces réservés apparaissent dans la phrase. C’est le piège le plus fréquent avec les modèles traduits, où l’ordre des mots déplace les espaces réservés.

Les trois boutons de chaque modèle

« Try it » — envoyer un test sans écrire une ligne de code

Le bouton en forme d’avion en papier ouvre ce modèle prérempli avec des valeurs d’exemple, une par nom de variable. C’est le moyen le plus rapide de vérifier qu’une association est correcte avant que vos développeurs n’y touchent. Notez l’interrupteur : « Simulate Only » est la valeur par défaut et rien ne sort de la maison — le serveur vous renvoie votre charge utile telle quelle. Basculez-le sur « Send Real Message » et un vrai message WhatsApp part vers le numéro indiqué, et il est facturé.

1. ▶ « Try it » — envoyer un test sans écrire une ligne de code
2. ▶ Ce que vous renvoie un envoi simulé
3. ▶ « Get code » — la requête, écrite pour vous
4. ▶ Changer de langage
5. ▶ « Edit » — modifier ce que votre système envoie
6. ▶ Test API — le même outil, n’importe quel point de terminaison
7. ▶ Webhooks — recevoir les réponses

Ce que vous renvoie un envoi simulé

Appuyer sur « Send Request » en mode « Simulate Only » renvoie la requête telle que la plateforme l’a reçue, avec le statut HTTP et le temps d’aller-retour. Voyez-y une vérification de forme, pas une répétition générale : cela confirme que votre JSON a été analysé et que la clé a été acceptée, mais cela ne valide PAS vos noms de variables face à l’association, et Meta n’est jamais contacté. Une charge utile qui se simule proprement peut tout de même être rejetée pour de vrai. Pour prouver l’association elle-même, activez « Send Real Message » et envoyez sur votre propre téléphone.

« Get code » — la requête, écrite pour vous

Le bouton en chevrons génère une requête fonctionnelle pour ce modèle précis dans huit langages : cURL, JavaScript, Node.js, Python, PHP, Ruby, Go et C#. Transmettez-la à la personne qui écrit l’intégration. Les variables apparaissent sous forme de {{placeholders}} nommés d’après votre association, et les identifiants restent sous la forme YOUR_API_KEY / YOUR_API_SECRET — cette boîte de dialogue n’affiche jamais votre vraie clé, l’extrait peut donc être collé sans risque dans un ticket.

Changer de langage

Cliquez sur n’importe quel langage en haut et l’extrait est réécrit pour lui — le même appel, les mêmes en-têtes, le client HTTP de ce langage. Chacun est généré au premier clic : un bref indicateur de chargement lors du premier changement est donc normal. « Copy » reprend l’extrait tel qu’il s’affiche : il est complet, imports compris, et si cette clé exige des signatures, l’étape de signature y figure déjà.

« Edit » — modifier ce que votre système envoie

Le crayon ouvre l’association elle-même. La maquette de téléphone en haut est le message réel avec vos noms actuels substitués : vous voyez donc ce que le client lira. En dessous, chaque variable détectée peut être renommée, réordonnée, marquée comme obligatoire ou typée — une date, un montant, une image. Renommer une variable la renomme aussi dans votre charge utile d’API : un système qui envoie déjà l’ancien nom se mettra donc à échouer. Changez les deux ensemble.

Test API — le même outil, n’importe quel point de terminaison

« Test API », en haut de l’onglet, c’est « Try it » sans le verrou du modèle : choisissez l’un des trois points de terminaison d’envoi, changez de modèle depuis la seconde liste déroulante et modifiez le corps librement. Utilisez-le pour vérifier les appels bruts /messages/text ou /messages/template, qui n’ont pas de carte propre parce qu’ils ne sont liés à aucune association. Notez que les variables de ce modèle s’appellent encore body_1, body_2, body_3 — voilà à quoi ressemble un modèle non associé, et c’est précisément ce que « Edit » sert à corriger.

Réponses

Webhooks — recevoir les réponses

Envoyer ne représente que la moitié d’une intégration. Dirigez un webhook vers votre propre point de terminaison HTTPS et WizMessage y enverra en POST les messages entrants et les mises à jour de livraison. Le secret de signature n’est affiché qu’une fois, au moment de sa génération ; vérifiez-le à chaque livraison pour être certain que l’appel vient bien de nous.

Référence de l’API REST

Tout ce qui précède sert à configurer la clé. Voici ce que vos développeurs appellent réellement. L’URL de base est /api/v1/external. Chaque point de terminaison exige les en-têtes d’authentification ci-dessous et reste soumis aux limites de débit de la clé.

S’authentifier

Envoyez votre clé API à chaque requête. Si l’option « Require signature » est activée sur la clé, vous devez également signer la requête — et une clé sur laquelle elle est activée rejettera purement et simplement tout appel non signé.

Remarque : Les signatures ne sont exigées que lorsque require_signature est activé sur la clé. Si ce n’est pas le cas, la clé API suffit à elle seule pour envoyer des messages — c’est précisément pour cela que la clé est un secret, et non un identifiant. Traitez-la comme un mot de passe : elle n’est affichée qu’une fois, et quiconque la détient peut écrire à vos clients.

const crypto = require('node:crypto')

const body = JSON.stringify({ to: '+919876543210', message: 'Hello' })
const timestamp = Math.floor(Date.now() / 1000).toString()

const secretHash = crypto.createHash('sha256').update(API_SECRET).digest('hex')
const signature = crypto.createHmac('sha256', secretHash)
	.update(timestamp + '.' + body)
	.digest('hex')

await fetch('https://your-host/api/v1/external/messages/text', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
		'X-API-Key': API_KEY,
		'X-Timestamp': timestamp,
		'X-API-Signature': signature,
	},
	body,
})

Points de terminaison

Envoyer un modèle associé

Voici la charge utile qui va de pair avec l’onglet « Templates ». Vous envoyez les variables par NOM — les noms affichés sous forme d’étiquettes sur la carte du modèle — et la plateforme assemble les composants de Meta à votre place. C’est tout l’intérêt d’associer un modèle : votre logiciel de facturation n’a besoin de rien connaître du format de composants de Meta.

POST /api/v1/external/messages/template/send

{
	"to": "+919876543210",
	"template_name": "payment_failed_alert",
	"language": "en",
	"variables": {
		"customer_name": "Priya Sharma",
		"renewal_date": "12 Aug 2026",
		"plan_name": "Wiz Pro"
	},
	"reference": "invoice-2026-0817"
}

Remarque : Les noms des variables doivent correspondre exactement à l’association — un nom non reconnu est ignoré, et l’absence d’un nom obligatoire entraîne un rejet avec un 400. reference vous appartient : il vous est renvoyé sur les webhooks, ce qui vous permet de relier un rapport de livraison à un enregistrement de votre propre système.

Limites de débit

Chaque clé possède ses propres limites, visibles dans l’onglet « Overview » — 60 requêtes/minute et 1 000 messages/jour par défaut. Les réponses indiquent le quota restant : levez le pied quand il s’épuise plutôt que de réessayer en butant contre le mur.