L’API di WhatsApp, documentata.

Da zero al tuo primo messaggio in 3 passaggi.

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":"Ciao da WAzion Bridge"}'

La console è dove gestisci le linee, le chiavi API e i webhook. La documentazione descrive la stessa API che puoi provare lì.

Base dell’API e autenticazione.

Tutta la richiesta viene autenticata con una API key nell’intestazione Authorization (si accetta anche X-Bridge-Key). Le chiavi API si creano nella console e iniziano per wzb_live_. Ogni risposta include un’intestazione X-Request-Id utile per supporto e debug. L’API supporta CORS (Access-Control-Allow-Origin: *).

Authorization: Bearer wzb_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Come è organizzato Bridge.

Lavori sempre con line_id e API keys. Bridge nasconde la sessione interna di WhatsApp: non esponi né usi la session_key.

Endpoint REST.

POST /v1/messages/send

Le spedizioni (send, send-media, reply) ammettono l’intestazione Idempotency-Key. Le letture GET /v1/chats e GET /v1/messages limitano il risultato a 500 e 200 rispettivamente.

Invia un messaggio nella tua lingua.

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

Invia immagine, video, audio o documento.

Usa media_type con uno de questi valori: image, video, audio, document. Il campo media_url deve essere un’URL pubblica che il server possa scaricare.

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

Idempotenza.

Per non inviare lo stesso messaggio due volte (ritentativi di rete, riavvii), invia l’intestazione Idempotency-Key con un identificatore unico della tua operazione. Se ripeti la stessa chiave con lo stesso corpo, Bridge restituisce la risposta salvata senza reinviare. La chiave viene ricordata per 24 ore e si applica a send, send-media e reply.

-H "Idempotency-Key: pedido-1001"

Se riutilizzi la stessa chiave con un corpo diverso, ricevi 409 idempotency_conflict.

Ricevere eventi firmati.

Crea un webhook con un URL HTTPS pubblica. Bridge invierà un POST a quell’URL ad ogni evento. Ogni webhook ha il proprio segreto. (wzb_whsec_...) che viene mostrato una sola volta al crearlo.

Eventi a cui puoi iscriverti (vengono forniti così come li produce il motore di WhatsApp): message.received, message.sent, message.status, line.status.

Ogni consegna include queste intestazioni:

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

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

Verificare la firma

La firma è un HMAC-SHA256 del corpo in chiaro utilizzando il segreto del webhook. Confronta sempre prima di elaborare:

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

Puoi lanciare un evento di prova al tuo webhook dalla console o con POST /v1/webhooks/{id}/test.

Gestione degli errori.

Gli errori di autenticazione, account e server utilizzano una busta normalizzata:

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

Gli errori di validazione e di business utilizzano una forma piatta con il codice in errore:

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

Quote per piano.

• Le quote (messaggi inviati, eventi webhook, numero di righe) sono per account e vengono conteggiate all’interno del tuo ciclo di fatturazione.
• Superando una quota ricevi 429 (quota_exceeded o line_limit_reached) con il dettaglio di used, limit e plan.
• GET /v1/chats restituisce al massimo 500 chat e GET /v1/messages al massimo 200 messaggi per richiesta.
• Per stabilità di WhatsApp, le spedizioni di una stessa linea sono distanziate di alcuni secondi; distribuisci le spedizioni massicce nel tempo.

Controlla il tuo consumo in qualsiasi momento con GET /v1/usage. I limiti concreti di ogni piano sono in la pagina dei piani.

Server MCP per il tuo agente.

Bridge espone un server MCP (Model Context Protocol) affinché il tuo agente possa inviare e leggere WhatsApp senza scrivere codice REST. Aggiungilo con:

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