Skip to content
Messages

List messages

GET
/{phone_number_id}/messages
const url = 'https://api.kirimdev.com/v1/106540352242922/messages?conversation_id=cnv_01HXYZABCDEFGHJKMNPQRSTVWX&direction=inbound&status=pending&created_after=2026-09-10T00%3A00%3A00.000Z&created_before=2026-09-11T00%3A00%3A00.000Z&limit=25&cursor=eyJpZCI6IjAxSFhZWkFCQ0RFRkdISktNTlBRUlNUVldYIiwidHMiOiIyMDI2LTA5LTEwVDA5OjAwOjAwLjAwMFoifQ';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}

List messages for the WhatsApp account identified by phone_number_id. Filter by conversation_id, direction, status, or a created_after/created_before window.

phone_number_id
required

Meta WhatsApp Business phone_number_id of the connected account that should send / own this resource. Discoverable via GET /v1/accounts (returned as phone_number_id on each row).

string
/^\d{6,20}$/
Example
106540352242922

Meta WhatsApp Business phone_number_id of the connected account that should send / own this resource. Discoverable via GET /v1/accounts (returned as phone_number_id on each row).

conversation_id

Return messages from one public inbox conversation. Unknown or cross-account IDs produce an empty list.

string
/^cnv_[0-9A-HJKMNP-TV-Z]{26}$/
Example
cnv_01HXYZABCDEFGHJKMNPQRSTVWX

Return messages from one public inbox conversation. Unknown or cross-account IDs produce an empty list.

direction

Filter messages received from contacts (inbound) or sent by your business (outbound).

string
Allowed values: inbound outbound
Example
inbound

Filter messages received from contacts (inbound) or sent by your business (outbound).

status

Filter by the latest persisted delivery state.

string
Allowed values: pending sent delivered read failed
Example
delivered

Filter by the latest persisted delivery state.

created_after

Return messages created strictly after this ISO 8601 instant.

string format: date-time
Example
2026-09-10T00:00:00.000Z

Return messages created strictly after this ISO 8601 instant.

created_before

Return messages created strictly before this ISO 8601 instant.

string format: date-time
Example
2026-09-11T00:00:00.000Z

Return messages created strictly before this ISO 8601 instant.

limit

Number of items to return. Defaults to 25; minimum 1 and maximum 100.

string
default: 25 /^\d+$/
Example
25

Number of items to return. Defaults to 25; minimum 1 and maximum 100.

cursor

Opaque continuation token from the previous response’s next_cursor. Pass it unchanged and keep all other filters the same.

string
>= 1 characters
Example
eyJpZCI6IjAxSFhZWkFCQ0RFRkdISktNTlBRUlNUVldYIiwidHMiOiIyMDI2LTA5LTEwVDA5OjAwOjAwLjAwMFoifQ

Opaque continuation token from the previous response’s next_cursor. Pass it unchanged and keep all other filters the same.

Message list

Media type application/json
object
data
required

Items in this page, ordered as documented by the operation.

Array<object>
object
id
required
string
object
required
string
Allowed values: message
conversation_id
required
string
to
required
string | null
direction
required
string
Allowed values: inbound outbound
type
required
string
content
required
string | null
media_url
required
string | null
status
required
string
Allowed values: pending sent delivered read failed
created_at
required
string format: date-time
unsupported
object
type
required

Meta-reported sub-kind. Current values include edit (contact edited a message; Meta refused to forward the new body) and unknown (message type Meta itself cannot classify). Kept open-string because Meta may introduce new values (view_once, poll, …).

string
error
object
code
required

Stable Kirim error code. Known values include outside_24h_window, marketing_opted_out, marketing_blocked_by_user, recipient_unavailable, unsupported_message_type, account_restricted, account_locked, consent_required, customer_suspended, contact_blocked, permission_revoked, auth_expired, app_rate_limited, account_rate_limited, template_not_found, template_paused, template_policy_violation, flow_blocked, media_upload_failed, media_download_failed, undeliverable, policy_violation, subscription_inactive, upstream_error.

string
message
required
string
provider_code
required
number | null
has_more
required

Whether another page is available.

boolean
next_cursor
required

Pass this value unchanged as cursor to fetch the next page. null marks the final page.

string | null
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example success

Most recent inbox messages

{
"data": [
{
"id": "msg_01HXYZABCDEFGHJKMNPQRSTVWX",
"object": "message",
"conversation_id": "cnv_01HXYZABCDEFGHJKMNPQRSTVWX",
"to": "+628123456789",
"bsuid": null,
"parent_bsuid": null,
"username": null,
"direction": "inbound",
"type": "text",
"content": "Halo, apakah pesanan saya sudah dikirim?",
"media_url": null,
"status": "delivered",
"created_at": "2026-09-10T09:00:00.000Z"
}
],
"has_more": false,
"next_cursor": null,
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}

Validation failure

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

A field value is invalid.

{
"error": {
"type": "invalid_request_error",
"code": "invalid_field_value",
"message": "A field value is invalid.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Authentication failure

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

The provided API key is invalid.

{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is invalid.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Resource not found

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

Resource not found.

{
"error": {
"type": "not_found",
"code": "resource_not_found",
"message": "Resource not found.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Semantic failure (e.g. idempotency key reuse, pre-send compliance guard, media not found)

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

The WhatsApp number is not connected. Check its status in the Kirimdev dashboard and reconnect it if needed.

{
"error": {
"type": "invalid_request_error",
"code": "whatsapp_number_not_verified",
"message": "The WhatsApp number is not connected. Check its status in the Kirimdev dashboard and reconnect it if needed.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Rate limit exceeded

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

Rate limit exceeded.

{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}

Internal server error

Media type application/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error api_error
code
required
string
message
required

Human-readable explanation of the error.

string
param

Request field associated with the error, when applicable.

string
request_id
required

Unique request identifier to include when contacting support.

string
Examples
Example default

An unexpected error occurred.

{
"error": {
"type": "api_error",
"code": "internal_error",
"message": "An unexpected error occurred.",
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
}