API développeur

Branchez WhatzAI à vos propres outils

Votre site, votre boutique en ligne ou votre logiciel peut lire vos contacts et vos conversations, ajouter des contacts et envoyer un message WhatsApp. L'API fait partie du plan Agency.

Vous n'êtes pas technicien ?

Une API est une porte d'entrée réservée aux logiciels. Elle permet à un autre outil de parler à WhatzAI à votre place, sans que personne n'ouvre le tableau de bord. Exemples :

Votre boutique en ligne prévient le client sur WhatsApp quand sa commande est prête.
Un formulaire de votre site ajoute chaque nouveau prospect dans vos contacts WhatzAI.
Votre logiciel de gestion affiche l'historique WhatsApp d'un client.

Vous n'avez rien à programmer vous-même : créez une clé (étape 1) et transmettez cette page à la personne qui s'occupe de votre site ou de votre logiciel.

1. Créer une clé

Dans votre tableau de bord : Paramètres → Clé API → « Créer une clé ». Elle commence par wz_live_ et n'est affichée qu'une seule fois. Gardez-la secrète, côté serveur uniquement.

Deux types de clé : lecture seule (consulter contacts et conversations) ou lecture et écriture (aussi ajouter un contact et envoyer un message). Donnez à chaque outil le minimum dont il a besoin. Vous pouvez créer jusqu'à 5 clés, une par outil.

2. Appeler l'API

Adresse de base : https://whatzai-backend.onrender.com. Envoyez votre clé dans l'en-tête Authorization. Les réponses sont en JSON.

curl https://whatzai-backend.onrender.com/v1/contacts?limit=10 \
  -H "Authorization: Bearer wz_live_VOTRE_CLE"

Envoyer un message :

curl -X POST https://whatzai-backend.onrender.com/v1/messages \
  -H "Authorization: Bearer wz_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "ID_DE_L_AGENT", "to": "+237696213325", "text": "Votre commande est prête." }'

3. Les routes

GET/v1/account

Votre compte : identifiant, email, entreprise, plan.

GET/v1/agents

Vos agents et numéros, avec leur identifiant (nécessaire pour envoyer un message).

GET/v1/contacts

Vos contacts, du plus récent au plus ancien.

Paramètres : limit (1 à 100, 50 par défaut), after (identifiant du dernier contact reçu, pour la page suivante), phone (chercher un numéro).

POST/v1/contacts

Ajouter un contact.

Corps : phone (obligatoire, avec l'indicatif du pays), name, email. Réponse 409 si le numéro existe déjà.

{ "phone": "+237696213325", "name": "Marie" }

GET/v1/conversations

Vos conversations, la plus récente d'abord.

Paramètre : limit (1 à 100).

GET/v1/conversations/{id}/messages

Les derniers messages d'une conversation.

Champ « from » : contact (le client), ai (l'agent), human (votre équipe ou votre API).

POST/v1/messages

Envoyer un message texte WhatsApp depuis le numéro d'un agent.

Corps : agentId, to (numéro avec indicatif), text (4 096 caractères maximum).

{ "agentId": "…", "to": "+237696213325", "text": "Votre commande est prête." }

4. Être prévenu à chaque message reçu

Plutôt que d'interroger l'API en boucle, donnez une adresse à WhatzAI (Paramètres → Clé API → « Être prévenu à chaque message reçu »). Dès qu'un client vous écrit, WhatzAI envoie à cette adresse une requête POST en JSON :

{
  "event": "message.received",
  "createdAt": "2026-10-12T08:30:00.000Z",
  "data": {
    "messageId": "…",
    "conversationId": "…",
    "agentId": "…",
    "contact": { "id": "…", "phone": "237696213325", "name": "Marie" },
    "type": "text",
    "text": "Bonjour, ma commande est prête ?"
  }
}

L'adresse doit être publique et commencer par https://.
Répondez vite avec un code 200. WhatzAI attend 5 secondes au maximum et ne renvoie pas un appel échoué : pour ne rien manquer, complétez avec GET /v1/conversations.
Le bouton « Envoyer un essai » envoie un événement ping pour vérifier votre adresse.
Vérifiez la signature. Chaque appel porte l'en-tête X-WhatzAI-Signature, égal à sha256= suivi du HMAC-SHA256 du corps brut de la requête, calculé avec votre secret. Refusez tout appel dont la signature ne correspond pas.

// Exemple Node.js
import { createHmac, timingSafeEqual } from "node:crypto";

function vientDeWhatzAI(corpsBrut, signatureRecue, secret) {
  const attendue = "sha256=" + createHmac("sha256", secret).update(corpsBrut).digest("hex");
  const a = Buffer.from(attendue), b = Buffer.from(signatureRecue || "");
  return a.length === b.length && timingSafeEqual(a, b);
}

5. Les règles à connaître

Fenêtre de 24 heures. WhatsApp n'autorise un message libre que dans les 24 heures qui suivent le dernier message du client sur ce numéro. En dehors, l'API répond 422 et rien n'est envoyé.
Désabonnement. Un contact qui a répondu STOP n'est jamais contacté (403).
Limites. 240 requêtes par minute et par compte, dont 60 modifications. Au-delà : 429.
Vos données seulement. Une clé ne donne accès qu'au compte qui l'a créée.
Clé perdue ou exposée. Supprimez-la dans Paramètres : elle cesse de fonctionner aussitôt.

6. Les codes d'erreur

400	Un champ est manquant ou invalide. Le message précise lequel.
401	Clé absente ou invalide.
403	Plan Agency inactif, clé en lecture seule utilisée pour modifier, ou contact désabonné (il a répondu STOP).
404	L'élément n'existe pas dans votre compte.
409	Le contact existe déjà.
422	Fenêtre de 24 h fermée : le client n'a pas écrit depuis plus de 24 heures.
429	Trop de requêtes. Attendez une minute.
502	WhatsApp a refusé l'envoi. Réessayez plus tard.

Une erreur renvoie toujours un champ message en français qui explique la cause.

Une question ou un besoin qui n'est pas couvert ? difisoltech@gmail.com