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

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",
    "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',
    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",
    "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",
    "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",
  "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, messaging settings, or join approval mode.

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",
    "join_approval_mode": "approval_required",
    "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",
    "join_approval_mode": "approval_required",
    "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