The WhatsApp API, documented.

From zero to your first message in 3 steps.

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":"Hello from WAzion Bridge"}'

The console is where you manage lines, API keys, and webhooks. The documentation describes the same API that you can test there.

API base and authentication.

All requests are authenticated with an API key in the Authorization header (it is also accepted X-Bridge-Key). API keys are created in the console and start with wzb_live_. Each response includes a header X-Request-Id tool for support and debugging. The API supports CORS (Access-Control-Allow-Origin: *).

Authorization: Bearer wzb_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

How Bridge is organized.

You always work with line_id and API keys. Bridge hides the internal WhatsApp session: you never expose or use the session_key.

REST endpoints.

POST /v1/messages/send

The shipments (send, send-media, reply) accept the Idempotency-Key header. The GET /v1/chats and GET /v1/messages readings limit the result to 500 and 200 respectively.

Send a message in your language.

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

Send image, video, audio, or document.

Use media_type with one of these values: image, video, audio, document. The media_url field must be a public URL that the server can download.

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

Idempotence.

To avoid sending the same message twice (network retries, restarts), send the header. Idempotency-Key with a unique identifier for your operation. If you repeat the same key with the same body, Bridge returns the saved response without resending. The key is remembered for 24 hours and applies to send, send-media, and reply.

-H "Idempotency-Key: pedido-1001"

If you reuse the same key with a different body, you receive 409 idempotency_conflict.

Receive signed events.

Create a webhook with a public HTTPS URL. Bridge will send a POST to that URL on each event. Each webhook has its own secret. (wzb_whsec_...) that is shown only once when creating it.

Events you can subscribe to (they are delivered as produced by the WhatsApp engine): message.received, message.sent, message.status, line.status.

Each delivery includes these headers:

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

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

Verify the signature

The signature is an HMAC-SHA256 of the raw body using the webhook secret. Always compare before processing:

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

You can trigger a test event to your webhook from the console or with POST /v1/webhooks/{id}/test.

Error handling.

Authentication, account, and server errors use a standardized envelope:

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

Validation and business errors use a flat form with the error code:

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

Plan fees.

• The quotas (sent messages, webhook events, number of lines) are per account and are counted within your billing cycle.
• Upon exceeding a quota, you receive 429 (quota_exceeded or line_limit_reached) with the details of used, limit, and plan.
• GET /v1/chats returns a maximum of 500 chats and GET /v1/messages a maximum of 200 messages per request.
• For the stability of WhatsApp, the deliveries of the same line are spaced a few seconds apart; it distributes mass deliveries over time.

Check your consumption at any time with GET /v1/usage. The specific limits of each plan are in the plans page.

MCP server for your agent.

Bridge exposes an MCP (Model Context Protocol) server so that your agent can send and read WhatsApp without writing REST code. Add it with:

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