Core Concepts

This page covers the things that apply to every endpoint. Read it once and the rest of the docs will feel a lot easier.

Base URL

Every endpoint lives under:

https://api-zawa.azickri.com

Requests and responses are JSON. For endpoints that take a body, remember to send Content-Type: application/json.

Sessions: id + session-id

Zawa doesn't use API keys or tokens. Instead, each WhatsApp number has one session, identified by two values you get from Create Session:

Header	Value	Example
id	id from Create Session	68b3f0a2c1d4e5f6a7b8c9d0
session-id	sessionId from Create Session	0b2f7059-8a90-4f6d-8684-b0e1ce6f0310

Every endpoint except POST /session requires both headers:

curl "https://api-zawa.azickri.com/group" \
  -H "id: 68b3f0a2c1d4e5f6a7b8c9d0" \
  -H "session-id: 0b2f7059-8a90-4f6d-8684-b0e1ce6f0310"

Treat them like a password

Anyone with your id and session-id can send messages from your number. Keep them on your server, never in a frontend or mobile app.

One session = one WhatsApp number. To use several numbers, create several sessions. Keep in mind that WhatsApp only allows a few linked devices per number (currently up to 4), and a Zawa session takes one of those slots.

Session Lifecycle

A session is "alive": it connects, drops, reconnects, and is eventually deleted. Here's what happens in each situation:

Situation	What happens
Just created	isConnected: false. A few seconds later qrcode is filled in.
QR not scanned for about 3 minutes	The session is deleted automatically. The next request gets 404 session not found.
QR scanned	isConnected: true, qrcode is empty, name and picture are filled in.
Connection drops briefly	Zawa reconnects on its own with growing delays (0s, 2s, 4s, and so on, up to 30s).
You log out from your phone	The link is removed and Zawa immediately prepares a new QR code. Scan it to reconnect.
The number is opened elsewhere or banned by WhatsApp	The session stops and doesn't reconnect. Try Reset Session.
Disconnected for more than 30 minutes	The session is deleted automatically, along with all of its data.
You call Delete Session	The linked device is logged out from your phone and all session data is deleted.

Keep an eye on the connection

Get Session is safe to call at any time, even while the session is disconnected. Check isConnected regularly (every few minutes, say) so you know when to scan again, before the 30 minutes are up.

Numbers, Groups, and Channels

Send Message and Send Typing need a recipient. Fill in one of these fields:

Field	Format	Example	Where to get it
phone	Number in international format	6281234567890	The recipient's number
group	Group ID	[email protected]	Get Groups
newsletter	Channel ID	120363000000000000@newsletter	Get Channels

To save you some hassle, Zawa tidies up the number you send:

• Anything that isn't a digit is removed, so +62 812-3456-7890 works fine.
• A leading 0 is replaced with 62, so 081234567890 becomes 6281234567890.
• After tidying, the number must have at least 8 digits. Otherwise you get 400 invalid receiver.

A leading 0 always means Indonesia

For numbers outside Indonesia, always include the country code. For example, use 447911123456 for the UK, not 07911123456.

A few small things people often miss:

• Zawa does not check whether the recipient is on WhatsApp. If the number has no WhatsApp account, you still get a messageId, but the message won't go anywhere.
• You can only send to channels you manage (isOwner: true in Get Channels).
• If you fill in more than one recipient field, Zawa uses group first, then newsletter, then phone.

Sending Media From a URL

Zawa doesn't accept file uploads. You just pass a URL, and Zawa downloads the file and sends it to WhatsApp. To keep things smooth:

• The URL must be public and point directly at the file, with no login required. Preview pages (like a Google Drive share page) won't work.
• Stick to safe formats. Zawa sends images as JPEG, video as MP4, and audio as MP3. Use source files in those formats so the result looks right.
• mimetype is still required, for example image/jpeg, video/mp4, audio/mpeg, or application/pdf.
• Thumbnails are optional. If thumbnail is empty, images and videos use Zawa's default thumbnail. For video statuses, the thumbnail is generated from the video automatically.

There are also time limits:

Limit	Value
File server must start sending data	60 seconds
Download stalls (no data arriving)	30 seconds
Total time to send one message or status	4 minutes
JSON body size	25 MB

Response Format

On success you get status 200 with a JSON object. Endpoints that return a list always wrap it in docs:

{
  "docs": [
    { "id": "[email protected]", "name": "Zawa Community" }
  ]
}

Errors always look the same:

{
  "statusCode": 400,
  "message": "invalid header"
}

If several fields are wrong at once, their messages are joined with a newline (\n) in message. The full list of errors and how to fix them is in Errors & Fixes.

Other Limits Worth Knowing

• The typing indicator from Send Typing only shows for 5 seconds.
• Get Channel Messages returns 100 messages per page.
• Zawa doesn't store incoming messages and currently has no webhook. The old webhook is deprecated.