API Overview

The Whatbot API lets external systems push contacts, send messages, and read conversations. It’s a small, JSON-over-HTTPS API authenticated with a per-tenant key.

Base URL

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

All endpoints below are relative to this base.

Authentication

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

X-API-Key: wa_live_xxxxxxxxxxxxxxxx

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

Conventions

Field	Type	Required	Description
Content-Type	header		Use `application/json` for JSON bodies, or `multipart/form-data` for the CSV upload.

Phone numbers can be sent in any format — Whatbot normalizes them to E.164 (e.g. 98765 43210 → +919876543210). A default country code is applied to bare 10-digit numbers.
Upsert semantics: contacts are keyed on phone. Re-sending an existing phone updates that contact rather than creating a duplicate.
Timestamps are ISO 8601 in UTC.

Errors

Standard HTTP status codes. Error bodies are JSON with a detail field.

Status	Meaning
`200`	Success
`401`	Missing or invalid `X-API-Key`
`403`	Key valid but not permitted for this resource
`422`	Validation error (e.g. bad body shape or invalid phone)
`429`	Rate limited — retry with backoff
`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

Import CSV POST /contacts/csv

Send message POST /messages

List conversations GET /conversations