L’API de WhatsApp, documentée.

De zéro à votre premier message en 3 étapes.

curl -X POST https://www.wazion.com/api/bridge/v1/messages/send \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"line_id":"TU_LINE_ID","to":"+34600000000","message":"Bonjour depuis WAzion Bridge"}'

La console est l’endroit où vous gérez les lignes, les clés API et les webhooks. La documentation décrit la même API que vous pouvez tester là-bas.

Base de l’API et authentification.

Toute demande est authentifiée avec une clé API dans l’en-tête Authorization (une autre méthode est également acceptée). X-Bridge-Key). Les clés API se créent dans la console et commencent par wzb_live_. Chaque réponse inclut un en-tête X-Request-Id outil pour le support et le débogage. L’API prend en charge CORS (Access-Control-Allow-Origin: *).

Authorization: Bearer wzb_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Comment est organisé Bridge.

Vous travaillez toujours avec line_id et des clés API. Bridge cache la session interne de WhatsApp : vous n’exposez jamais ni n’utilisez la session_key.

Points de terminaison REST.

POST /v1/messages/send

Les envois (send, send-media, reply) acceptent l’en-tête Idempotency-Key. Les lectures GET /v1/chats et GET /v1/messages limitent le résultat à 500 et 200 respectivement.

Envoyer un message dans ta langue.

curl -X POST https://www.wazion.com/api/bridge/v1/messages/send \
  -H "Authorization: Bearer wzb_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{"line_id":"line_xxx","to":"+34600000000","message":"Pedido confirmado"}'

// Node 18+ (fetch nativo)
const res = await fetch("https://www.wazion.com/api/bridge/v1/messages/send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer wzb_live_xxx",
    "Content-Type": "application/json",
    "Idempotency-Key": "order-1001"
  },
  body: JSON.stringify({
    line_id: "line_xxx",
    to: "+34600000000",
    message: "Pedido confirmado"
  })
});
console.log(await res.json());

import requests

r = requests.post(
    "https://www.wazion.com/api/bridge/v1/messages/send",
    headers={
        "Authorization": "Bearer wzb_live_xxx",
        "Idempotency-Key": "order-1001",
    },
    json={
        "line_id": "line_xxx",
        "to": "+34600000000",
        "message": "Pedido confirmado",
    },
)
print(r.json())

<?php
$ch = curl_init("https://www.wazion.com/api/bridge/v1/messages/send");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer wzb_live_xxx",
        "Content-Type: application/json",
        "Idempotency-Key: order-1001",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "line_id" => "line_xxx",
        "to" => "+34600000000",
        "message" => "Pedido confirmado",
    ]),
]);
echo curl_exec($ch);

Envoyer une image, une vidéo, un audio ou un document.

Utilisez media_type avec l’une de ces valeurs : image, video, audio, document. Le champ media_url doit être une URL publique que le serveur peut télécharger.

curl -X POST https://www.wazion.com/api/bridge/v1/messages/send-media \
  -H "Authorization: Bearer wzb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"line_id":"line_xxx","to":"+34600000000","media_url":"https://tu-cdn.com/foto.jpg","media_type":"image","caption":"Bonjour"}'

Idempotence.

Pour ne pas envoyer le même message deux fois (réessais de réseau, redémarrages), envoie l’en-tête. Idempotency-Key avec un identifiant unique de votre opération. Si vous répétez la même clé avec le même corps, Bridge renvoie la réponse enregistrée sans renvoyer. La clé est mémorisée pendant 24 heures et s’applique à send, send-media et reply.

-H "Idempotency-Key: pedido-1001"

Si vous réutilisez la même clé avec un corps différent, vous recevez 409 idempotency_conflict.

Recevoir des événements signés.

Créez un webhook avec une URL HTTPS publique. Bridge enverra un POST à cette URL à chaque événement. Chaque webhook a son propre secret. (wzb_whsec_...) qui s’affiche une seule fois lors de sa création.

Événements auxquels vous pouvez vous abonner (ils sont livrés tels que produits par le moteur de WhatsApp) : message.received, message.sent, message.status, line.status.

Chaque livraison comprend ces en-têtes :

X-WAzion-Bridge-Event: message.received
X-WAzion-Bridge-Signature: sha256=<hmac>
Content-Type: application/json

{
  "event": "message.received",
  "line_id": "line_xxx",
  "data": { ... }
}

Vérifier la signature

La signature est un HMAC-SHA256 du corps brut utilisant le secret du webhook. Compare toujours avant de traiter :

// Node.js
import crypto from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected)
  );
}

<?php
// PHP
$raw = file_get_contents("php://input");
$sig = $_SERVER["HTTP_X_WAZION_BRIDGE_SIGNATURE"] ?? "";
$expected = "sha256=" . hash_hmac("sha256", $raw, $secret);
if (!hash_equals($expected, $sig)) { http_response_code(401); exit; }

Vous pouvez lancer un événement de test à votre webhook depuis la console ou avec POST /v1/webhooks/{id}/test.

Gestion des erreurs.

Les erreurs d’authentification, de compte et de serveur utilisent une enveloppe normalisée :

{
  "ok": false,
  "error": { "code": "unauthorized", "message": "...", "retryable": false }
}

Les erreurs de validation et de métier utilisent une forme plate avec le code en erreur :

{ "error": "quota_exceeded", "message": "Monthly quota exceeded", "metric": "sent_messages", "used": 10000, "limit": 10000, "plan": "pro" }

Cotisations par plan.

• Les quotas (messages envoyés, événements de webhook, nombre de lignes) sont par compte et sont comptées dans votre cycle de facturation.
• En dépassant un quota, vous recevez 429 (quota_exceeded ou line_limit_reached) avec les détails de used, limit et plan.
• GET /v1/chats renvoie au maximum 500 chats et GET /v1/messages au maximum 200 messages par requête.
• Pour la stabilité de WhatsApp, les envois d’une même ligne sont espacés de quelques secondes ; ils répartissent les envois massifs dans le temps.

Consulte votre consommation à tout moment avec GET /v1/usage. Les limites concrètes de chaque plan sont dans la page des plans.

Serveur MCP pour votre agent.

Bridge expose un serveur MCP (Model Context Protocol) pour que votre agent envoie et lise WhatsApp sans écrire de code REST. Ajoutez-le avec :

claude mcp add --transport http wazion-bridge \
  https://www.wazion.com/api/bridge/mcp \
  --header "Authorization: Bearer wzb_live_xxx"