Getting started
Requests and errors
Authentication
Send your number's API token on every request:
Authorization: Bearer wat_YOUR_TOKENA token belongs to one number. It can read and send for that number only, and can't see any other number's data. All paths live under https://api.api-supp.com/v1.
Format
- Request and response bodies are JSON. The exceptions are uploading media, which takes raw file bytes, and downloading media, which returns them.
- Pagination is
limit/offset. - Timestamps are returned as
YYYY-MM-DD HH:MM:SS±HH:MM. Replace the space withTif your parser needs strict ISO-8601.
Chat ids (JIDs)
WhatsApp addresses chats with JIDs:
| Form | Example | Meaning |
|---|---|---|
| Phone | 14155550132@s.whatsapp.net | A person, by phone number |
| LID | 133144455962747@lid | A person, by WhatsApp's private id (newer accounts and many groups) |
| Group | 120363…@g.us | A group |
Where a request takes a recipient you can usually pass bare phone digits. In URLs, encode @ as %40: chat_jid=14155550132%40s.whatsapp.net.
Errors
Every error response looks like {"error": "human description"}. The status code tells you the kind:
| Code | Meaning |
|---|---|
400 | Invalid input |
401 | Missing or wrong token |
404 | Not found for this number |
409 | Conflict |
413 | Upload too large or over the storage cap |
502 | WhatsApp rejected the request |
503 | The number's WhatsApp session isn't connected right now (if it lasts, the number may need re-pairing in the portal) |
Tips
- Reuse HTTP connections (for example
requests.Session()in Python). A new TLS handshake on every call adds about 200 ms. - Sends are not retried for you. If you get a
502, decide in your code whether to try again.