Sending

Send a text message

POST /messages
Idempotency-Key: order-123-v1

{
  "instance_id": "ins_…",
  "type": "text",
  "to": "9665xxxxxxxx",
  "text": "Hello",
  "client_reference": "order-123",
  "options": { "delay_profile": "normal" }
}

text: required, up to 8192 characters (counted as characters, not bytes; Arabic and English alike). Longer returns 422 INVALID_TEXT.

Authorization header and instance_id in the body — both required and must belong to the same session.

Field to: digits only with country code, no + or leading zeros (e.g. 9665xxxxxxxx).

options.delay_profile (optional): random delay before sending to reduce ban risk — none = no delay, normal = 2–12 s (default), cautious = 25–60 s, high_protection = 61–180 s. Use none only for urgent messages such as verification codes; heavy instant sending raises ban risk.

client_reference: your own reference up to 128 characters (optional) — returned in GET and in the message.unknown event.

Send response — request accepted (not WhatsApp delivery)

HTTP 202
{
  "success": true,
  "message_id": "msg_…",
  "status": "queued",
  "request_id": "…"
}

The request is queued and answered immediately with 202, without waiting for WhatsApp. Track the result with GET or via webhook.

HTTP 200 when the same Idempotency-Key and body are retried — safe, no duplicate message.

Media — image, video, audio, document

// A) upload, then send by media_id
POST /media   (multipart/form-data, field: file, max 50 MB)
→ 201 { "media_id": "med_…", "mime_type": "application/pdf", "file_name": "…", "size_bytes": 1024, "url": "https://…/m/…", "expires_at": "…" }

POST /messages
{
  "instance_id": "ins_…",
  "type": "media",
  "to": "9665xxxxxxxx",
  "media": { "media_id": "med_…", "caption": "Invoice" }
}

// B) send from your public URL
{
  "instance_id": "ins_…",
  "type": "media",
  "to": "9665xxxxxxxx",
  "media": { "url": "https://example.com/file.pdf", "filename": "file.pdf", "caption": "…" }
}

Use media_id from an upload or a public url (exactly one). caption is optional, up to 2048 characters. Uploaded and received files are auto-deleted after the retention period; links are temporary until expires_at.

To send the same file to many numbers: upload it once and use the same media_id for every number (or in a batch). Uploading the same file with the same name again returns the same media_id, and uploads are limited to 30 files per minute per session.

Batch send

POST /messages/batch

{
  "instance_id": "ins_…",
  "messages": [
    { "type": "text", "to": "9665xxxxxxxx", "text": "Hello" },
    { "type": "media", "to": "9665xxxxxxxx", "media": { "media_id": "med_…" } }
  ]
}

Up to 50 messages per request; one result per item in results[] (ok and message_id, or error). Idempotency-Key and delay_profile do not apply to batches.