Permanent and immediate: Deletion disbands the group for all participants. The group ID can no longer be used to send messages or perform any group operations. Notify participants before deleting an active group.
When to Use
- Project completion cleanup: When a project is marked as complete and archived in the project management system, a workflow deletes the associated WhatsApp group to keep the account tidy and within group limits.
- Incident closure: After a post-mortem is completed and signed off, the incident response workflow deletes the bridge and post-mortem group as part of the final closure steps.
- Cohort graduation: When an e-learning cohort finishes, the course completion workflow deletes the study group after archiving key discussions to the course record system.
- Group limit housekeeping: A scheduled housekeeping workflow identifies groups inactive for more than 60 days (based on no messages sent by the business number) and deletes them to free up quota.
- Tenant offboarding: The client offboarding workflow deletes all WhatsApp groups associated with the tenant's phone number as part of GDPR-compliant data removal.
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. Must be a group admin. |
apiVersion | Optional | Meta Graph API version. Defaults to v18.0. |
Operation
| Field | Required | Description |
|---|
groupId | Required | The WhatsApp group ID to delete. |
Sample Configuration
{
"resource": "group",
"operation": "delete",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345",
"groupId": "120363xxxxxxxxxx@g.us"
}
Validation Errors
| Error | Cause |
|---|
accessToken is required | The accessToken field is empty. |
phoneNumberId is required | No Phone Number ID supplied. |
groupId is required | No group ID provided. |
100 (Meta) | Group not found or already deleted. |
200 (Meta) | Phone number is a group member but not an admin — admin privilege required. |
Output
Success Port
| Field | Type | Description |
|---|
success | bool | true when the group was deleted. |
groupId | string | The deleted group ID (echoed for audit). |
status | string | "deleted". |
rawResponse | string | Full raw JSON from the Meta Graph API. |
Error Port
| Field | Type | Description |
|---|
groupId | string | Group ID echoed from input. |
status | string | "failed" or "error". |
errorCode | string | Meta error code or "timeout". |
errorMessage | string | Human-readable error description. |
Sample Output
{
"success": true,
"groupId": "120363xxxxxxxxxx@g.us",
"status": "deleted"
}
Expression Reference
| Value | Expression | Notes |
|---|
| Deletion confirmed | {{ $output.deleteGroup.success }} | Gate the local database cleanup step on this boolean. |
| Deleted group ID | {{ $output.deleteGroup.groupId }} | Use to mark the group as deleted in the local group table. |
Node Policies & GuardRails
| Policy Area | Recommendation |
|---|
| Credential storage | Store the access token in BizFirst Credentials Manager. |
| Participant notification | Send a farewell message via message/sendText to the group before deleting, informing participants the group is being disbanded. This is good practice for customer-facing groups. |
| Audit logging | Log the group ID, subject (retrieved in a prior group/get), deletion timestamp, and initiating workflow to a permanent audit table before calling delete. |
| Idempotency | Treat a 100 not-found error as a successful idempotent delete in cleanup workflows — the desired outcome is already achieved. |
| Error port | Connect the error port. A 200 permission error requires verifying the phone number has admin status before retrying. |
Examples
Project Completion Cleanup
{
"resource": "group",
"operation": "delete",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345",
"groupId": "{{ $input.projectGroupId }}"
}
A project closure webhook fires when a project is archived. The workflow first sends a "Project complete — archiving this group" message to the group. After a 30-second delay, this delete node disbands the group. On success: true, the group record is marked deleted in the project database and the group ID is added to the deletion audit log.
Bulk Stale Group Cleanup
{
"resource": "group",
"operation": "delete",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345",
"groupId": "{{ $item.groupId }}"
}
A monthly housekeeping workflow calls group/getMany, then a Function node identifies groups not used in the past 60 days by cross-referencing with the message activity log. SplitInBatches iterates the stale group list. This delete node is called for each. Successes and failures are aggregated and emailed to the operations team as a cleanup report.
