Guides

Group Management

Create, inspect, and administer WhatsApp groups and communities — participants, settings, invite links, and disappearing messages.

WUTS exposes a full set of authenticated endpoints to create groups and communities, manage participants, edit settings, control invite links, and link groups into communities. Every operation runs against the WhatsApp session of the authenticated device, so the device must be connected first — see Connect a Device.

All requests require the Authorization: Bearer <token> header. The base URL is https://api.wuts.com.br.

Group identifiers are JIDs ending in @g.us (for example 120363039000000000@g.us). Participants may be passed as plain phone numbers (5511999999999), full user JIDs (5511999999999@s.whatsapp.net), or LIDs (abcd@lid).

Create a group or community

POST /groups creates a group from a list of participants. Set options.community: true to create a parent community instead of a regular group.

curl -X POST https://api.wuts.com.br/groups \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Team",
    "participants": ["5511999999999", "5511988887777"],
    "options": {
      "announcement": false,
      "locked": false,
      "join_approval": false,
      "community": false
    }
  }'

name and participants are required; options is optional. Available flags: announcement (only admins can send), locked (only admins can edit group info), join_approval (new members need admin approval), community (create a parent community), and parent_jid (attach the new group to an existing community).

A successful create returns 201 Created with the group state:

{
  "success": true,
  "group": {
    "jid": "120363039000000000@g.us",
    "name": "Support Team",
    "topic": "",
    "owner": "5511999999999@s.whatsapp.net",
    "created_at": "2026-06-15T14:45:11Z",
    "is_announce": false,
    "is_locked": false,
    "join_approval": false,
    "members_count": 3,
    "participants": [
      { "jid": "5511999999999@s.whatsapp.net", "is_admin": true, "is_super_admin": true },
      { "jid": "5511988887777@s.whatsapp.net", "is_admin": false, "is_super_admin": false }
    ]
  }
}

List and inspect groups

GET /groups returns every group the connected device has joined. GET /groups/:jid returns a single group, including its full participant list and admin flags.

# List all joined groups
curl https://api.wuts.com.br/groups -H "Authorization: Bearer <token>"

# Inspect one group
curl https://api.wuts.com.br/groups/120363039000000000@g.us \
  -H "Authorization: Bearer <token>"

The list response wraps results in a groups array; the single-group response wraps the object in group. Each participant includes is_admin and is_super_admin so you can tell who can perform privileged actions.

Manage participants

Use POST /groups/:jid/participants for add, promote, and demote operations via the action field. When action is omitted it defaults to add.

# Add members (default action)
curl -X POST https://api.wuts.com.br/groups/120363039000000000@g.us/participants \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "participants": ["5511999999999"] }'

# Promote a member to admin
curl -X POST https://api.wuts.com.br/groups/120363039000000000@g.us/participants \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "action": "promote", "participants": ["5511999999999"] }'

Accepted values for action: add, remove, promote, demote. You can also remove members with the dedicated DELETE /groups/:jid/participants endpoint, which takes the same { "participants": [...] } body. Both responses return the affected participants with their updated admin flags.

The connected device must be an admin of the group to add, remove, promote, or demote members, or to change any group setting below. Non-admin attempts are rejected by WhatsApp.

Edit settings, subject, and description

PATCH /groups/:jid updates one or more group properties. Omitted fields are left unchanged.

curl -X PATCH https://api.wuts.com.br/groups/120363039000000000@g.us \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Team Enterprise",
    "topic": "Official channel",
    "description": "Internal support coordination",
    "announcement": true,
    "locked": true,
    "join_approval": true,
    "member_add_mode": "admin"
  }'

Fields: name (the group subject), topic and description (the topic and description text), announcement (restrict sending to admins), locked (restrict editing group info to admins), join_approval (require admin approval for new joins), and member_add_mode (who can add members — admin or all). The endpoint returns the refreshed group object (same shape as POST /groups).

Set the group picture

POST /groups/:jid/picture updates the group photo. The body carries the image as a base64-encoded JPEG.

