Skip to main content
TypeScript

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
required

Phone to act with: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). The phone must be connected to the org and accessible by the API token.

Minimum string length: 1
Example:

"919876543210"

Body

application/json
invite_code
string
required

The invite code of the group — the trailing segment of the invite link (https://chat.whatsapp.com/invite/<invite_code>)

Minimum string length: 1
Example:

"AAAAAAAAAAAAAAAAAAAAAA"

Response

The chat object of the joined group

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"

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.

Example:
labels
string[]

An array of labels associated with the chat.

Example:
custom_properties
object

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

Example:
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.

Example:
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.

latest_message
object

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

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.

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"