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" \
  -H "Idempotency-Key: TU_OPERACION_UNICA" \
  -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 e reply richiedono 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" \
  -H "Idempotency-Key: media-1001" \
  -d '{"line_id":"line_xxx","to":"+34600000000","media_url":"https://tu-cdn.com/foto.jpg","media_type":"image","caption":"Ciao"}'

Idempotenza.

Le spedizioni send, send-media e reply richiedono l’intestazione Idempotency-Key con un identificatore unico della tua operazione. Durante un’occorrenza, ripetere la stessa chiave con lo stesso corpo restituisce lo stato salvato senza reinviare né consumare nuovamente quota. Una chiave completata può avviare una nuova occorrenza quando scade la sua retention di 24 ore; i retry di rete dell’occorrenza attiva conservano sempre la stessa identità interna.

-H "Idempotency-Key: pedido-1001"

Le risposte queued, processing e sent_unconfirmed includono status_url per consultare GET /v1/messages/status. Solo sent con message_id conferma l’invio; sent_unconfirmed richiede riconciliazione o revisione manuale e Bridge non lo reinvia né restituisce automaticamente la sua quota. Se riutilizzi la stessa chiave attiva con un corpo diverso, ricevi 409 idempotency_conflict.

GET https://www.wazion.com/api/bridge/v1/messages/status?endpoint=messages%2Fsend&idempotency_key=pedido-1001

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: message.received, message.sent, message.status, line.connected, line.disconnected. line.status è un alias di abbonamento che include entrambi gli eventi di linea.

Il campo event del corpo e l’intestazione X-WAzion-Bridge-Event usano sempre il nome normalizzato. event_id e X-WAzion-Bridge-Event-Id conservano la stessa identità in tutti i tentativi di ripetizione.

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"

La risposta initialize restituisce Mcp-Session-Id. Il cliente deve restituire quell’intestazione: insieme all’id JSON-RPC e agli argomenti identifica in modo durevole le spedizioni MCP. Se il cliente non conserva le sessioni, deve fornire idempotency_key esplicitamente in send, send-media e reply.