Groups
List the WhatsApp groups a connected phone can post to.
List Groups
Current base URL: https://developers-api.chatmaid.net.
GET /v1/groups
List the WhatsApp groups the given sender phone can post to. Each group's id is a full group JID — pass it as to in POST /v1/messages/send to message that group.
Groups where the phone cannot post (for example announcement-only groups where it is not an admin) are excluded from the result.
Request Contract
| Parameter | In | Type | Required | Rules |
|---|---|---|---|---|
fromPhoneId | Query | string | Yes | Sender phone, given as its E.164 number (recommended) or its dashboard ID. Must belong to your account. |
Auth and Status Codes
| Item | Value |
|---|---|
| Required scope | groups:read |
| Alternative scopes | messages:read, messages:send, messages:write |
| Success code | 200 |
| Error codes | 400, 401, 403, 404, 429, 502 |
For sk_test_* keys, a static sandbox group list is returned so the list-then-send flow can be exercised end to end. For sk_live_* keys, the phone must be connected; groups are fetched from WhatsApp on demand, so expect the call to take a few seconds for phones in many groups. A 502 means the WhatsApp fetch failed — retry after a moment.
curl -X GET "https://developers-api.chatmaid.net/v1/groups?fromPhoneId=%2B15551234567" \
-H "Authorization: Bearer sk_live_xxx"const params = new URLSearchParams({ fromPhoneId: "+15551234567" });
const response = await fetch(
"https://developers-api.chatmaid.net/v1/groups?" + params.toString(),
{ headers: { Authorization: "Bearer " + process.env.CHATMAID_API_KEY } }
);
const payload = await response.json();import os
import requests
response = requests.get(
"https://developers-api.chatmaid.net/v1/groups",
headers={"Authorization": f"Bearer {os.environ['CHATMAID_API_KEY']}"},
params={"fromPhoneId": "+15551234567"},
)
payload = response.json(){
"success": true,
"data": [
{
"id": "120363043211234567@g.us",
"name": "Team Updates",
"isCommunityAnnounce": false
},
{
"id": "120363098765432109@g.us",
"name": "Product Community (announcements)",
"isCommunityAnnounce": true
}
]
}Response Fields
| Field | Type | Notes |
|---|---|---|
data[].id | string | Full group JID. Valid as to in POST /v1/messages/send. |
data[].name | string | Group subject as shown in WhatsApp. |
data[].isCommunityAnnounce | boolean | True for a community's announcement channel — sends reach all community members. |
Replying to group messages
Inbound group messages already carry the group JID in their groupId field (see the message.received webhook and GET /v1/messages/inbound). To reply to a group, pass that groupId as to — no groups lookup needed.