API conventions
The API uses HTTPS, standard HTTP methods and status codes, and JSON request and response bodies. Version 2 is available under /api/v2.
Request headers
| Header | When to send it |
|---|---|
Authorization: Bearer <token> | Every authenticated API request. |
Accept: application/json | All JSON requests, including requests that may fail validation. |
Content-Type: application/json | JSON request bodies. For file uploads, use multipart/form-data with a boundary generated by your HTTP client. |
Idempotency-Key | Required when creating customers or connections, sending messages, or sending group messages. |
Identifiers
Use the IDs returned by the API. Connection IDs, customer IDs, and outbound message IDs are UUIDs. Group IDs and inbound history IDs are internal identifiers. Do not substitute a WhatsApp JID for an internal group ID.
For replies and reactions, use the original WhatsApp message_id from retained history, rather than an outbound API message UUID or numeric history-row ID.
Response envelopes
Resource responses use a data field. Collection endpoints return a data array and endpoint-specific pagination information. Some action endpoints return a confirmation such as revoked: true or disabled: true.
Pagination
| Endpoint family | Request | Response |
|---|---|---|
| Connections, conversations, retained messages, group messages, receipts | after_id and limit, where supported | next_after_id; null when no next page is available |
| Groups | page and per_page | meta.current_page, meta.last_page, meta.total |
| Customers | page; 50 items per page | meta.page and meta.last_page |
Receipt cursors paginate participant rows; they do not act as a change feed for updates to previously returned rows. Use receipt webhooks or reload pages to refresh earlier receipt statuses.
Timestamps and null values
Timestamps use ISO 8601 with a timezone offset. A null delivery or read timestamp means that Jawib has not recorded that event; it does not prove that the recipient has not received or read the message.
OpenAPI specification
The downloadable reference uses OpenAPI 3.1.0 and includes authentication, path parameters, request schemas, media types, and response definitions. Use it to inspect the contract in your API tooling.