Documentation Index
Fetch the complete documentation index at: https://docs.kaanha.ai/llms.txt
Use this file to discover all available pages before exploring further.
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"
}
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) |
/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 |
/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?"
}
| 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 |
POST /api/whatsapp-api/media
Upload media. Returns a mediaId for use in message sends.
Content-Type: multipart/form-data
Body: file (max 16MB)
/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
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 |
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": "Human-readable error message"
}
