API endpoint: Calls POST /{groupId}/participants with participants as an array of phone numbers. The service accepts a single phone number per call — to add multiple members, call this node once per member or use a SplitInBatches loop.
When to Use
- New team member onboarding: When a new employee is added to a project in the project management system, a workflow automatically adds their phone number to the corresponding WhatsApp group.
- Loyalty tier upgrade: When a customer is promoted to a VIP tier, the loyalty workflow adds them to the VIP WhatsApp group where exclusive offers and early announcements are shared.
- Escalation routing: When a customer support ticket is escalated to level 2, the escalation workflow adds the L2 specialist's number to the case coordination group.
- Event attendee addition: As new attendees register for an event, the registration workflow adds each attendee to the event's WhatsApp coordination group.
- Dynamic cohort management: As students enrol in a course, the LMS enrolment workflow adds each student's phone number to the cohort's study group in real time.
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 add participants to. |
phoneNumber | Required | Phone number to add in E.164 format without the + prefix (e.g. 14155552671). The number must have an active WhatsApp account. |
Sample Configuration
{
"resource": "group",
"operation": "add-member",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345",
"groupId": "120363xxxxxxxxxx@g.us",
"phoneNumber": "14155552671"
}
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. |
phoneNumber is required | No participant phone number provided. |
100 (Meta) | The participant phone number does not have an active WhatsApp account, or the group does not exist. |
200 (Meta) | Business phone number is not a group admin. |
131026 (Meta) | Group participant limit reached. |
Output
Success Port
| Field | Type | Description |
|---|
groupId | string | The group ID. |
status | string | "member_added". |
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": "member_added",
"rawResponse": "{}"
}
Expression Reference
| Value | Expression | Notes |
|---|
| Add success | {{ $output.addParticipant.status }} | Confirm "member_added" before updating the local membership record. |
| Group ID | {{ $output.addParticipant.groupId }} | Use for audit logging alongside the added phone number. |
Node Policies & GuardRails
| Policy Area | Recommendation |
|---|
| Credential storage | Store the access token in BizFirst Credentials Manager. |
| Phone number format | Normalise all phone numbers to E.164 format without the + prefix before passing to this node. Use a Function node for normalisation. |
| WhatsApp account check | Adding a number that does not have WhatsApp returns a 100 error. Pre-validate numbers against the WhatsApp Business API contact lookup if available before adding. |
| Privacy and consent | Only add participants who have consented to be added to business WhatsApp groups. Adding customers to groups without consent may violate GDPR and WhatsApp's Terms of Service. |
| Error port | Connect the error port. A 131026 group limit error means no more participants can be added — audit and reduce existing membership before retrying. |
Examples
New Team Member Auto-Add
{
"resource": "group",
"operation": "add-member",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345",
"groupId": "{{ $input.projectGroupId }}",
"phoneNumber": "{{ $input.newMemberPhone }}"
}
A project management webhook fires when a new team member is assigned to a project. A Function node retrieves the project's WhatsApp group ID from the project database and normalises the member's phone number to E.164 format without +. This node adds them to the group. On success, the membership table is updated and a welcome message is sent to the group tagging the new member.
Batch Cohort Addition
{
"resource": "group",
"operation": "add-member",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345",
"groupId": "{{ $workflow.cohortGroupId }}",
"phoneNumber": "{{ $item.studentPhone }}"
}
When a course cohort is created, a SplitInBatches node iterates all enrolled students and calls this node for each one. The success and error counts are aggregated by a Merge node. Numbers that failed (e.g. not on WhatsApp) are written to an exceptions table for manual follow-up by the course admin.
