Clés API et Client ID

Une clé API permet à vos propres logiciels, et à des outils comme Zapier, n8n, Make et le plugin WordPress, d'envoyer des messages WhatsApp depuis les numéros de votre espace de travail. Votre propre code envoie la clé dans un en-tête Authorization: Bearer ; les intégrations demandent deux valeurs de la page Clés API : le Client ID de votre espace de travail et l'une de ses clés. La même page contient le secret qui signe nos webhooks.

Qui peut le faire : les Propriétaires uniquement – tous les Propriétaires de l'espace de travail, pas seulement son créateur. Les Propriétaires voient, créent, copient et suppriment toutes les clés de l'espace de travail, quelle que soit la personne qui les a créées. Les Éditeurs et les Analystes ne voient Clés API ni dans la barre latérale ni sur la page Paramètres, et un lien vers cet onglet leur ouvre Profil (consultez Rôles et autorisations). Les clés fonctionnent avec tous les forfaits, y compris l'essai gratuit ; ce que vous envoyez avec elles utilise les messages de l'espace de travail.

Ouvrez Clés API sous Intégrations dans la barre latérale, ou allez dans Paramètres → Clés API.

Chaque clé affiche son nom, sa date de création (Créée le …), les quatre derniers caractères de la clé (par exemple •••• 7f3a), Copier la clé et Supprimer. La clé la plus récente apparaît en premier.

Créer une clé API#

1. Cliquez sur Créer une clé

   Dans Paramètres → Clés API, cliquez sur Créer une clé en haut à droite de la carte.

2. Nommez-la (facultatif)

   Sous Nom (facultatif), saisissez l'application qui va l'utiliser, par exemple n8n ou Site web (50 caractères maximum). Laissée vide, elle reçoit un nom comme « API Key 3 », comme l'indique l'aide sous le champ.

3. Créez-la

   Cliquez sur Créer une clé.

   

4. Copiez la clé

   Votre nouvelle clé API affiche la clé complète : « Copiez-la maintenant – vous ne verrez plus la clé complète. Ensuite, « Copier la clé » la copie sans l’afficher. » Cliquez sur Copier (« Clé copiée. »), collez la clé dans votre application ou votre intégration, puis cliquez sur Terminé.

   

• Jusqu'à 10 clés par espace de travail. Avec 10 clés, Créer une clé est grisé, et en le survolant vous voyez « Vous pouvez avoir jusqu’à 10 clés API. Supprimez-en une pour en créer une autre. »
• Les clés n'expirent pas, et elles ne peuvent être ni renommées ni désactivées : une clé fonctionne jusqu'à sa suppression.
• Une clé par application. Nommez chaque clé d'après l'application qui l'utilise, pour pouvoir en remplacer ou en supprimer une sans perturber les autres.
• Quel espace de travail : une clé appartient à l'espace de travail sélectionné au moment de sa création, et chaque requête faite avec elle agit sur cet espace de travail : ses numéros, ses messages et son forfait. Pour envoyer depuis un autre espace de travail, passez à celui-ci et créez-y une clé.

Ce qu'il faut saisir dans votre application#

Où les saisir :

• Votre propre code : dans un en-tête Authorization: Bearer YOUR_API_KEY sur chaque requête (recommandé). La clé désigne son espace de travail, donc client_id peut être omis ; si vous l'envoyez, il doit quand même être celui de cet espace de travail. Consultez Envoyer la clé dans un en-tête, et Envoyer un message pour un premier message en cURL, Python, Node.js et PHP.
• Zapier : le Client ID et la clé API, lorsque vous connectez votre compte.
• n8n : les champs Client ID, API Key et WhatsApp Client ID des identifiants WbizTool.
• Make, Pabbly Connect et d'autres outils : le corps d'une requête HTTP.
• WordPress : WbizTool → Settings, sous API Configuration.

Google Sheets et Shopify se configurent dans le tableau de bord et n'ont pas besoin de clé.

Envoyer la clé dans un en-tête#

Chaque endpoint /api/v1/ accepte la clé dans un en-tête Authorization, comme le fera la future API v2 :

Authorization: Bearer YOUR_API_KEY

