Groups API

Use the Groups API to create and manage WhatsApp groups, invite members, handle join requests, and manage invite links.

All group endpoints are under /v2/channels/whatsapp/cloud/group and require the apikey header for authentication.

Create a Group

Use POST /channels/whatsapp/cloud/group to create a new WhatsApp group. The response may return 200 if completed synchronously, or 202 if the creation is asynchronous (pending Meta webhook).

subject is required (max 128 characters). description is optional (max 2048 characters).

curl --request POST \
  --url https://chat.zoko.io/v2/channels/whatsapp/cloud/group \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'apikey: YOUR_API_KEY' \
  --data '{
    "subject": "Support Team",
    "description": "Customer support discussions and announcements",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

const options = {
  method: 'POST',
  url: 'https://chat.zoko.io/v2/channels/whatsapp/cloud/group',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    apikey: 'YOUR_API_KEY'
  },
  body: {
    subject: 'Support Team',
    description: 'Customer support discussions and announcements',
    agent_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

import requests

url = "https://chat.zoko.io/v2/channels/whatsapp/cloud/group"

payload = {
    "subject": "Support Team",
    "description": "Customer support discussions and announcements",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "apikey": "YOUR_API_KEY"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response (200 - synchronous):

{
  "_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "request_id": "meta_request_123",
  "group_id": "120363012345678901",
  "customer_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "subject": "Support Team",
  "status": "complete"
}

Response (202 - asynchronous):

{
  "request_id": "meta_request_123",
  "subject": "Support Team",
  "status": "pending"
}

List Groups

Use GET /channels/whatsapp/cloud/group to retrieve all active groups for your store.

curl --request GET \
  --url https://chat.zoko.io/v2/channels/whatsapp/cloud/group \
  --header 'accept: application/json' \
  --header 'apikey: YOUR_API_KEY'

import requests

url = "https://chat.zoko.io/v2/channels/whatsapp/cloud/group"
headers = {
    "accept": "application/json",
    "apikey": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

Response:

[
  {
    "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "customerId": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "chatType": "group",
    "groupId": "120363012345678901",
    "subject": "Support Team",
    "description": "Customer support discussions and announcements",
    "photoUrl": "https://cdn.example.com/groups/support-team.jpg",
    "inviteLink": "https://chat.whatsapp.com/abc123",
    "autoApproval": false,
    "activeParticipantCount": 5,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-02T00:00:00Z"
  }
]

Get Group Details

Use GET /channels/whatsapp/cloud/group/{id} to retrieve details of a specific group including its participants.

curl --request GET \
  --url https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID \
  --header 'accept: application/json' \
  --header 'apikey: YOUR_API_KEY'

import requests

url = "https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID"
headers = {
    "accept": "application/json",
    "apikey": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

Response:

{
  "_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "customer_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "chat_type": "group",
  "group_id": "120363012345678901",
  "subject": "Support Team",
  "description": "Customer support discussions and announcements",
  "photo_url": "https://cdn.example.com/groups/support-team.jpg",
  "invite_link": "https://chat.whatsapp.com/abc123",
  "auto_approval": false,
  "suspended": false,
  "status": "active",
  "participants": [
    {
      "wa_id": "919876543210",
      "is_admin": true,
      "status": "joined",
      "customer_id": "a1b2c3d4-0000-0000-0000-000000000001",
      "name": "Jane Doe"
    }
  ],
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-02T00:00:00Z"
}

Update Group Settings

Use PUT /channels/whatsapp/cloud/group/{id}/settings to update the group subject, description, photo, or messaging settings. All fields are optional — include only what you want to change.

Photo requirements. When supplying photo_url, the image must be:

Reachable over HTTPS (we download it server-side)
MIME type image/jpeg
5 MB or smaller
Square (height equals width)
At least 192 × 192 pixels

Any image that fails these checks returns HTTP 400 before the upload reaches Meta.

curl --request PUT \
  --url https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/settings \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'apikey: YOUR_API_KEY' \
  --data '{
    "subject": "Updated Group Name",
    "description": "Updated description for the group",
    "photo_url": "https://cdn.example.com/groups/new-picture.jpg",
    "agent_email": "agent@example.com"
  }'

import requests

url = "https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/settings"

payload = {
    "subject": "Updated Group Name",
    "description": "Updated description for the group",
    "photo_url": "https://cdn.example.com/groups/new-picture.jpg",
    "agent_email": "agent@example.com"
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "apikey": "YOUR_API_KEY"
}

response = requests.put(url, json=payload, headers=headers)
print(response.json())

Delete Group

Use POST /channels/whatsapp/cloud/group/{id}/delete to exit and delete a group.

curl --request POST \
  --url https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/delete \
  --header 'accept: application/json' \
  --header 'apikey: YOUR_API_KEY'

import requests

url = "https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/delete"
headers = {
    "accept": "application/json",
    "apikey": "YOUR_API_KEY"
}

response = requests.post(url, headers=headers)
print(response.json())

Invite Members

Use POST /channels/whatsapp/cloud/group/{id}/invitations to send template invitations to phone numbers. Numbers that are already joined, left, removed, or have a pending invitation will be skipped.

curl --request POST \
  --url https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/invitations \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'apikey: YOUR_API_KEY' \
  --data '{
    "phone_numbers": ["919876543210", "919876543211", "919876543212"]
  }'

const options = {
  method: 'POST',
  url: 'https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/invitations',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    apikey: 'YOUR_API_KEY'
  },
  body: {
    phone_numbers: ['919876543210', '919876543211', '919876543212']
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

import requests

url = "https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/invitations"

payload = {
    "phone_numbers": ["919876543210", "919876543211", "919876543212"]
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "apikey": "YOUR_API_KEY"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response:

{
  "sent": ["919876543210"],
  "skipped": ["919876543211"],
  "failed": [
    {
      "phone_number": "919876543212",
      "reason": "invalid number"
    }
  ]
}

Remove Participants

Use POST /channels/whatsapp/cloud/group/{id}/remove-participants to remove specific participants from the group.

curl --request POST \
  --url https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/remove-participants \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'apikey: YOUR_API_KEY' \
  --data '{
    "participants": ["919876543210"],
    "agent_email": "agent@example.com"
  }'

import requests

url = "https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/remove-participants"

payload = {
    "participants": ["919876543210"],
    "agent_email": "agent@example.com"
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "apikey": "YOUR_API_KEY"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Get Join Requests

Use GET /channels/whatsapp/cloud/group/{id}/join-requests to retrieve pending join requests for the group.

curl --request GET \
  --url https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/join-requests \
  --header 'accept: application/json' \
  --header 'apikey: YOUR_API_KEY'

Response:

{
  "count": 2,
  "data": [
    {
      "join_request_id": "req_123",
      "wa_id": "919876543210",
      "creation_timestamp": 1704067200,
      "customer_id": "a1b2c3d4-0000-0000-0000-000000000001",
      "name": "John Doe"
    }
  ]
}

Handle Join Requests

Use POST /channels/whatsapp/cloud/group/{id}/join-requests/{action} to approve or reject pending join requests. The {action} parameter must be either approve or reject.

curl --request POST \
  --url https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/join-requests/approve \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'apikey: YOUR_API_KEY' \
  --data '{
    "join_requests": ["req_123", "req_456"]
  }'

import requests

url = "https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/join-requests/approve"

payload = {
    "join_requests": ["req_123", "req_456"]
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "apikey": "YOUR_API_KEY"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Toggle Auto-Approval

Use PUT /channels/whatsapp/cloud/group/{id}/auto-approval to enable or disable automatic approval of join requests.

curl --request PUT \
  --url https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/auto-approval \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'apikey: YOUR_API_KEY' \
  --data '{
    "auto_approval": true
  }'

import requests

url = "https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/auto-approval"

payload = {
    "auto_approval": True
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "apikey": "YOUR_API_KEY"
}

response = requests.put(url, json=payload, headers=headers)
print(response.json())

Get Invite Link

Use GET /channels/whatsapp/cloud/group/{id}/invite-link to retrieve the current invite link for the group.

curl --request GET \
  --url https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/invite-link \
  --header 'accept: application/json' \
  --header 'apikey: YOUR_API_KEY'

Response:

{
  "invite_link": "https://chat.whatsapp.com/abc123def456"
}

Reset Invite Link

Use PUT /channels/whatsapp/cloud/group/{id}/invite-link to revoke the current invite link and generate a new one.

curl --request PUT \
  --url https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/invite-link \
  --header 'accept: application/json' \
  --header 'apikey: YOUR_API_KEY'

Response:

{
  "invite_link": "https://chat.whatsapp.com/xyz789ghi012"
}

Get Invitation Template

Use GET /channels/whatsapp/cloud/group/{id}/invitation-template to retrieve the default invitation template ID and arguments configured for the group.

curl --request GET \
  --url https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/invitation-template \
  --header 'accept: application/json' \
  --header 'apikey: YOUR_API_KEY'

Response:

{
  "invitation_template_id": "group_invite_01",
  "template_args": {}
}

Set Invitation Template

Use PUT /channels/whatsapp/cloud/group/{id}/invitation-template to configure the template used when inviting members to the group.

Available template variables:

{{brand.whatsapp_display_name}} — your store name
{{group.invite_link}} — the group invite link

curl --request PUT \
  --url https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/invitation-template \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'apikey: YOUR_API_KEY' \
  --data '{
    "invitation_template_id": "group_invite_01",
    "template_args": {}
  }'

import requests

url = "https://chat.zoko.io/v2/channels/whatsapp/cloud/group/GROUP_ID/invitation-template"

payload = {
    "invitation_template_id": "group_invite_01",
    "template_args": {}
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "apikey": "YOUR_API_KEY"
}

response = requests.put(url, json=payload, headers=headers)
print(response.json())

Create a Group​

List Groups​

Get Group Details​

Update Group Settings​

Delete Group​

Invite Members​

Remove Participants​

Get Join Requests​

Handle Join Requests​

Toggle Auto-Approval​

Get Invite Link​

Reset Invite Link​

Get Invitation Template​

Set Invitation Template​

Create a Group

List Groups

Get Group Details

Update Group Settings

Delete Group

Invite Members

Remove Participants

Get Join Requests

Handle Join Requests

Toggle Auto-Approval

Get Invite Link

Reset Invite Link

Get Invitation Template

Set Invitation Template