curl -X POST https://api.wuts.com.br/groups/120363039000000000@g.us/picture \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "image_base64": "/9j/4AAQSkZJRgABAQAAAQ..." }'

The response returns the new picture_id:

{ "success": true, "picture_id": "1718462711" }

Configure disappearing messages

PUT /groups/:jid/ephemeral sets the disappearing message timer for the group. The duration is given in seconds.

curl -X PUT https://api.wuts.com.br/groups/120363039000000000@g.us/ephemeral \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "duration_seconds": 604800 }'

Accepted values for duration_seconds: 0 (off), 86400 (1 day), 604800 (7 days), or 7776000 (90 days). The response echoes the applied value: { "success": true, "duration_seconds": 604800 }.

GET /groups/:jid/invite returns the current invite link. POST /groups/:jid/invite/reset revokes the current link and generates a new one.

# Get the current invite link
curl https://api.wuts.com.br/groups/120363039000000000@g.us/invite \
  -H "Authorization: Bearer <token>"

# Revoke and regenerate the link
curl -X POST https://api.wuts.com.br/groups/120363039000000000@g.us/invite/reset \
  -H "Authorization: Bearer <token>"

Both return the link; the reset response also adds a reset_at timestamp.

{
  "success": true,
  "group_jid": "120363039000000000@g.us",
  "invite_link": "https://chat.whatsapp.com/FxYzAbCdEfGHIJ",
  "reset_at": "2026-06-15T15:02:11Z"
}

POST /groups/join joins a group either via a full invite link or via an invite code plus the group and inviter JIDs.

# Join by link
curl -X POST https://api.wuts.com.br/groups/join \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "link": "https://chat.whatsapp.com/FxYzAbCdEfGHIJ" }'

# Join by invite code
curl -X POST https://api.wuts.com.br/groups/join \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "invite_code": "FxYzAbCdEfGHIJ",
    "group_jid": "120363039000000000@g.us",
    "inviter_jid": "5511999999999@s.whatsapp.net"
  }'

When the link form is used, the URL must contain chat.whatsapp.com/. When the code form is used, group_jid and inviter_jid are both required. A successful join returns { "success": true, "group_jid": "...", "pending_approval": false }.

If the target group requires admin approval, the response sets pending_approval: true, group_jid may be omitted, and an approval_request_jid is returned. The membership becomes active only after an admin approves the request.

Leave a group

DELETE /groups/:jid/leave removes the connected device from the group.

curl -X DELETE https://api.wuts.com.br/groups/120363039000000000@g.us/leave \
  -H "Authorization: Bearer <token>"

Returns { "success": true } on success.

A community groups several child groups under one parent. The :jid path parameter is the community JID; the body carries the child group_jid.

# Link a group into a community
curl -X POST https://api.wuts.com.br/groups/120363039000000000@g.us/community/link \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "group_jid": "120363040000000000@g.us" }'

# Unlink a group from a community
curl -X DELETE https://api.wuts.com.br/groups/120363039000000000@g.us/community/link \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "group_jid": "120363040000000000@g.us" }'

Both return { "success": true }. The device must be an admin of the community to link or unlink child groups.

Errors

Every endpoint requires a connected device; if the session is not connected, you receive 503 with code device_disconnected. Invalid JIDs return 400 with invalid_group_jid, and downstream WhatsApp failures surface as 502 with codes such as create_failed, update_failed, or invite_failed. Join failures are mapped to precise codes — for example invite_link_revoked (410), group_not_found (404), or rate_limited (429). See Errors and Rate Limits for the shared error envelope and retry guidance.

Working with Media

Send images, video, audio, documents and stickers, and fetch inbound media bytes on demand from the WUTS gateway.

Webhooks

Receive real-time WhatsApp events — inbound messages, receipts, connection state, calls, groups and more — pushed to your server.

On this page

Create a group or communityList and inspect groupsManage participantsEdit settings, subject, and descriptionSet the group pictureConfigure disappearing messagesInvite linksJoin a group by linkLeave a groupLink and unlink a communityErrors