API Overview

The Whatbot API lets external systems push contacts, send messages, trigger flows, read conversations, and receive events. It’s a JSON-over-HTTPS API authenticated with a per-workspace key.

Base URL

https://api.whatbot.in/public/v1

All endpoints below are relative to this base.

Authentication

Send your API key in the X-API-Key header on every request:

X-API-Key: wa_live_xxxxxxxxxxxxxxxx

Authorization: Bearer wa_live_xxxxxxxxxxxxxxxx is accepted too. If both are present, X-API-Key wins.

The key scopes the request to a single workspace. There is no separate account id — the key is the workspace identity.

Conventions

Content type: send application/json bodies, except the CSV upload, which is multipart/form-data.
Phone numbers can be sent in any format — Whatbot normalizes them to E.164 (e.g. 98765 43210 → +919876543210). A bare 10-digit number is treated as Indian (+91); a leading 0 is dropped; a leading + or 00 is kept as the country code. Send the country code for any non-Indian number.
Several WhatsApp numbers: a workspace can hold more than one number. Endpoints that start a conversation (send a message, trigger a flow) take an optional from — see Send a Message.
Timestamps are ISO 8601 in UTC.
Phone masking: responses carry full phone numbers unless a workspace admin turns on Also mask the public API, webhooks and MCP tools on the Privacy settings page (/settings/privacy, linked from Settings → Role Based Access). With it on, the phone / phone_number / wa_id fields on the read endpoints (conversations, calls, orders, flow executions, contact activity) come back masked. Webhook payloads currently carry the full number either way.

Errors

Standard HTTP status codes. Error bodies are JSON with a detail field — usually a string; a list of field errors on a 422 validation error; or, for the cases your code is expected to branch on, an object carrying an error code (e.g. window_closed). A few codes sit next to detail at the top level instead: error on a 402, code: "whatsapp_not_connected" on a 424.

Status	Meaning
`200`	Success
`400`	The request named something that is not yours or not set up — e.g. a `from` number this workspace doesn’t hold, or no catalog connected
`401`	Missing or invalid API key (`Missing API key` / `Invalid API key`)
`402`	The workspace cannot send right now: its prepaid wallet balance is too low (top-level `error: "insufficient_balance"`, with `balance` and `required`), or its plan is not active
`403`	Valid key, but not allowed — e.g. a media path from another workspace, or a call without permission
`404`	The id you passed doesn’t exist in this workspace
`409`	Conflict with current state — e.g. the 24-hour window is closed, or the number already has a flow running
`422`	Validation error (bad body shape, invalid phone number, missing required field)
`424`	This workspace has no WhatsApp number connected
`429`	Call-permission request limit reached (see Voice Calls)
`502`	WhatsApp rejected the request (e.g. a send). Usually permanent — fix the cause rather than retrying
`5xx`	Server error — safe to retry idempotent calls

{
  "detail": [
    { "type": "list_type", "loc": ["body"], "msg": "Input should be a valid list" }
  ]
}

Endpoints

Upsert contacts POST /contacts · POST /contacts/tag

Import CSV POST /contacts/csv

Contact activity GET /contacts/whatsapp-activity

Send message POST /messages

Messaging window GET /messaging-window

Templates GET /templates

List conversations GET /conversations

List messages GET /conversations/{id}/messages

Inbound media GET /media

Flows GET /flows · POST /flows/{ref}/trigger

Segments GET · POST · DELETE /segments

AI agent knowledge POST /agents/{id}/knowledge

Team GET · POST /team

Webhooks POST · GET · DELETE /webhooks

Voice calls /calls

Catalog /catalog