SocialMate Local API

Groups

List, inspect, create, and manage WhatsApp groups over the API.

Read groups on any tier; creating and modifying them is Pro (apiWriteEnabled) and needs an admin-scoped key. Mutating routes also require the account to be connected (409 otherwise).

GET /v1/accounts/{id}/groups

scope: readFree

All group chats for the account. These are chat rows (the same shape as chats, filtered to type: "group") — so each carries name, unreadCount, and lastMessageAt, not live metadata. For the participant list, subject, and description, call Get a group.

curl http://localhost:3456/v1/accounts/ACCOUNT_ID/groups \
  -H "x-api-key: YOUR_KEY"

{ "data": [ { "id": "[email protected]", "name": "Team", "type": "group", "lastMessagePreview": "Standup at 9", "lastMessageAt": 1718800000000, "unreadCount": 3 } ] }

GET /v1/accounts/{id}/groups/{groupId}

scope: readFree

Live group metadata (subject, description, participants, admins) from WhatsApp.

curl http://localhost:3456/v1/accounts/ACCOUNT_ID/groups/[email protected] \
  -H "x-api-key: YOUR_KEY"

{ "data": { "id": "[email protected]", "subject": "Team", "description": "Daily standup", "owner": "[email protected]", "participants": [ { "id": "[email protected]", "isAdmin": true, "isSuperAdmin": true } ] } }

GET /v1/accounts/{id}/groups/{groupId}/invite

scope: readFree

The group's invite code and link.

curl http://localhost:3456/v1/accounts/ACCOUNT_ID/groups/[email protected]/invite \
  -H "x-api-key: YOUR_KEY"

{ "data": { "inviteCode": "Abc123…", "inviteLink": "https://chat.whatsapp.com/Abc123…" } }

POST /v1/accounts/{id}/groups

scope: adminPro

Create a group. Body: name (1–100) and participants (array of phone numbers in international format with country code, or JIDs; 1–256).

curl -X POST http://localhost:3456/v1/accounts/ACCOUNT_ID/groups \
  -H "x-api-key: ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Launch crew", "participants": ["15551234567"] }'

{ "data": { "id": "[email protected]", "subject": "Launch crew" } }

POST /v1/accounts/{id}/groups/{groupId}/participants

scope: adminPro

Add, remove, promote, or demote members. Body: participants (array) + action ∈ add, remove, promote, demote.

curl -X POST http://localhost:3456/v1/accounts/ACCOUNT_ID/groups/[email protected]/participants \
  -H "x-api-key: ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "action": "add", "participants": ["15551230002"] }'

{ "data": { "success": true } }

PUT /v1/accounts/{id}/groups/{groupId}/subject

scope: adminPro

Rename the group. Body: subject (1–100).

curl -X PUT http://localhost:3456/v1/accounts/ACCOUNT_ID/groups/[email protected]/subject \
  -H "x-api-key: ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "subject": "New name" }'

{ "data": { "success": true } }

PUT /v1/accounts/{id}/groups/{groupId}/description

scope: adminPro

Set the group description. Body: description (≤512).

curl -X PUT http://localhost:3456/v1/accounts/ACCOUNT_ID/groups/[email protected]/description \
  -H "x-api-key: ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "description": "Be kind. No spam." }'

{ "data": { "success": true } }

POST /v1/accounts/{id}/groups/{groupId}/leave

scope: adminPro

Leave the group.

curl -X POST http://localhost:3456/v1/accounts/ACCOUNT_ID/groups/[email protected]/leave \
  -H "x-api-key: ADMIN_KEY"

{ "data": { "success": true } }