Create Group

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.createGroup({
    group_name: 'Example Group',
    participants: [
      '922222222222',
    ],
  });
  console.log(response);
}

main();

curl -X POST 'https://api.periskope.app/v1/chats/create' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'x-phone: 919876543210' \
  -H 'Content-Type: application/json' \
  -d '{
    "group_name": "Example Group",
    "participants": [
      "922222222222"
    ]
  }'

{
  "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": "ERROR",
  "message": "The phone is disconnected or its server is off/unreachable",
  "status": 400
}

{
  "code": "UNAUTHORIZED_ERROR",
  "message": "Invalid bearer auth token",
  "status": 401
}

{
  "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.createGroup({
    group_name: 'Example Group',
    participants: [
      '922222222222',
    ],
  });
  console.log(response);
}

main();

curl -X POST 'https://api.periskope.app/v1/chats/create' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'x-phone: 919876543210' \
  -H 'Content-Type: application/json' \
  -d '{
    "group_name": "Example Group",
    "participants": [
      "922222222222"
    ]
  }'

{
  "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": "ERROR",
  "message": "The phone is disconnected or its server is off/unreachable",
  "status": 400
}

{
  "code": "UNAUTHORIZED_ERROR",
  "message": "Invalid bearer auth token",
  "status": 401
}

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

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

group_name

string

required

Name (subject) of the group to create

Minimum string length: 1

Example:

"Example Group"

participants

(string | null)[]

required

Phone numbers to add to the group (country code + number, e.g. 922222222222). Per WhatsApp policy a participant is added directly only when their privacy settings allow it and they are in your phone contacts — everyone else receives an invite to join.

Minimum array length: 1

Phone number of the participant, as country code + number without symbols or spaces

Minimum string length: 1

Example:

"922222222222"

Example:

["922222222222"]

options

object

Additional settings for the new group

Show child attributes

Response

The chat object of the newly created 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"

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

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

Body

Response