Developers
API reference & error codes
Updated 31 May 2026
A consolidated reference for the Baat developer API. For step-by-step guides, see the other articles in this section.
Base URLs
| Environment | Host |
|---|---|
| Production | https://api.baat.ai |
| Staging | https://stageapi.baat.ai |
Authentication
Pass your key in the X-API-KEY header on every request. Keys look like bk_live_ followed by 34 characters and are issued per organization.
X-API-KEY: bk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Endpoints
| Method | Path | Scope | Purpose |
|---|---|---|---|
POST | /m1/whatsapp/messages | messages:send | Send a WhatsApp template message. |
POST | /v1/remote/contacts | contacts:write | Create a contact. |
GET | /v1/remote/account/channels | channels:read | List connected WhatsApp channels. |
GET | /v1/remote/account/channels/{channelId}/whatsapp-templates | templates:read | List approved templates on a channel. |
API keys and webhook subscriptions are managed from the dashboard (Developers section), not through these key-authenticated endpoints.
HTTP status codes
| Code | Meaning |
|---|---|
200 OK | Request succeeded (reads). |
201 Created | Resource created (e.g. a contact). |
202 Accepted | Message accepted and queued for delivery. |
400 Bad Request | Invalid or malformed request. |
401 Unauthorized | Missing, unknown, inactive or expired API key. |
403 Forbidden | Key lacks the required scope (insufficient_scope). |
409 Conflict | Duplicate resource (e.g. contact phone number with ignore-duplicate=false). |
500 Internal Server Error | Unexpected error on Baat’s side — safe to retry. |
Webhook delivery
| Aspect | Detail |
|---|---|
| Method | POST with Content-Type: application/json |
| Signature header | X-Baat-Signature: sha256= — HMAC-SHA256 of the raw body, keyed with the signing secret. |
| Events | contact.created, contact.updated, conversation.opened, conversation.closed, flow_response.submitted |
| Payload | { event, occurred_at, organization_id, data } |
| Retries | Up to 8 attempts with backoff (10 min → 7 days), then marked Failed. |
Build handlers to be idempotent and verify the X-Baat-Signature on every webhook. Treat API keys and signing secrets as secrets — store them in a vault, never in source control, and rotate on suspicion of exposure.