Skip to content
Conversations

Update a conversation

PATCH
/{phone_number_id}/conversations/{id}
const url = 'https://api.kirimdev.com/v1/106540352242922/conversations/cnv_01HXYZABCDEFGHJKMNPQRSTVWX';
const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: '{"status":"open","assigned_to":"example"}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}

Update status (open / resolved / pending) and/or assigned_to (user id, or null to clear). At least one field must be present.

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

id
required

Public Kirimdev conversation ID.

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

Public Kirimdev conversation ID.

Media type application/json
object
status
string
Allowed values: open resolved pending
assigned_to
string | null
>= 1 characters <= 64 characters

Updated conversation

Media type application/json
object
data
required
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
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"
}
]
},
"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"
}
}