API endpoint: Calls GET /{phoneNumberId}/groups and returns all groups where the business phone number is a participant or admin. Each record includes id, subject, and description.
When to Use
- Group inventory audit: A monthly audit workflow lists all active groups and reconciles them against the internal group database to identify orphaned groups (exist at Meta but not locally) for review and cleanup.
- Broadcast targeting: A campaign workflow lists all groups, filters those matching a naming convention (e.g. groups prefixed with "VIP-"), and sends a broadcast message to each matched group.
- Stale group cleanup: A housekeeping workflow lists all groups and compares each
groupId against the project database — groups whose projects were closed more than 30 days ago are flagged for deletion.
- Group limit monitoring: A daily check lists all groups and alerts when the count approaches the account group limit, prompting the team to delete inactive ones.
- Database synchronisation: A nightly sync workflow retrieves all groups from Meta and updates the local group table, adding missing records and flagging locally-recorded groups that no longer exist at Meta.
Configuration
Connection
| Field | Required | Description |
|---|
accessToken | Required | Permanent System User access token. Store in BizFirst Credentials Manager. |
phoneNumberId | Required | Numeric string ID of the business phone number whose groups are listed. |
apiVersion | Optional | Meta Graph API version. Defaults to v18.0. |
Operation
No additional operation fields are required. The listing is automatically scoped to the connection phone number ID.
Sample Configuration
{
"resource": "group",
"operation": "get",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345"
}
Validation Errors
| Error | Cause |
|---|
accessToken is required | The accessToken field is empty. |
phoneNumberId is required | No Phone Number ID supplied. |
100 (Meta) | Invalid Phone Number ID or the number is not registered. |
200 (Meta) | Insufficient permissions to list groups. |
Output
Success Port
| Field | Type | Description |
|---|
groups | array | Array of group objects. Each contains groupId, subject, and description. |
count | number | Total number of groups returned. |
status | string | "success". |
rawResponse | string | Full raw JSON from the Meta Graph API. |
Error Port
| Field | Type | Description |
|---|
status | string | "failed" or "error". |
errorCode | string | Meta error code or "timeout". |
errorMessage | string | Human-readable error description. |
Sample Output
{
"groups": [
{
"groupId": "120363xxxxxxxxxx@g.us",
"subject": "Project Alpha Team",
"description": "Daily standup and updates for Project Alpha."
},
{
"groupId": "120363yyyyyyyyyy@g.us",
"subject": "VIP Customer Tier",
"description": null
}
],
"count": 2,
"status": "success"
}
Expression Reference
| Value | Expression | Notes |
|---|
| All groups | {{ $output.listGroups.groups }} | Pipe into SplitInBatches to process each group individually. |
| Group count | {{ $output.listGroups.count }} | Compare to account group limit for capacity monitoring. |
| Filter by name prefix | {{ $output.listGroups.groups.filter(g => g.subject.startsWith('VIP-')) }} | Use in a Function node to target specific groups by naming convention. |
Node Policies & GuardRails
| Policy Area | Recommendation |
|---|
| Credential storage | Store the access token in BizFirst Credentials Manager. |
| Group limits | WhatsApp enforces limits on the number of groups a business number can join or create. Run this operation weekly to track usage. |
| Error port | Connect the error port. An empty groups array is a valid success — handle it explicitly to prevent downstream errors when no groups exist. |
Examples
Stale Group Identification
{
"resource": "group",
"operation": "get",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345"
}
A weekly housekeeping workflow lists all groups. A Function node cross-references each groupId against the project table, filtering groups associated with closed projects older than 30 days. The matched groups are passed to a SplitInBatches node that calls group/delete for each.
Convention-Based Broadcast
{
"resource": "group",
"operation": "get",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "{{ $env.BROADCAST_PHONE_ID }}"
}
A campaign broadcast workflow lists all groups and a Function node filters those whose subject starts with "PROMO-". A SplitInBatches node iterates the filtered list and sends the promotional message to each matching group via message/sendTemplate.
