> For the complete documentation index, see [llms.txt](https://docs.cekat.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cekat.ai/api-documentation/chat/message/send-a-whatsapp-message.md).

# Send a WhatsApp message

Sends a free-form WhatsApp message in an existing conversation. WhatsApp only delivers these within 24 hours of the contact's last message; outside that window, send a template with `POST /templates/send`.

The message is queued and the response returns right away with `status: sent`. Check delivery later with `GET /messages/{message_id}`.

| `media_type`                 | What to send                                                                                                                                                                                    |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`                       | `message`                                                                                                                                                                                       |
| `image`, `video`, `document` | `file_url` (the type is also detected from the file extension), with `message` as the caption                                                                                                   |
| `location`                   | `location` with `latitude` and `longitude`, plus optional `name` and `address`                                                                                                                  |
| `button`                     | `message` and `action.buttons`: 1 to 3 buttons, each `{"type": "reply", "reply": {"id", "title"}}`; titles up to 20 characters                                                                  |
| `list`                       | `message` and `action` with `button` (up to 20 characters) and `sections`: up to 10 sections, each with a `title` (up to 24 characters) and up to 10 `rows` of `{"id", "title", "description"}` |
| `cta_url`                    | `message` and `action` `{"name": "cta_url", "parameters": {"display_text", "url"}}`; `display_text` up to 20 characters                                                                         |

`header` (`{"text"}` or `{"file_url"}`) and `footer` (text) are optional for `button`, `list` and `cta_url` messages.

```json
{"openapi":"3.0.3","info":{"title":"Cekat Open API","version":"1.0.0"},"tags":[{"name":"Message","description":"Read the messages in your conversations and send WhatsApp messages from the API.\n\nTo start a new conversation, or to message a contact who hasn't written to you in the last 24 hours, use an approved template with `POST /templates/send`. WhatsApp only allows free-form messages (`POST /messages/whatsapp`) within 24 hours of the contact's last message.\n"}],"servers":[{"url":"https://api.cekat.ai","description":"Production"}],"security":[{"CekatApiKey":[]}],"components":{"securitySchemes":{"CekatApiKey":{"type":"apiKey","in":"header","name":"api_key","description":"Your business's Cekat API key, from **Settings → Developers & API** in the Cekat dashboard (https://chat.cekat.ai/developers?section=apikeys). Available on the Business and Enterprise plans."}},"schemas":{"ChatMessage":{"type":"object","description":"A message in a conversation. Additional fields may be present.","additionalProperties":true,"properties":{"id":{"type":"string"},"conversation_id":{"type":"string","format":"uuid"},"message":{"type":"string","nullable":true},"sent_by":{"type":"string","nullable":true,"description":"ID of the sender (agent, AI agent, contact or `system`)."},"sent_by_name":{"type":"string","nullable":true},"sent_by_type":{"type":"string","description":"Who sent the message, for example `user` (the contact), `agent`, `api` or `system`."},"media_type":{"type":"string","nullable":true},"media_url":{"type":"string","nullable":true},"platform_mid":{"type":"string","nullable":true,"description":"The channel's message ID, for example the WhatsApp message ID."},"status":{"type":"string","nullable":true,"description":"Delivery status, for example `sent`, `delivered`, `read` or `failed`."},"is_template":{"type":"boolean","nullable":true},"created_at":{"type":"string","description":"ISO 8601 UTC with `version=2026-05-22` or later; otherwise `YYYY-MM-DD HH:mm:ss` in Asia/Jakarta time."},"updated_at":{"type":"string","nullable":true},"chat_credits_used":{"type":"number","nullable":true,"description":"AI credits used to generate the message, for AI replies."},"location":{"type":"object","nullable":true,"additionalProperties":true},"action":{"type":"object","nullable":true,"additionalProperties":true},"additional_data":{"type":"object","nullable":true,"additionalProperties":true,"description":"Extra data, such as the ad referral for messages that came from a click-to-WhatsApp ad."},"contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"display_name":{"type":"string"},"phone_number":{"type":"string","nullable":true},"platform_id":{"type":"string","nullable":true},"username":{"type":"string","nullable":true},"type":{"type":"string"}}},"inbox":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"business_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"phone_number":{"type":"string","nullable":true},"type":{"type":"string"}}}}},"Error":{"type":"object","description":"Error body returned by the `/templates` endpoints.","properties":{"success":{"type":"boolean"},"status_code":{"type":"integer"},"error":{"type":"object","properties":{"message":{"type":"string"}}}}},"RateLimitError":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate limit exceeded. Wait and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}},"paths":{"/messages/whatsapp":{"post":{"tags":["Message"],"operationId":"SendWhatsAppMessage","summary":"Send a WhatsApp message","description":"Sends a free-form WhatsApp message in an existing conversation. WhatsApp only delivers these within 24 hours of the contact's last message; outside that window, send a template with `POST /templates/send`.\n\nThe message is queued and the response returns right away with `status: sent`. Check delivery later with `GET /messages/{message_id}`.\n\n| `media_type` | What to send |\n| --- | --- |\n| `text` | `message` |\n| `image`, `video`, `document` | `file_url` (the type is also detected from the file extension), with `message` as the caption |\n| `location` | `location` with `latitude` and `longitude`, plus optional `name` and `address` |\n| `button` | `message` and `action.buttons`: 1 to 3 buttons, each `{\"type\": \"reply\", \"reply\": {\"id\", \"title\"}}`; titles up to 20 characters |\n| `list` | `message` and `action` with `button` (up to 20 characters) and `sections`: up to 10 sections, each with a `title` (up to 24 characters) and up to 10 `rows` of `{\"id\", \"title\", \"description\"}` |\n| `cta_url` | `message` and `action` `{\"name\": \"cta_url\", \"parameters\": {\"display_text\", \"url\"}}`; `display_text` up to 20 characters |\n\n`header` (`{\"text\"}` or `{\"file_url\"}`) and `footer` (text) are optional for `button`, `list` and `cta_url` messages.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversation_id"],"properties":{"conversation_id":{"type":"string","format":"uuid","description":"A WhatsApp conversation."},"message":{"type":"string","description":"Message text, or the caption for media."},"media_type":{"type":"string","default":"text","enum":["text","image","video","document","location","button","list","cta_url"]},"file_url":{"type":"string","format":"uri","description":"Public URL of the image, video or document to send."},"header":{"type":"object","properties":{"text":{"type":"string"},"file_url":{"type":"string","format":"uri"}}},"footer":{"type":"string"},"action":{"type":"object","additionalProperties":true,"description":"Buttons, list or link, depending on `media_type`."},"location":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"},"name":{"type":"string"},"address":{"type":"string"}}}}}}}},"responses":{"201":{"description":"Message queued for sending.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status_code":{"type":"integer"},"data":{"$ref":"#/components/schemas/ChatMessage"}}}}}},"400":{"description":"The message is invalid, contains a blocked phrase, the contact is blocked, or the conversation has no WhatsApp number.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"The conversation was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```