Update Chat

TypeScript

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
}

TypeScript

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

Authorization

string

header

required

Your Periskope API token, sent as Authorization: Bearer <token>. Generate one from the Periskope dashboard under Settings → API & Webhooks. API access requires an active Pro or Enterprise plan.

Headers

x-phone

string

Optional. Scope results to a single phone: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). Omit to return data across all phones the API token can access.

Example:

"919876543210"

Path Parameters

chat_id

string

required

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.

Minimum string length: 1

Example:

"120363000000000000@g.us"

Body

application/json

labels

string | null

Comma-separated label names to set on the chat, replacing its current labels. Matched case-insensitively; labels that do not exist are created automatically. Pass null or an empty string to remove every label from the chat.

Example:

"priority,follow-up"

custom_properties

object | null

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.

Example:

{ "Custom Property": "Value" }

assigned_to

string | null

Email of the workspace member to assign the chat to. Must match an existing member of the organization. Pass null or an empty string to unassign the chat.

Example:

"user@example.com"

status

enum<string>

Open or close the chat: 'closed' stamps closed_at with the current time, 'open' clears it

Available options:

open,

closed

Example:

"closed"

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

org_id

string<uuid>

The unique identifier of the organization that owns the WhatsApp account.

Example:

"00000000-0000-0000-0000-000000000000"

chat_id

string

The unique identifier of the WhatsApp chat (format: {phone_number}@c.us for individual chats or {group_id}@g.us for groups).

Example:

"120363000000000000@g.us"

org_phone

string

The organization phone that the chat belongs to (in the format {phone_number}@c.us).

Example:

"911111111111@c.us"

chat_name

string

The display name of the chat. For groups, this is the group name. For individual chats, this is the contact's name.

Example:

"Example Group"

chat_type

string

The type of chat. Can be group, user, or business.

Example:

"group"

chat_image

string

The URL of the chat's profile image.

Example:

"https://example.com/images/example.jpg"

invite_link

string

The invite link of the chat. Group chats only, and only when the phone is an admin.

Example:

"https://chat.whatsapp.com/invite/AAAAAAAAAAAAAAAAAAAAAA"

label_ids

object

A map of label identifiers associated with the chat, where keys are label IDs and values are booleans.

Show child attributes

Example:

{ "label-aaaaaaaaaaaaaaaa": true }

labels

string[]

An array of labels associated with the chat.

Example:

["priority"]

custom_properties

object

A map of custom properties associated with the chat. Values depend on the property type: dropdown, text, date.

Example:

{ "Custom Property": "Value" }

assigned_to

string

The email address of the user assigned to this chat. Absent when unassigned.

Example:

"user@example.com"

chat_access

object

A map of user access permissions, where keys are email addresses and values are booleans. Absent when no per-chat overrides exist.

Show child attributes

Example:

{ "user@example.com": true }

group_description

string

The description text for group chats. Group chats only.

Example:

"A sample group description"

info_admins_only

boolean

Indicates if only admins can modify group info.

Example:

false

messages_admins_only

boolean

Indicates if only admins can send messages in the group.

Example:

false

add_members_admins_only

boolean

Indicates if only admins can add new members to the group.

Example:

false

member_count

integer

The total number of participants in the chat.

Example:

12

members

object

A map of members in the chat, keyed by WhatsApp ID (format: {phone_number}@c.us). Only returned when fetching a single chat by id — list results omit it.

Show child attributes

latest_message

object

An object containing details about the latest message sent in the chat.

Show child attributes

latest_message_timestamp

string

Timestamp of the most recent message in the chat, as an ISO 8601 UTC timestamp.

Example:

"2026-01-15T09:30:00+00:00"

message_unread_count

integer

The number of unread messages in the chat.

Example:

0

flag_count_map

object

A map of flagged messages, where keys are phone numbers and values are flagged messages count.

Show child attributes

parent_community_id

string

Indicates the id of the parent community for the group.

is_archived

boolean

Indicates if the chat has been archived.

Example:

false

group_metadata

object

Additional raw group metadata synced from WhatsApp, when present

is_muted

boolean

Indicates if notifications for this chat are muted.

Example:

false

is_exited

boolean

Indicates if the organization has left this chat.

Example:

false

closed_at

number

The timestamp when the chat was closed, if applicable, as an epoch timestamp in milliseconds. Absent while the chat is open.

created_at

string

The ISO 8601 formatted timestamp when the chat was created.

Example:

"2026-01-10T08:00:00+00:00"

updated_at

string

The ISO 8601 formatted timestamp when the chat was last updated.

Example:

"2026-01-15T09:30:00.025233+00:00"

API

Chat APIs

Group Settings APIs

Message APIs

Scheduled Message APIs

Call APIs

Media APIs

Contact APIs

Ticket APIs

Custom Property APIs

Task APIs

Queue APIs

Phone APIs

Notes APIs

Reaction APIs

Knowledge Base APIs

Member APIs

AI APIs

Webhook APIs

Webhooks

Authorizations

Headers

Path Parameters

Body

Response