import { PeriskopeApi } from '@periskope/periskope-client';
const client = new PeriskopeApi({
authToken: 'YOUR_API_KEY',
phone: '919876543210', // the phone to act with (x-phone)
});
async function main() {
const response = await client.chats.updateChat({
chat_id: '120363000000000000@g.us',
labels: 'priority,follow-up',
});
console.log(response);
}
main();curl -X PATCH 'https://api.periskope.app/v1/chats/120363000000000000@g.us' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'x-phone: 919876543210' \
-H 'Content-Type: application/json' \
-d '{
"labels": "priority,follow-up"
}'{
"org_id": "00000000-0000-0000-0000-000000000000",
"chat_id": "120363000000000000@g.us",
"org_phone": "911111111111@c.us",
"chat_name": "Example Group",
"chat_type": "group",
"chat_image": "https://example.com/images/example.jpg",
"invite_link": "https://chat.whatsapp.com/invite/AAAAAAAAAAAAAAAAAAAAAA",
"label_ids": {
"label-aaaaaaaaaaaaaaaa": true
},
"labels": [
"priority"
],
"custom_properties": {
"Custom Property": "Value"
},
"assigned_to": "user@example.com",
"chat_access": {
"user@example.com": true
},
"group_description": "A sample group description",
"info_admins_only": false,
"messages_admins_only": false,
"add_members_admins_only": false,
"member_count": 12,
"members": {
"key": {
"org_id": "00000000-0000-0000-0000-000000000000",
"chat_id": "120363000000000000@g.us",
"org_phone": "911111111111@c.us",
"contact_id": "922222222222@c.us",
"contact_name": "John Doe",
"contact_image": "https://example.com/images/example.jpg",
"contact_color": "#000000",
"is_admin": false,
"is_super_admin": false,
"is_internal": false
}
},
"latest_message": {
"message_id": "true_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAAAA",
"org_id": "00000000-0000-0000-0000-000000000000",
"org_phone": "911111111111@c.us",
"chat_id": "120363000000000000@g.us",
"body": "Hello! This is a sample message.",
"message_type": "chat",
"from_me": true,
"author": "922222222222@c.us",
"ack": "4",
"timestamp": "2026-01-15T09:30:00+00:00",
"media": {
"path": "https://example.com/images/example.jpg",
"mimetype": "image/png",
"filename": "image.png"
},
"mentioned_ids": [
"922222222222@c.us"
],
"performed_by": "api",
"quoted_message_id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"sender_phone": "911111111111@c.us",
"sent_message_id": "00000000-0000-0000-0000-000000000000",
"delivery_info": {
"delivered": {
"key": null
},
"read": {
"key": null
},
"pending": [
null
],
"read_count": null,
"delivered_count": null
},
"is_deleted": null,
"is_forwarded": null,
"is_starred": null,
"has_media": null,
"unique_id": "AAAAAAAAAAAAAAAAAAAAAA",
"updated_at": "2026-01-15T09:31:12.884+00:00"
},
"latest_message_timestamp": "2026-01-15T09:30:00+00:00",
"message_unread_count": 0,
"flag_count_map": {
"key": null
},
"parent_community_id": null,
"is_archived": false,
"group_metadata": {},
"is_muted": false,
"is_exited": false,
"closed_at": null,
"created_at": "2026-01-10T08:00:00+00:00",
"updated_at": "2026-01-15T09:30:00.025233+00:00"
}{
"code": "UNAUTHORIZED_ERROR",
"message": "Invalid bearer auth token",
"status": 401
}{
"code": "NOT_FOUND_ERROR",
"message": "No chat matches chat_id on this phone",
"status": 404
}{
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 422,
"fields": {
"body.chat_id": {
"message": "chat_id is required"
}
}
}{
"code": "RATE_LIMIT_ERROR",
"message": "You can only make 100 requests per second",
"status": 429
}{
"code": "UNKNOWN_ERROR",
"message": "Internal server error",
"status": 500
}Update Chat
Updates the Periskope attributes of a chat — labels, custom_properties, assigned_to and/or status. At least one is required. Pass null (or an empty value) to clear labels or assigned_to; custom_properties is merged per key.
import { PeriskopeApi } from '@periskope/periskope-client';
const client = new PeriskopeApi({
authToken: 'YOUR_API_KEY',
phone: '919876543210', // the phone to act with (x-phone)
});
async function main() {
const response = await client.chats.updateChat({
chat_id: '120363000000000000@g.us',
labels: 'priority,follow-up',
});
console.log(response);
}
main();curl -X PATCH 'https://api.periskope.app/v1/chats/120363000000000000@g.us' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'x-phone: 919876543210' \
-H 'Content-Type: application/json' \
-d '{
"labels": "priority,follow-up"
}'{
"org_id": "00000000-0000-0000-0000-000000000000",
"chat_id": "120363000000000000@g.us",
"org_phone": "911111111111@c.us",
"chat_name": "Example Group",
"chat_type": "group",
"chat_image": "https://example.com/images/example.jpg",
"invite_link": "https://chat.whatsapp.com/invite/AAAAAAAAAAAAAAAAAAAAAA",
"label_ids": {
"label-aaaaaaaaaaaaaaaa": true
},
"labels": [
"priority"
],
"custom_properties": {
"Custom Property": "Value"
},
"assigned_to": "user@example.com",
"chat_access": {
"user@example.com": true
},
"group_description": "A sample group description",
"info_admins_only": false,
"messages_admins_only": false,
"add_members_admins_only": false,
"member_count": 12,
"members": {
"key": {
"org_id": "00000000-0000-0000-0000-000000000000",
"chat_id": "120363000000000000@g.us",
"org_phone": "911111111111@c.us",
"contact_id": "922222222222@c.us",
"contact_name": "John Doe",
"contact_image": "https://example.com/images/example.jpg",
"contact_color": "#000000",
"is_admin": false,
"is_super_admin": false,
"is_internal": false
}
},
"latest_message": {
"message_id": "true_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAAAA",
"org_id": "00000000-0000-0000-0000-000000000000",
"org_phone": "911111111111@c.us",
"chat_id": "120363000000000000@g.us",
"body": "Hello! This is a sample message.",
"message_type": "chat",
"from_me": true,
"author": "922222222222@c.us",
"ack": "4",
"timestamp": "2026-01-15T09:30:00+00:00",
"media": {
"path": "https://example.com/images/example.jpg",
"mimetype": "image/png",
"filename": "image.png"
},
"mentioned_ids": [
"922222222222@c.us"
],
"performed_by": "api",
"quoted_message_id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"sender_phone": "911111111111@c.us",
"sent_message_id": "00000000-0000-0000-0000-000000000000",
"delivery_info": {
"delivered": {
"key": null
},
"read": {
"key": null
},
"pending": [
null
],
"read_count": null,
"delivered_count": null
},
"is_deleted": null,
"is_forwarded": null,
"is_starred": null,
"has_media": null,
"unique_id": "AAAAAAAAAAAAAAAAAAAAAA",
"updated_at": "2026-01-15T09:31:12.884+00:00"
},
"latest_message_timestamp": "2026-01-15T09:30:00+00:00",
"message_unread_count": 0,
"flag_count_map": {
"key": null
},
"parent_community_id": null,
"is_archived": false,
"group_metadata": {},
"is_muted": false,
"is_exited": false,
"closed_at": null,
"created_at": "2026-01-10T08:00:00+00:00",
"updated_at": "2026-01-15T09:30:00.025233+00:00"
}{
"code": "UNAUTHORIZED_ERROR",
"message": "Invalid bearer auth token",
"status": 401
}{
"code": "NOT_FOUND_ERROR",
"message": "No chat matches chat_id on this phone",
"status": 404
}{
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 422,
"fields": {
"body.chat_id": {
"message": "chat_id is required"
}
}
}{
"code": "RATE_LIMIT_ERROR",
"message": "You can only make 100 requests per second",
"status": 429
}{
"code": "UNKNOWN_ERROR",
"message": "Internal server error",
"status": 500
}Authorizations
Headers
Path Parameters
Unique id of the chat. For 1-1 chats, country code + number optionally suffixed with @c.us (e.g. 922222222222@c.us — the suffix is added automatically when omitted); for groups, the id ending with @g.us.
1"120363000000000000@g.us"
Body
Custom property values to set, keyed by property name or property_id (case-insensitive). Dropdown values accept an option label or id; picklist values accept an array or comma-separated string of option labels/ids; date values accept a parseable date string. Unknown properties or invalid option values reject the request. Properties not included are left unchanged (the map is merged per key, not a full replacement); set a property to null to clear it. Passing null or an empty object as custom_properties changes nothing.
{ "Custom Property": "Value" }
Response
The updated chat
A WhatsApp chat (1-1 conversation or group) synced into the workspace, together with its Periskope attributes (labels, assignee, custom properties, status).
Was this page helpful?