Die dokumentierte WhatsApp-API.

Von null zu deiner ersten Nachricht in 3 Schritten.

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":"Hallo von WAzion Bridge"}'

Die Konsole ist der Ort, an dem du Linien, API-Schlüssel und Webhooks verwaltest. Die Dokumentation beschreibt dieselbe API, die du dort testen kannst.

API-Basis und Authentifizierung.

Jede Anfrage wird mit einem API-Schlüssel im Authorization-Header authentifiziert (es wird auch akzeptiert X-Bridge-Key). Die API-Schlüssel werden in der Konsole erstellt und beginnen mit wzb_live_. Jede Antwort enthält eine Überschrift X-Request-Id nützlich für Unterstützung und Debugging. Die API unterstützt CORS (Access-Control-Allow-Origin: *).

Authorization: Bearer wzb_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Wie Bridge organisiert ist.

Du arbeitest immer mit line_id und API-Keys. Bridge verbirgt die interne WhatsApp-Sitzung: du exponierst oder verwendest niemals die session_key.

REST-Endpunkte.

POST /v1/messages/send

Die Sendungen (send, send-media, reply) akzeptieren den Header Idempotency-Key. Die GET-Anfragen /v1/chats und /v1/messages begrenzen das Ergebnis auf 500 bzw. 200.

Sende eine Nachricht in deiner Sprache.

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);

Bild, Video, Audio oder Dokument senden.

Verwende media_type mit einem dieser Werte: image, video, audio, document. Das Feld media_url muss eine öffentliche URL sein, die der Server herunterladen kann.

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":"Hallo"}'

Idempotenz.

Um die gleiche Nachricht nicht zweimal zu senden (Netzwerkwiederholungen, Neustarts), senden Sie die Kopfzeile. Idempotency-Key mit einer eindeutigen Kennung deiner Operation. Wenn du denselben Schlüssel mit demselben Inhalt wiederholst, gibt Bridge die gespeicherte Antwort zurück, ohne sie erneut zu senden. Der Schlüssel wird 24 Stunden lang gespeichert und gilt für send, send-media und reply.

-H "Idempotency-Key: pedido-1001"

Wenn du denselben Schlüssel mit einem anderen Körper wiederverwendest, erhältst du 409 idempotency_conflict.

Ereignisse empfangen, die signiert sind.

Erstelle einen Webhook mit einer öffentlichen HTTPS-URL. Bridge wird bei jedem Ereignis ein POST an diese URL senden. Jeder Webhook hat sein eigenes Geheimnis. (wzb_whsec_...) das nur einmal beim Erstellen angezeigt wird.

Ereignisse, die Sie abonnieren können (werden so geliefert, wie sie vom WhatsApp-Motor erzeugt werden): message.received, message.sent, message.status, line.status.

Jede Lieferung enthält diese Kopfzeilen:

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

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

Unterschrift überprüfen

Die Signatur ist ein HMAC-SHA256 des Rohkörpers unter Verwendung des Webhook-Geheimnisses. Vergleiche immer, bevor du verarbeitest:

// 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; }

Du kannst ein Testereignis an deinen Webhook von der Konsole aus oder mit POST /v1/webhooks/{id}/test senden.

Fehlerbehandlung.

Die Fehler bei der Authentifizierung, dem Konto und dem Server verwenden einen standardisierten Umschlag:

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

Die Validierungs- und Geschäftsfehler verwenden eine flache Form mit dem fehlerhaften Code:

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

Beiträge pro Plan.

• Die Kontingente (gesendete Nachrichten, Webhook-Ereignisse, Anzahl der Zeilen) gelten pro Konto und werden innerhalb deines Abrechnungszyklus gezählt.
• Wenn du ein Kontingent überschreitest, erhältst du 429 (quota_exceeded oder line_limit_reached) mit den Details used, limit und plan.
• GET /v1/chats gibt maximal 500 Chats zurück und GET /v1/messages maximal 200 Nachrichten pro Anfrage.
• Für die Stabilität von WhatsApp werden die Sendungen einer gleichen Linie um einige Sekunden gestaffelt; die massenhaften Sendungen werden über die Zeit verteilt.

Überprüfen Sie Ihren Verbrauch jederzeit mit GET /v1/usage. Die konkreten Grenzen jedes Plans liegen in die Seite der Pläne.

MCP-Server für deinen Agenten.

Bridge bietet einen MCP-Server (Model Context Protocol), damit dein Agent WhatsApp senden und lesen kann, ohne REST-Code zu schreiben. Ergänze es mit:

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