Skip to content
Conversations

List conversations

GET
/{phone_number_id}/conversations
const url = 'https://api.kirimdev.com/v1/106540352242922/conversations?status=open&contact_id=ctc_01HXYZABCDEFGHJKMNPQRSTVWX&updated_since=2026-09-10T00%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 conversations for the WhatsApp account identified by phone_number_id. Default order: newest-active first by last_message_at (NULLS LAST). With updated_since, order switches to updated_at DESC so assignment/status changes are not buried. Supports short-lived server-side caching, and ETag/If-None-Match for unchanged responses.

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).

status

Filter by inbox lifecycle state.

string
Allowed values: open resolved pending
Example
open

Filter by inbox lifecycle state.

contact_id

Return conversations linked to this public contact ID.

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

Return conversations linked to this public contact ID.

updated_since

Return conversations updated strictly after this ISO 8601 instant. Results then order by updated_at newest first.

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

Return conversations updated strictly after this ISO 8601 instant. Results then order by updated_at newest first.

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.

Conversation 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: conversation
status
required
string
Allowed values: open resolved pending
contact
required
object
id
required
string
phone_number
required
string | null
name
required
string | null
whatsapp_account
required
object
phone_number
required
string | null
phone_number_id
required

Meta business_phone_number_id — use as the {phone_number_id} path segment in /v1/{phone_number_id}/... endpoints.

string | null
customer
required

End-customer (multi-tenant platform mode) that owns this account. NULL for direct-org accounts.

object
id
required
string
name
required
string
assignee
required
object
id
required
string
name
required
string | null
email
required
string | null
labels
required

Labels currently attached to this conversation.

Array<object>
object
id
required
string
name
required
string
color
required
string
Allowed values: gray red orange amber yellow lime green emerald teal sky blue violet pink
unread_count
required
integer
last_message_at
required
string | null format: date-time
last_inbound_at
required
string | null format: date-time
created_at
required
string format: date-time
updated_at
required
string format: date-time
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
Example
{
"data": [
{
"id": "cnv_01HXYZABCDEFGHJKMNPQRSTVWX",
"object": "conversation",
"status": "open",
"whatsapp_account": {
"phone_number_id": "106540352242922",
"customer": {
"id": "cus_01HXYZABCDEFGHJKMNPQRSTVWX"
}
},
"labels": [
{
"id": "lbl_01HXYZABCDEFGHJKMNPQRSTVWX",
"name": "VIP",
"color": "gray"
}
]
}
],
"has_more": false,
"next_cursor": null,
"request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
}
ETag
string

Weak entity tag derived from the newest updated_at in the page. Send as If-None-Match on the next poll — unchanged lists return 304.

Not modified — request carried a matching If-None-Match ETag.

ETag
string

Same weak entity tag as the prior response.

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"
}
}