Skip to main content

​
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

  1. Go to Settings → API Keys → Create Key
  2. Give it a descriptive name and optional expiry date
  3. 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 ParamTypeDescription
searchstringSearch by name or phone
tagstringFilter by tag
pagenumberPage number (default: 1)
limitnumberResults 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 ParamTypeDescription
statusstringOPEN / ASSIGNED / RESOLVED
pagenumberPage 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:
TypeRequired Fields
texttext
imagemediaUrl or mediaId
documentmediaUrl, filename
audiomediaUrl
videomediaUrl
templatetemplateName, language, components
interactiveinteractive (button/list format)
locationlatitude, longitude, name
contactcontacts array
reactionmessageId, emoji

​
Media

POST /api/whatsapp-api/media 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

ScopeLimit
API requests120 requests/minute per IP
Message sends20 messages/hour per recipient
Broadcast1,000 contacts/broadcast on Growth; unlimited on Pro
File uploads16MB 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 StatusMeaning
200Success
201Created
400Bad request (missing or invalid fields)
401Unauthorized (missing/expired API key)
403Forbidden (insufficient permissions)
404Not found
409Conflict (duplicate resource)
429Rate limit exceeded
500Server error
Error responses always include a JSON body: 
{
  "error": "Human-readable error message"
}