Skip to main content

API Reference

The single source of truth is the OpenAPI spec (packages/sdk/openapi.yaml), which generates the TypeScript SDK and this reference. Below are the core endpoints with real examples. Authenticate with Authorization: Bearer bz_live_....

Send text — POST /messages/text​

curl -X POST https://api.bzapper.com.br/messages/text \
  -H "Authorization: Bearer $BZ_KEY" -H "Content-Type: application/json" \
  -d '{"instance_id":"INST","to":"+5511988888888","body":"Hello","client_reference":"lead-42"}'
import requests
requests.post("https://api.bzapper.com.br/messages/text",
  headers={"Authorization": f"Bearer {key}"},
  json={"instance_id": inst, "to": "+5511988888888", "body": "Hello"})
await fetch("https://api.bzapper.com.br/messages/text", {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ instance_id: inst, to: "+5511988888888", body: "Hello" }),
});
<?php
$ch = curl_init("https://api.bzapper.com.br/messages/text");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer $key", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["instance_id" => $inst, "to" => "+5511988888888", "body" => "Hello"]),
  CURLOPT_RETURNTRANSFER => true,
]);
$res = curl_exec($ch);

Response 202: { "message_id": "...", "status": "queued", "client_reference": "lead-42" }.

Other core endpoints​

  • POST /messages/{image,video,document,audio,sticker,location,contact,poll,reaction,buttons,list}
  • POST /messages/otp — verification code in 2 messages (text + the code bubble); counts as 1 send. The code is never persisted or shown in the inbox (masked + echoguard). If you omit body, the API generates the text in the account's language. Details in Message types → OTP.
  • POST /contacts/check — IsOnWhatsApp (handles @lid)
  • GET /conversations?instance_id= and GET /conversations/{jid}/messages — inbox
  • GET /media/{id} — a stable reference to received media (private): responds with 302 to a fresh pre-signed URL. See Message types.
  • POST /webhooks — register a webhook (HMAC); see the webhooks guide
  • GET /stream — real-time SSE
  • GET /usage — usage telemetry
  • GET /billing/wallet · POST /billing/checkout · GET /me/entitlements — wallet/top-up and limits; see Billing (prepaid)

Errors​

Every error has a stable neutral code plus a translated message:

{ "code": "instance_not_connected", "message": "Number disconnected...", "locale": "en" }

Use the code in your logic. Common ones: unauthorized, forbidden, rate_limited, not_connected, no_number_available, not_supported (experimental).