WhatsApp — group/updateParticipantRole

Two internal operations — one node field: Set role to "admin" to promote (POST /{groupId}/admins with action: "promote") or to "member" to demote (DELETE /{groupId}/admins/{phoneId}). Retrieve the participant's wa_id from group/getParticipants before calling this operation.

When to Use

Team leadership change: When a project lead is appointed, a workflow promotes their WhatsApp ID to group admin so they can manage membership and settings without manual intervention.
Escalation workflow: A support escalation flow grants an escalation agent temporary admin rights in a customer group, then demotes them automatically once the ticket closes.
Moderation hand-off: When a community moderator rotates out, the HR workflow demotes the outgoing moderator and promotes the incoming one in a single automated step.
Role-based access sync: An IAM sync job reads role changes from an HR system and mirrors admin status in the corresponding WhatsApp groups, keeping permissions consistent across platforms.
Onboarding completion: After a new employee completes an onboarding programme, the LMS workflow promotes them to admin in the team group to signal full membership status.

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 (e.g. `120363xxxxxxxxxx@g.us`).
`participantId`	Required	The participant's WhatsApp ID (`wa_id` from `group/getParticipants`).
`role`	Required	Target role. Accepted values: `"admin"` (promote) or `"member"` (demote).

Admin-only action: The business phone number must already be a group admin. Attempting to change roles without admin status returns a Meta error code 200. You cannot demote yourself if you are the only remaining admin — the group must always have at least one admin.

Sample Configuration

Promote to admin

{
  "resource": "group",
  "operation": "promote-admin",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "123456789012345",
  "groupId": "120363xxxxxxxxxx@g.us",
  "participantId": "14155552671",
  "role": "admin"
}

Demote to member

{
  "resource": "group",
  "operation": "demote-admin",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "123456789012345",
  "groupId": "120363xxxxxxxxxx@g.us",
  "participantId": "14155552671",
  "role": "member"
}

Internal operation names: The node maps the role field to an internal operation automatically. When role is "admin" the internal operation is promote-admin; when role is "member" the internal operation is demote-admin. You can also supply the internal operation name directly in the operation field if you prefer.

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.
`participantId is required`	No participant WA ID provided.
`role must be "admin" or "member"`	The `role` value is missing or not one of the two accepted strings.
`100` (Meta)	Group not found or participant is not a member of the group.
`200` (Meta)	Business phone number is not a group admin, or attempting to demote the sole remaining admin.

Output

Success Port

Field	Type	Description
`groupId`	string	The group ID.
`status`	string	`"admin_promoted"` when promoting; `"admin_demoted"` when demoting.
`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

Promote

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

Demote

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

Expression Reference

Value	Expression	Notes
Role change result	`{{ $output.updateParticipantRole.status }}`	Check for `"admin_promoted"` or `"admin_demoted"` to confirm the change before updating your internal role store.
Group ID	`{{ $output.updateParticipantRole.groupId }}`	Echo of the input `groupId` — useful for chaining into a subsequent `group/getParticipants` call to verify the updated roles.

Node Policies & GuardRails

Admin prerequisite: The calling phone number must be a group admin. The node will fail with a Meta 200 error if this condition is not met.
Rate limiting: Meta enforces per-phone-number rate limits on admin operations. Avoid promoting or demoting many participants in rapid succession; introduce a delay node between bulk role-change iterations.
Sole-admin guard: The Meta API prevents demoting the only remaining admin. Ensure at least one other admin exists in the group before demoting.
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 status field and the triggering user identity from your IAM system for compliance and rollback capability.

Examples

Example 1 — Promote a new team lead when an HR event fires

An HR system publishes a role_changed event. A webhook trigger receives the event, looks up the employee's WhatsApp ID from a CRM lookup node, then promotes them:

{
  "resource": "group",
  "operation": "promote-admin",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "{{ $env.WA_PHONE_NUMBER_ID }}",
  "groupId": "{{ $trigger.body.groupId }}",
  "participantId": "{{ $nodes.CrmLookup.output.waId }}",
  "role": "admin"
}

Example 2 — Demote a moderator when their tenure ends

A scheduled workflow reads a list of moderators whose term has expired from a database, iterates over them, and demotes each in the relevant group:

{
  "resource": "group",
  "operation": "demote-admin",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "{{ $env.WA_PHONE_NUMBER_ID }}",
  "groupId": "{{ $item.groupId }}",
  "participantId": "{{ $item.waId }}",
  "role": "member"
}

Example 3 — Conditional role assignment based on a form response

A form collects nominations for a community leader. The workflow evaluates the nomination and branches: if approved, it promotes; if rejected, it demotes any existing interim admin:

{
  "resource": "group",
  "operation": "{{ $nodes.EvaluateNomination.output.approved == true ? 'promote-admin' : 'demote-admin' }}",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "{{ $env.WA_PHONE_NUMBER_ID }}",
  "groupId": "{{ $form.groupId }}",
  "participantId": "{{ $form.nomineeWaId }}",
  "role": "{{ $nodes.EvaluateNomination.output.approved == true ? 'admin' : 'member' }}"
}