Skip to main content

Quickstart — your first message in 5 minutes

You'll connect a number and send your first message.

1. Get your API key​

In the admin panel (or with the super-admin), create an API key for your tenant. It becomes Authorization: Bearer bz_live_... on every call.

2. Create a number and connect it via QR​

# create the instance (number)
curl -X POST https://api.bzapper.com.br/instances \
  -H "Authorization: Bearer $BZ_KEY" -H "Content-Type: application/json" \
  -d '{"phone":"+5511999999999","nickname":"sales"}'

# start the connection via QR (or ?method=code for a pairing code)
curl -X POST "https://api.bzapper.com.br/instances/$ID/connect?method=qr" \
  -H "Authorization: Bearer $BZ_KEY"

The response carries qr_code. Render it as a QR image and scan it in WhatsApp under Linked devices → Link a device. Track the status:

curl "https://api.bzapper.com.br/instances/$ID" -H "Authorization: Bearer $BZ_KEY"
# status: qr_pending → connecting → connected (a fresh number enters "warming")

Tip: open the SSE stream (GET /stream) and watch the status change in real time.

3. Send your first message​

You don't need to say which number to send from — just to and body. bZapper picks a number from your pool automatically (load spreading + conversation affinity):

curl -X POST https://api.bzapper.com.br/messages/text \
  -H "Authorization: Bearer $BZ_KEY" -H "Content-Type: application/json" \
  -d '{"to":"+5511988888888","body":"Hello from bZapper! 🐝"}'
instance_id is OPTIONAL

Omit instance_id and the gateway picks the number (rotation/sticky) — the recommended path. Only pass instance_id to force a specific number. To find your numbers' ids, list the instances:

curl https://api.bzapper.com.br/instances -H "Authorization: Bearer $BZ_KEY"
# → { "data": [ { "id": "<instance_id>", "phone": "+55...", "status": "connected", ... } ] }

In the admin, the Numbers screen shows each number's instance_id with a copy button.

Done. The status envelope (message.sent/delivered/read) arrives through the webhooks and the SSE stream, with your client_reference echoed end to end.

Next: validating webhooks (HMAC).