WhatsApp — group/leave

Irreversible action: Once the business phone number leaves a group, it cannot send messages to or read messages from that group. It must be re-invited by an existing group admin to rejoin. Use group/delete instead if you want to permanently dissolve the group entirely.

API endpoint: Calls the WhatsApp Cloud API group leave endpoint for the business phone number. Only the groupId is required — the business phone number acts as the leaving participant.

When to Use

Service contract end: When a business engagement concludes, a workflow removes the bot from all customer-facing groups associated with that contract, preventing inadvertent contact after contract termination.
Trial expiry: When a free trial lapses and the customer does not upgrade, a subscription management workflow removes the bot from the trial group to enforce the service boundary.
Group purpose fulfilled: When an event support group is no longer needed after the event ends, the post-event cleanup workflow has the bot leave rather than deleting the group (preserving participant history).
Bot reassignment: When the business phone number is being migrated to a different role, a pre-migration checklist workflow exits all active groups to avoid message processing conflicts during the transition.
Compliance offboarding: Regulatory or data retention policies require the business to withdraw from certain group communications; a compliance workflow triggers the leave operation after confirming data has been archived.

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 that will leave the group.
`apiVersion`	Optional	Meta Graph API version. Defaults to `v18.0`.

Operation

Field	Required	Description
`groupId`	Required	The WhatsApp group ID the business phone number should leave (e.g. `120363xxxxxxxxxx@g.us`).

Sole-admin caution: If the business phone number is the only admin in the group, leaving may leave the group without any admin. Consider promoting another participant to admin via group/updateParticipantRole before calling group/leave, or use group/delete to dissolve the group cleanly.

Sample Configuration

{
  "resource": "group",
  "operation": "leave",
  "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 the business phone number is not a member of the specified group.
`200` (Meta)	Permission error — the access token does not have rights to perform this action on the phone number.

Output

Success Port

Field	Type	Description
`groupId`	string	The group ID that was left.
`status`	string	`"left"` — confirms the business phone number has exited the group.
`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

{
  "groupId": "120363xxxxxxxxxx@g.us",
  "status": "left"
}

Expression Reference

Value	Expression	Notes
Leave confirmed	`{{ $output.leave.status }}`	Confirm `"left"` before updating your internal group membership records to reflect the bot's departure.
Group ID	`{{ $output.leave.groupId }}`	Echo of the input `groupId` — use to mark the group as inactive in your system of record.

Node Policies & GuardRails

Irreversibility: The leave action cannot be undone by the node. The business phone number must be re-invited by a group participant to rejoin. Ensure workflow logic confirms intent before executing this node (e.g. precede it with an approval or confirmation gate).
Sole-admin protection: When the bot is the only admin, leaving creates an admin-less group. Promote another participant to admin first or delete the group instead.
Post-leave node routing: Any downstream nodes that send messages to the same group will fail after this node executes. Design the workflow to route away from messaging nodes on the success path.
Credential storage: Always store accessToken in BizFirst Credentials Manager and reference it via {{ $credentials.* }}. Never hard-code tokens in the configuration.
Audit trail: Log the groupId and status alongside the workflow execution ID and triggering actor for compliance reporting.

Examples

Example 1 — Leave all trial groups when a customer subscription lapses

A subscription expiry event triggers a workflow that queries the database for all group IDs associated with the lapsed account, iterates over them, and leaves each:

{
  "resource": "group",
  "operation": "leave",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "{{ $env.WA_PHONE_NUMBER_ID }}",
  "groupId": "{{ $item.groupId }}"
}

Example 2 — Promote a backup admin then leave gracefully

To avoid leaving a group admin-less, a pre-leave workflow first promotes a designated backup admin, waits for confirmation, then leaves:

// Step 1 — promote backup admin (group/updateParticipantRole node)
{
  "resource": "group",
  "operation": "promote-admin",
  "groupId": "{{ $trigger.groupId }}",
  "participantId": "{{ $trigger.backupAdminWaId }}",
  "role": "admin"
}

// Step 2 — leave the group (group/leave node, runs after Step 1 succeeds)
{
  "resource": "group",
  "operation": "leave",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "{{ $env.WA_PHONE_NUMBER_ID }}",
  "groupId": "{{ $trigger.groupId }}"
}

Example 3 — Post-event cleanup with conditional branching

An event management workflow checks whether the event has concluded and the group has more than zero remaining admins. If both conditions are true, the bot leaves; otherwise it routes to a manual review step:

{
  "resource": "group",
  "operation": "leave",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "{{ $env.WA_PHONE_NUMBER_ID }}",
  "groupId": "{{ $nodes.EventLookup.output.groupId }}"
}