> 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/list-messages.md).

# List messages

Lists messages across your business, or in one conversation, with each message's contact and inbox.

**Without date filters, only today's messages are returned** (in your `X-User-Timezone`, default Asia/Jakarta). With only a start date, results run to the end of today.

```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":[]},{"BearerAuth":[]}],"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."},"BearerAuth":{"type":"http","scheme":"bearer","description":"The same Cekat API key, sent as `Authorization: Bearer YOUR_API_KEY`. Accepted only by endpoints under `/api/...`."}},"parameters":{"StartDate":{"name":"start_date","in":"query","required":false,"description":"Only include items created on or after this date (`YYYY-MM-DD`). Cannot be combined with `start_datetime`.","schema":{"type":"string","format":"date"}},"EndDate":{"name":"end_date","in":"query","required":false,"description":"Only include items created on or before the end of this date (`YYYY-MM-DD`). Cannot be combined with `end_datetime`.","schema":{"type":"string","format":"date"}},"StartDatetime":{"name":"start_datetime","in":"query","required":false,"description":"Only include items created at or after this time (`YYYY-MM-DDTHH:mm:ss`, optional offset such as `+07:00` or `Z`). Cannot be combined with `start_date`.","schema":{"type":"string"}},"EndDatetime":{"name":"end_datetime","in":"query","required":false,"description":"Only include items created at or before this time (`YYYY-MM-DDTHH:mm:ss`, optional offset). Cannot be combined with `end_date`.","schema":{"type":"string"}},"Version":{"name":"version","in":"query","required":false,"description":"Response format version in `YYYY-MM-DD` format. Use `2026-05-22` or later to get `created_at` as an ISO 8601 UTC timestamp.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"UserTimezone":{"name":"X-User-Timezone","in":"header","required":false,"description":"IANA time zone used to read date filters that have no offset. Defaults to `Asia/Jakarta`.","schema":{"type":"string"}}},"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"}}}}},"ApiError":{"type":"object","description":"Error body returned by the `/api/...` endpoints.","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"statusCode":{"type":"integer"},"error":{"type":"object","properties":{"message":{"type":"string"}}},"correlationId":{"type":"string","description":"Request ID. Include it when contacting Cekat support."}}},"RateLimitError":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"ApiUnauthorized":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"TooManyRequests":{"description":"Rate limit exceeded. Wait and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}},"paths":{"/api/messages":{"get":{"tags":["Message"],"operationId":"ListMessages","summary":"List messages","description":"Lists messages across your business, or in one conversation, with each message's contact and inbox.\n\n**Without date filters, only today's messages are returned** (in your `X-User-Timezone`, default Asia/Jakarta). With only a start date, results run to the end of today.\n","parameters":[{"name":"conversation_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":2000,"default":100}},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"is_ads","in":"query","required":false,"description":"`true` to return only contact messages that came from a click-to-WhatsApp ad.","schema":{"type":"boolean","default":false}},{"name":"is_template","in":"query","required":false,"description":"`true` for template messages only, `false` to exclude them.","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"},{"$ref":"#/components/parameters/StartDatetime"},{"$ref":"#/components/parameters/EndDatetime"},{"$ref":"#/components/parameters/Version"},{"$ref":"#/components/parameters/UserTimezone"}],"responses":{"200":{"description":"A page of messages.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}},"metadata":{"type":"object","properties":{"pagination":{"type":"object","properties":{"current_page":{"type":"integer"},"current_items":{"type":"integer"},"total_page":{"type":"integer"},"total_items":{"type":"integer"}}}}}}}}}},"400":{"description":"A filter is invalid, or `limit` is above 2000.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/ApiUnauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```