A WhatsApp API, dokumentálva.

Nulláról az első üzenetedig 3 lépésben.

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":"Helló a WAzion Bridge-ből"}'

A konzol az, ahol kezelheted a vonalakat, API kulcsokat és webhooks-t. A dokumentáció ugyanazt az API-t írja le, amelyet ott kipróbálhatsz.

API alapja és hitelesítés.

Minden kérés autentikálva van egy API kulccsal a Authorization fejlécben (elfogadott X-Bridge-Key). Az API kulcsokat a konzolban hozzák létre, és a következővel kezdődnek wzb_live_. Minden válasz tartalmaz egy fejlécet X-Request-Id használható támogatásra és hibakeresésre. Az API támogatja a CORS-t (Access-Control-Allow-Origin: *).

Authorization: Bearer wzb_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Hogyan van megszervezve a Bridge.

Mindig line_id-val és API kulcsokkal dolgozol. A Bridge elrejti a WhatsApp belső munkamenetét: soha nem teszed közzé és nem használod a session_key-t.

REST végpontok.

POST /v1/messages/send

A küldemények (send, send-media, reply) elfogadják az Idempotency-Key fejlécet. A GET /v1/chats és a GET /v1/messages lekérdezések az eredményt 500-ra, illetve 200-ra korlátozzák.

Üzenetet küldeni a nyelveden.

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

Kép, videó, hang vagy dokumentum küldése.

Használj media_type-ot az alábbi értékek egyikével: image, video, audio, document. A media_url mezőnek egy nyilvános URL-nek kell lennie, amelyet a szerver letölthet.

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

Idempotencia.

A két ugyanazt az üzenetet ne küldje el (hálózati újrapróbálkozások, újraindítások), küldje el a fejlécet. Idempotency-Key egyedi azonosítóval a műveletedhez. Ha ugyanazt a kulcsot ugyanazzal a törzzsel ismétled, a Bridge a mentett választ adja vissza anélkül, hogy újra elküldené. A kulcsot 24 órán át megjegyzik, és a send, send-media és reply műveletekre vonatkozik.

-H "Idempotency-Key: pedido-1001"

Ha ugyanazt a kulcsot különböző törzzsel használod, 409 idempotency_conflict-ot kapsz.

Aláírt események fogadása.

Hozz létre egy nyilvános HTTPS URL-lel rendelkező webhookot. A Bridge minden eseménynél POST-ot küld erre az URL-re. Minden webhooknak megvan a saját titka. (wzb_whsec_...) amit csak egyszer mutatnak be a létrehozásakor.

Olyan események, amelyekre feliratkozhatsz (azokat úgy adják át, ahogyan a WhatsApp motorja előállítja): message.received, message.sent, message.status, line.status.

Minden szállítmány tartalmazza ezeket a fejlécet:

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

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

A aláírás ellenőrzése

A aláírás egy HMAC-SHA256 a nyers törzs alapján, a webhook titkos kulcsát használva. Mindig hasonlítsd össze a feldolgozás előtt:

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

Egy teszt eseményt indíthatsz a webhookodra a konzolból vagy a POST /v1/webhooks/{id}/test segítségével.

Hibakezelés.

A hitelesítési, fiók- és szerverhibák egy normalizált borítékot használnak:

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

A validációs és üzleti hibák egy sík formát használnak a hibás kóddal:

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

Tervdíjak.

• A kvóták (küldött üzenetek, webhook események, sorok száma) fiókonként értendők, és a számlázási ciklusodba számítanak.
• Ha túlléped a kvótát, 429 (quota_exceeded vagy line_limit_reached) választ kapsz a használt, a limit és a terv részleteivel.
• A GET /v1/chats legfeljebb 500 csevegést, a GET /v1/messages pedig legfeljebb 200 üzenetet ad vissza kérésenként.
• A WhatsApp stabilitása miatt az azonos vonalon történő küldések között néhány másodpercnyi szünet van; a tömeges küldéseket időben elosztja.

Bármikor ellenőrizheti a fogyasztását a GET /v1/usage. A konkrét határok minden tervben a következők: a tervek oldala.

MCP szerver a te ügynököd számára.

A Bridge egy MCP (Model Context Protocol) szervert kínál, hogy az ügynököd WhatsApp-ot küldjön és olvasson anélkül, hogy REST kódot kellene írnod. Kiegészítem a következővel:

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