API Reference

Kaanha AI provides a REST API for programmatic access to contacts, conversations, messages, and more. All API endpoints use Bearer token authentication via API Keys.

Authentication

Create an API Key

Go to Settings → API Keys → Create Key
Give it a descriptive name and optional expiry date
Copy the key immediately — it won’t be shown again

Using the API Key

Include the key in all requests:

Authorization: Bearer YOUR_API_KEY

Base URL

https://app.kaanha.ai/api/whatsapp-api

Endpoints

Status

GET /api/whatsapp-api/status Returns WhatsApp connection status for the authenticated organization.

{
  "connected": true,
  "phoneNumber": "+91 98765 43210",
  "connectionType": "cloud_api",
  "businessName": "Acme Corp"
}

Contacts

GET /api/whatsapp-api/contacts List contacts with optional filtering.

Query Param	Type	Description
`search`	string	Search by name or phone
`tag`	string	Filter by tag
`page`	number	Page number (default: 1)
`limit`	number	Results per page (default: 20, max: 100)

POST /api/whatsapp-api/contacts Create a new contact.

{
  "phone": "+919876543210",
  "name": "John Doe",
  "email": "john@example.com",
  "tags": ["vip", "retail"],
  "optedIn": true
}

Conversations

GET /api/whatsapp-api/chats List conversations.

Query Param	Type	Description
`status`	string	OPEN / ASSIGNED / RESOLVED
`page`	number	Page number

GET /api/whatsapp-api/chats/{conversationId} Get a single conversation with recent messages.

Messages

GET /api/whatsapp-api/messages List recent messages across all conversations. POST /api/whatsapp-api/send Send a message to a contact.

{
  "to": "+919876543210",
  "type": "text",
  "text": "Hello! How can I help you today?"
}

Supported message types:

Type	Required Fields
`text`	`text`
`image`	`mediaUrl` or `mediaId`
`document`	`mediaUrl`, `filename`
`audio`	`mediaUrl`
`video`	`mediaUrl`
`template`	`templateName`, `language`, `components`
`interactive`	`interactive` (button/list format)
`location`	`latitude`, `longitude`, `name`
`contact`	`contacts` array
`reaction`	`messageId`, `emoji`

Media

POST /api/media/upload Upload media. Returns a mediaId for use in message sends.

Content-Type: multipart/form-data
Body: file (max 16MB)

Supported types: images (JPEG, PNG, WebP), documents (PDF, DOCX), audio (MP3, OGG), video (MP4) GET /api/media/{mediaId} Download/stream a media file by ID.

MCP Server (Claude / AI Assistants)

Kaanha AI exposes an MCP (Model Context Protocol) server for integration with Claude and other AI assistants.

stdio Transport (Claude Desktop / Claude Code)

# Register with Claude (from your local clone of the platform)
claude mcp add wasender -- node src/mcp/server.mjs

Available tools: list_contacts, get_contact, create_contact, list_conversations, get_conversation, send_message, list_templates, send_broadcast, get_analytics, list_ai_agents, list_quick_replies, create_payment_link

SSE Transport (Network Clients)

GET https://app.kaanha.ai/api/mcp/sse
Authorization: Bearer YOUR_API_KEY

Rate Limits

Scope	Limit
API requests	120 requests/minute per IP
Message sends	20 messages/hour per recipient
Broadcast	1,000 contacts/broadcast on Starter; unlimited on Pro
File uploads	16MB max per file

Rate limit responses return HTTP 429 with a Retry-After header.

Webhooks (Outgoing)

Kaanha AI can push events to your server. See Webhooks Guide.

Error Codes

HTTP Status	Meaning
`200`	Success
`201`	Created
`400`	Bad request (missing or invalid fields)
`401`	Unauthorized (missing/expired API key)
`403`	Forbidden (insufficient permissions)
`404`	Not found
`409`	Conflict (duplicate resource)
`429`	Rate limit exceeded
`500`	Server error

Error responses always include a JSON body:

{
  "error": "Human-readable error message"
}

​API Reference

​Authentication

​Create an API Key

​Using the API Key

​Base URL

​Endpoints

​Status

​Contacts

​Conversations

​Messages

​Media

​MCP Server (Claude / AI Assistants)

​stdio Transport (Claude Desktop / Claude Code)

​SSE Transport (Network Clients)

​Rate Limits

​Webhooks (Outgoing)

​Error Codes