La API de WhatsApp, documentada.

De cero a tu primer mensaje en 3 pasos.

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":"Hola desde WAzion Bridge"}'

La consola es donde gestionas lineas, API keys y webhooks. La documentacion describe la misma API que puedes probar alli.

Base de la API y autenticacion.

Toda peticion se autentica con una API key en la cabecera Authorization (tambien se acepta X-Bridge-Key). Las API keys se crean en la consola y empiezan por wzb_live_. Cada respuesta incluye una cabecera X-Request-Id util para soporte y depuracion. La API admite CORS (Access-Control-Allow-Origin: *).

Authorization: Bearer wzb_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Como esta organizado Bridge.

Trabajas siempre con line_id y API keys. Bridge oculta la sesion interna de WhatsApp: nunca expones ni usas la session_key.

Endpoints REST.

POST /v1/messages/send

Los envios (send, send-media, reply) admiten la cabecera Idempotency-Key. Las lecturas GET /v1/chats y GET /v1/messages limitan el resultado a 500 y 200 respectivamente.

Enviar un mensaje en tu lenguaje.

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

Enviar imagen, video, audio o documento.

Usa media_type con uno de estos valores: image, video, audio, document. El campo media_url debe ser una URL publica que el servidor pueda descargar.

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

Idempotencia.

Para no enviar el mismo mensaje dos veces (reintentos de red, reinicios), envia la cabecera Idempotency-Key con un identificador unico de tu operacion. Si repites la misma clave con el mismo cuerpo, Bridge devuelve la respuesta guardada sin reenviar. La clave se recuerda 24 horas y aplica a send, send-media y reply.

-H "Idempotency-Key: pedido-1001"

Si reutilizas la misma clave con un cuerpo distinto, recibes 409 idempotency_conflict.

Recibir eventos firmados.

Crea un webhook con una URL HTTPS publica. Bridge enviara un POST a esa URL en cada evento. Cada webhook tiene su propio secreto (wzb_whsec_...) que se muestra una sola vez al crearlo.

Eventos que puedes suscribir (se entregan tal y como los produce el motor de WhatsApp): message.received, message.sent, message.status, line.status.

Cada entrega incluye estas cabeceras:

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

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

Verificar la firma

La firma es un HMAC-SHA256 del cuerpo en crudo usando el secreto del webhook. Compara siempre antes de procesar:

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

Puedes lanzar un evento de prueba a tu webhook desde la consola o con POST /v1/webhooks/{id}/test.

Manejo de errores.

Los errores de autenticacion, cuenta y servidor usan un sobre normalizado:

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

Los errores de validacion y de negocio usan una forma plana con el codigo en error:

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

Cuotas por plan.

• Las cuotas (mensajes enviados, eventos de webhook, numero de lineas) son por cuenta y se cuentan dentro de tu ciclo de facturacion.
• Al superar una cuota recibes 429 (quota_exceeded o line_limit_reached) con el detalle de used, limit y plan.
• GET /v1/chats devuelve como maximo 500 chats y GET /v1/messages como maximo 200 mensajes por peticion.
• Por estabilidad de WhatsApp, los envios de una misma linea se espacian unos segundos; reparte los envios masivos en el tiempo.

Consulta tu consumo en cualquier momento con GET /v1/usage. Los limites concretos de cada plan estan en la pagina de planes.

Servidor MCP para tu agente.

Bridge expone un servidor MCP (Model Context Protocol) para que tu agente envie y lea WhatsApp sin escribir codigo REST. Anadelo con:

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