Groups and communities

Groups and communities require a paired, connected token. Group JIDs end in @g.us.

List and inspect groups

GET /api/v1/sessions/{sessionId}/groups
Authorization: Bearer <api_key>

GET /api/v1/sessions/{sessionId}/groups/{groupJid}
Authorization: Bearer <api_key>

The response includes the group subject, participants, admin flags, invite settings, disappearing-message settings, and community flags.

Create and update groups

POST /api/v1/sessions/{sessionId}/groups
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "subject": "Customer updates",
  "participants": ["[email protected]"],
  "description": "Order and delivery updates"
}

Update the name or description:

PATCH /api/v1/sessions/{sessionId}/groups/{groupJid}/profile
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "subject": "Priority customers",
  "description": "High-priority support updates"
}

Participants and settings

Use participant actions to add, remove, promote, or demote members:

POST /api/v1/sessions/{sessionId}/groups/{groupJid}/participants
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "action": "add",
  "participants": ["[email protected]"]
}

Use settings to control announcement mode, admin-only editing, membership approval, invite sharing, and disappearing-message duration:

PATCH /api/v1/sessions/{sessionId}/groups/{groupJid}/settings
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "setting": "announcement",
  "enabled": true
}

{
  "ephemeralDurationSeconds": 604800
}

Invites and membership requests

Preview or join with an invite code:

POST /api/v1/sessions/{sessionId}/groups/invite/preview
POST /api/v1/sessions/{sessionId}/groups/join
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "code": "AbCdEfGhIjK"
}

Admin tokens can fetch or rotate a group invite code:

GET /api/v1/sessions/{sessionId}/groups/{groupJid}/invite-code
POST /api/v1/sessions/{sessionId}/groups/{groupJid}/invite/revoke
Authorization: Bearer <api_key>

For groups that require approval:

GET /api/v1/sessions/{sessionId}/groups/{groupJid}/membership-requests
POST /api/v1/sessions/{sessionId}/groups/{groupJid}/membership-requests
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "action": "approve",
  "participants": ["[email protected]"]
}

Communities

Create a community:

POST /api/v1/sessions/{sessionId}/communities
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "subject": "Customer community",
  "description": "Product announcements and support",
  "membershipApprovalMode": "request_required"
}

Link, unlink, or join subgroups:

POST /api/v1/sessions/{sessionId}/communities/{communityJid}/subgroups
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "action": "link",
  "subGroupJids": ["[email protected]"]
}

Community endpoints also support listing subgroups, listing merged participants, transferring ownership, fetching subgroup suggestions, and deactivating a community.

Get started

Guides

Build with the API

API Reference

Groups and communities

List and inspect groups

Create and update groups

Participants and settings

Invites and membership requests

Communities

​List and inspect groups

​Create and update groups

​Participants and settings

​Invites and membership requests

​Communities

List and inspect groups

Create and update groups

Participants and settings

Invites and membership requests

Communities