Messages API

Send WhatsApp messages from your own code: text, media, templates, interactive messages, bulk, and scheduling, on the official WhatsApp Business API.

The Messages API lets you send WhatsApp messages straight from your backend: order updates, COD confirmations, cart recovery, support replies, anything your app already knows about. Every message runs on the official WhatsApp Business API and is charged against your wallet at your plan's per-message rate.

Authentication

Every request needs an API key in the X-API-Key header. Generate keys from the dashboard under Settings → API Keys.

curl https://your-host/api/v1/messages/send \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{ "to": "919876543210", "message": { "message_type": "text", "text": "Hi" } }'

To attribute a send to a specific agent, add the optional X-AGENT-ID header. Customer assignment, agent wallet allotment, and the ledger entry all use it, regardless of the agent bound to the API key.

curl -X POST https://your-host/api/v1/messages/send \
  -H "X-API-Key: your-api-key-here" \
  -H "X-AGENT-ID: agt_abc123" \
  -H "Content-Type: application/json" \
  -d '{ "to": "919876543210", "message": { "message_type": "text", "text": "Hi" } }'

Keep keys server-side

An API key can send messages and spend wallet balance. Treat it like a password: keep it on your server, never in client code or a public repo.

One endpoint, many message types

Every message operation in this reference hits the same endpoint, POST /api/v1/messages/send. The message_type field inside message decides how it is processed (text, image, template, button, and so on). Each operation in the sidebar documents the exact request body for one type, so you can copy a working payload instead of guessing.

Media uploads and agent assignments use their own endpoints, documented in their groups below.

The API, by group

The sidebar mirrors how these endpoints are organized. Start here:

Session Messages

Free-form replies inside the 24-hour customer service window: text, media, locations, contacts, and interactive messages.

Send Text Message: a plain text reply, the simplest call to start with.

Send Image Message: send an image with an optional caption.

Send Button Message: up to three quick-reply buttons.

Send List Message: a tappable menu of options.

Template Messages

Pre-approved templates for messaging customers outside the 24-hour window, with dynamic body and header variables and media headers.

Send Template (Basic): a template with no variables.

With Body Variables: fill {{1}}, {{2}} placeholders in the body.

With Attachment: a template with an image, video, or document header.

Bulk & Utilities

Send Bulk Message: the same message to up to 50 recipients in one request.

Media

Upload Media: upload an image, video, audio, or document to the media library, then reference it by id when you send.

Agent Assignments

Decide which team agents handle a given customer. Accepts the customer's internal id or its public identifier.

Assign Agents: add agents to a customer.

Replace Assignments: set the full agent list for a customer.

List Agents for a Customer: see who currently handles a customer.

Chatbots

Create and manage chatbots, and activate or deactivate their flows. The flow graph (nodes, edges, variables, versions) is built from the dashboard builder, not via the API.

Create Chatbot: create a new chatbot in DRAFT status.

List Chatbots: filter and paginate your chatbots.

Get Chatbot: fetch a chatbot with its flow graph.

Update Chatbot: change metadata, trigger, variables, settings, or status.

Delete Chatbot: remove a chatbot.

Activate Flow / Deactivate Flow: turn the chatbot's flow on or off.

Scheduling

Any message can be scheduled by adding a top-level scheduleTime field, formatted DD-MM-YYYY:HH-MM in IST (Asia/Kolkata).

{
  "to": "919876543210",
  "scheduleTime": "06-05-2026:18-15",
  "message": { "message_type": "text", "text": "Reminder: your order ships tomorrow." }
}

How scheduling behaves

The time must be in the future and within 30 days. The wallet is charged immediately at request time, not at send time, and there is no cancellation or refund. The dispatcher runs every 2 minutes, so delivery can land up to 2 minutes after the scheduled time.

Billing and rate limits

Every message sent is charged against your wallet at your plan's per-message rate. If your balance is insufficient or your subscription is inactive, the API returns 402 Payment Required. Bulk sends are charged per recipient.

Where to look next

Pick an operation from the sidebar to see its full request body, a ready-to-run example, and the response shape. Each group is collapsible, so you can jump straight to the message type you need.

Messages API

On this page