Generic REST clients
Any HTTP client works. Conventions:
| Topic | Convention |
|---|---|
| Base URL | https://api.whatstig.com (self-hosted: your PUBLIC_API_URL) |
| Auth | Authorization: Bearer wt_live_... |
| Content type | application/json (except media upload: multipart/form-data with a file field) |
| Idempotency | Idempotency-Key header, required for POST /v1/messages |
| Request ID | Optional X-Request-Id; always returned in the response |
| Errors | { "error": { "code", "message", "details", "requestId" } } |
| Pagination | ?limit=&cursor=; response pagination.nextCursor |
| Time | ISO 8601 UTC strings |
| Phone numbers | International format; responses use E.164 with + |
Postman
Import docs/postman/whatstig.postman_collection.json (generated from the OpenAPI contract). Set the collection
variables baseUrl and apiKey.
OpenAPI
GET /api/openapi.json (OpenAPI 3.1). Generate a client in any language, e.g.:
npx @openapitools/openapi-generator-cli generate -i https://api.whatstig.com/api/openapi.json -g java -o whatstig-java
Interactive reference: /api/docs.
curl walkthrough
KEY=wt_live_...; WT=https://api.whatstig.com
curl -s $WT/v1/project -H "Authorization: Bearer $KEY"
curl -s -X POST $WT/v1/instances -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: create-tenant-101" -d '{"name":"School A WhatsApp","externalReference":"tenant-101"}'
curl -s -X POST $WT/v1/instances/$ID/connect -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"method":"qr"}'
curl -s $WT/v1/instances/$ID/qr -H "Authorization: Bearer $KEY"
curl -s $WT/v1/instances/$ID/status -H "Authorization: Bearer $KEY"
curl -s -X POST $WT/v1/media -H "Authorization: Bearer $KEY" -F "file=@photo.jpg;type=image/jpeg"
curl -s -X POST $WT/v1/messages -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: n-1" \
-d '{"instanceId":"'$ID'","recipient":"923001234567","type":"text","content":{"text":"Hello"}}'
curl -s "$WT/v1/messages?status=FAILED&limit=50" -H "Authorization: Bearer $KEY"
curl -s "$WT/v1/events?type=message.received" -H "Authorization: Bearer $KEY"