Group Management

Create groups, manage participants and admins, handle join requests, change settings and send to groups.

All group routes are device-scoped: send X-Device-Id. Group IDs are JIDs ending in @g.us, such as [e-mail]. Admin actions need the account to be a group admin.

export GOWA=http://localhost:3000 AUTH=admin:changeme DEVICE=my-device

Create and inspect

# create (participants: numbers or JIDs)
curl -u $AUTH -X POST $GOWA/group -H "X-Device-Id: $DEVICE" \
  -H "Content-Type: application/json" \
  -d '{"title": "Project Team", "participants": ["628111111111", "628222222222"]}'

# info and participants
curl -u $AUTH -H "X-Device-Id: $DEVICE" "$GOWA/group/info?group_id=[e-mail]"
curl -u $AUTH -H "X-Device-Id: $DEVICE" "$GOWA/group/participants?group_id=[e-mail]"

# participants as CSV
curl -u $AUTH -H "X-Device-Id: $DEVICE" "$GOWA/group/participants/export?group_id=[e-mail]" -o members.csv

# groups this account is in
curl -u $AUTH -H "X-Device-Id: $DEVICE" $GOWA/user/my/groups

Participants

The same body works for add, remove, promote and demote:

BODY='{"group_id": "[e-mail]", "participants": ["628333333333"]}'

curl -u $AUTH -X POST $GOWA/group/participants          -H "X-Device-Id: $DEVICE" -H "Content-Type: application/json" -d "$BODY"  # add
curl -u $AUTH -X POST $GOWA/group/participants/remove   -H "X-Device-Id: $DEVICE" -H "Content-Type: application/json" -d "$BODY"
curl -u $AUTH -X POST $GOWA/group/participants/promote  -H "X-Device-Id: $DEVICE" -H "Content-Type: application/json" -d "$BODY"
curl -u $AUTH -X POST $GOWA/group/participants/demote   -H "X-Device-Id: $DEVICE" -H "Content-Type: application/json" -d "$BODY"

WhatsApp may refuse to add someone directly because of their privacy settings. Send them the invite link instead.

Join requests

For groups that require admin approval:

curl -u $AUTH -H "X-Device-Id: $DEVICE" \
  "$GOWA/group/participant-requests?group_id=[e-mail]"

curl -u $AUTH -X POST $GOWA/group/participant-requests/approve \
  -H "X-Device-Id: $DEVICE" -H "Content-Type: application/json" \
  -d '{"group_id": "[e-mail]", "participants": ["628444444444"]}'
# reject: /group/participant-requests/reject with the same body

Settings

Setting	Endpoint	Body
Name	POST /group/name	{"group_id": "...", "name": "New name"}
Description	POST /group/topic	{"group_id": "...", "topic": "About this group"} (empty removes it)
Photo	POST /group/photo	multipart: group_id, photo (omit photo to remove)
Only admins edit info	POST /group/locked	{"group_id": "...", "locked": true}
Only admins send	POST /group/announce	{"group_id": "...", "announce": true}

curl -u $AUTH -X POST $GOWA/group/announce -H "X-Device-Id: $DEVICE" \
  -H "Content-Type: application/json" \
  -d '{"group_id": "[e-mail]", "announce": true}'

Invite links

# get the link (reset=true revokes the old one and creates a new one)
curl -u $AUTH -H "X-Device-Id: $DEVICE" \
  "$GOWA/group/invite-link?group_id=[e-mail]&reset=false"

# preview a group from a link without joining
curl -u $AUTH -H "X-Device-Id: $DEVICE" \
  "$GOWA/group/info-from-link?link=https://chat.whatsapp.com/AbCdEfGhIjKl"

# join
curl -u $AUTH -X POST $GOWA/group/join-with-link -H "X-Device-Id: $DEVICE" \
  -H "Content-Type: application/json" -d '{"link": "https://chat.whatsapp.com/AbCdEfGhIjKl"}'

# leave
curl -u $AUTH -X POST $GOWA/group/leave -H "X-Device-Id: $DEVICE" \
  -H "Content-Type: application/json" -d '{"group_id": "[e-mail]"}'

Messaging a group

Use the group JID as phone on any /send/* endpoint. Mention members with mentions, or everyone with "@everyone":

curl -u $AUTH -X POST $GOWA/send/message -H "X-Device-Id: $DEVICE" \
  -H "Content-Type: application/json" \
  -d '{"phone": "[e-mail]", "message": "Standup in 5 minutes", "mentions": ["@everyone"]}'

Group events

Subscribe to group.participants (join, leave, promote, demote) and group.joined (you were added) webhooks. Payload example:

{
  "event": "group.participants",
  "device_id": "[e-mail]",
  "payload": {"chat_id": "[e-mail]", "type": "join", "jids": ["[e-mail]"]}
}