• client_id est facultatif avec l'en-tête : la clé détermine l'espace de travail. Si vous envoyez aussi client_id, il doit être le Client ID de cet espace de travail, comme avant.
• Envoyez la clé à un seul endroit. Avec l'en-tête, omettez api_key dans le corps, ou envoyez la même clé. Si elles diffèrent, la clé de l'en-tête est utilisée lorsqu'elle est valide ; si l'en-tête contient autre chose (le jeton d'un autre outil, par exemple), c'est l'api_key du corps qui est utilisée.
• Les clés dans le corps fonctionnent toujours (client_id et api_key en JSON ou en champs de formulaire), donc rien ne change pour les applications et les intégrations qui les envoient. L'en-tête est préférable, car les corps de requête se retrouvent plus souvent que les en-têtes dans les journaux, les proxys et l'historique des outils de formulaires.
• Les champs de formulaire, les envois multipart et les corps JSON fonctionnent tous avec l'en-tête.

curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whatsapp_client": 101, "phone": "919876543210", "msg": "Hello from WbizTool"}'

Tester votre clé#

Appelez Vérifier les identifiants (POST /api/v1/me/) avec votre clé et, si vous le souhaitez, un whatsapp_client. "status": 1 avec "message": "Okay" signifie qu'ils fonctionnent ensemble. L'appel n'envoie rien et n'utilise aucun message, mais il ne vérifie ni qu'il vous reste des messages ni que le numéro est connecté.

curl -X POST https://wbiztool.com/api/v1/me/ -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" -d '{"whatsapp_client": 101}'

Une clé valide répond {"status": 1, "message": "Okay", "name": "…"}.

Copier à nouveau une clé#

Cliquez sur Copier la clé à côté de la clé. La clé complète est copiée dans votre presse-papiers sans être affichée sur la page ; vous voyez par exemple « « Zapier » copiée. » et le bouton affiche Copié ✓ un instant. Inutile de créer une nouvelle clé parce que vous avez perdu l'ancienne.

Pour savoir quelle clé utilise une application, comparez les quatre derniers caractères de sa clé avec la liste.

Supprimer une clé#

1. Cliquez sur Supprimer

   Cliquez sur Supprimer à côté de la clé.

2. Confirmez

   La fenêtre « Supprimer « … » ? » avertit : « Tout ce qui utilise cette clé cesse immédiatement de fonctionner : Zaps dans Zapier, scénarios n8n et Make, le plugin WordPress et vos propres appels à l’API. Donnez-leur d’abord une autre clé. Cette action est irréversible. » Cliquez sur Supprimer la clé. Vous voyez « « … » supprimée. »

Dès lors, les requêtes faites avec cette clé reçoivent Auth Error: invalid api key. Ce qu'elle a fait auparavant reste en place : les messages qu'elle a mis en attente partent quand même (annulez-les dans Rapports si nécessaire), et les rappels qu'elle a créés continuent de tourner. Un déclencheur Zapier Incoming WhatsApp Message configuré avec elle continue aussi de recevoir des messages, car son webhook est déjà sur le numéro : désactivez le Zap dans Zapier pour l'arrêter.

Remplacer une clé#

Remplacez une clé lorsqu'elle a pu fuiter, lorsqu'une personne qui pouvait la copier s'en va, ou de temps en temps. Il n'y a pas de bouton de rotation : créez d'abord la nouvelle clé, pour que rien ne s'arrête entre-temps.

1. Créez une nouvelle clé

   Créez une clé et copiez-la. Avec 10 clés, supprimez d'abord une clé que vous n'utilisez plus.

2. Mettez à jour vos applications

   Collez la nouvelle clé dans chaque application et intégration qui utilisait l'ancienne, et vérifiez chacune d'elles, par exemple avec Vérifier les identifiants.

3. Supprimez l'ancienne clé

   Supprimez-la. Elle cesse immédiatement de fonctionner.

4. Vérifiez les abus (après une fuite)

   Parcourez les Rapports pour repérer les messages que vous n'avez pas envoyés, et annulez ceux qui sont encore en attente. Dans Rappels, supprimez les rappels que vous n'avez pas créés, car ils continuent de tourner. Retirez les numéros que vous n'avez pas ajoutés dans Numéros WhatsApp. Avec le module Unibox, cherchez dans Numéros de la boîte un badge Zapier ou un webhook que vous ne reconnaissez pas.

Protéger vos clés#

Une clé n'a pas d'autorisations propres : toute personne qui en possède une peut faire dans votre espace de travail tout ce que permet l'API, quel que soit son rôle. Cela comprend envoyer des messages depuis n'importe lequel de ses numéros (en utilisant ses messages), lire son historique de messages, annuler des messages en attente, gérer les rappels et les fichiers média, vérifier des numéros et en connecter de nouveaux.

• Gardez les clés sur votre serveur, dans une variable d'environnement ou dans le gestionnaire d'identifiants de votre intégration. Ne mettez jamais une clé dans le JavaScript d'un site web, une application mobile, une feuille de calcul partagée ou du code que vous publiez.
• N'envoyez pas de clés par email ou par chat. Collez-les directement dans l'application qui en a besoin.
• Utilisez une clé par application, et supprimez les clés que vous n'utilisez plus.
• Remplacez les clés de temps en temps, et immédiatement si l'une d'elles a pu fuiter.

Le Client ID seul n'est pas un secret, mais traitez chaque clé comme un mot de passe.

Clés API v2#

L'API v2 a ses propres clés, créées dans la carte Clés API v2 du même onglet. Elles sont plus sûres que les clés ci-dessus :

• Affichées une seule fois. La clé complète (wbz_live_…) n'est affichée qu'au moment où vous la créez ; WbizTool n'en garde qu'une empreinte. Si vous la perdez, révoquez-la et créez-en une nouvelle.
• Uniquement ce dont elle a besoin. Cochez ce que la clé peut faire (envoyer des messages, lire les messages, rappels, numéros, médias, vérifications de numéros), limitez-la à certains de vos numéros, et donnez-lui une date d'expiration si vous le souhaitez.
• Clés de test. Une clé de test (wbz_test_…) vérifie chaque requête comme une clé réelle, mais n'envoie rien – pour construire et essayer une intégration.
• Dernière utilisation. Chaque clé indique quand et d'où elle a été utilisée pour la dernière fois. Révoquer l'arrête immédiatement, ainsi que les endpoints de webhook qu'elle a créés.

Les clés ci-dessus ne fonctionnent qu'avec l'API v1, et les clés API v2 qu'avec la v2. Consultez Passer de la v1 à la v2.

Signatures des webhooks#

WbizTool signe chaque webhook qu'il vous envoie, pour que votre endpoint puisse vérifier qu'une requête vient bien de nous et n'a pas été modifiée en chemin : le webhook de statut des messages (envoyé, échoué, annulé, expiré), les événements de connexion des numéros et les webhooks de la boîte de réception. Les corps restent les mêmes ; deux en-têtes s'ajoutent :

La signature couvre exactement les octets que nous envoyons : les champs de formulaire tels qu'ils arrivent, tout le corps multipart lorsqu'une image de QR code est jointe, et le JSON des webhooks de la boîte de réception. Les récepteurs qui ignorent les en-têtes continuent de fonctionner.

Obtenir le secret de signature#

Dans Paramètres → Clés API, la carte Secret de signature des webhooks, sous vos clés, affiche les quatre derniers caractères du secret, par exemple •••• b70d. Chaque espace de travail a un seul secret pour tous ses webhooks ; il est créé avec le premier webhook que nous vous envoyons.

1. Cliquez sur Afficher un nouveau secret

   Cliquez sur Afficher un nouveau secret (ou sur Créer le secret si l'espace de travail n'en a pas encore). La fenêtre « Remplacer le secret de signature ? » avertit que le secret actuel cesse immédiatement de fonctionner. Cliquez sur Générer un nouveau secret.

2. Copiez-le

   Votre secret de signature des webhooks affiche le secret complet une seule fois. Cliquez sur Copier et conservez-le là où votre récepteur de webhooks peut le lire, par exemple dans une variable d'environnement. Vous ne le reverrez plus : si vous le perdez, générez-en un nouveau.

Seuls les Propriétaires voient la carte. Un nouveau secret remplace l'ancien immédiatement : mettez donc vos récepteurs à jour tout de suite, car les webhooks envoyés entre-temps échouent à votre vérification.

Vérifier un webhook#

Calculez la signature à partir du corps brut (avant que votre framework ne l'analyse), comparez-la à l'en-tête en temps constant, et refusez les horodatages de plus de 5 minutes pour qu'une ancienne requête ne puisse pas être rejouée :

import hashlib, hmac, time

def verify(secret: str, body: bytes, headers) -> bool:
    ts, sig = headers["WbizTool-Timestamp"], headers["WbizTool-Signature"]
    mac = "v1=" + hmac.new(secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(ts)) < 300 and hmac.compare_digest(mac, sig)

const crypto = require("crypto");

function verify(secret, rawBody, headers) {
  const ts = headers["wbiztool-timestamp"], sig = String(headers["wbiztool-signature"]);
  const mac = "v1=" + crypto.createHmac("sha256", secret).update(ts + ".").update(rawBody).digest("hex");
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300 && sig.length === mac.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(mac));
}

Répondez 2xx lorsque la vérification réussit et 401 lorsqu'elle échoue. Les webhooks de la boîte de réception dont le numéro a son propre secret du webhook portent toujours aussi X-Wbiztool-Signature ; WbizTool-Signature suit le même schéma sur tous les webhooks.

Dépannage#

Voir aussi#

• Introduction à l'API
• Présentation de l'API v2
• API de vérification des identifiants
• API d'envoi de messages
• Applications et intégrations
• Paramètres de l'espace de travail, membres de l'équipe et rôles
• Connecter votre numéro WhatsApp