WhatsApp — group/create

API endpoint: Calls POST /{phoneNumberId}/groups with messaging_product, subject, and participants (array of phone numbers). The business phone number is automatically added as the group admin. Returns the new group's id.

When to Use

Project team communication: When a new project is created in your project management system, a workflow automatically creates a WhatsApp group for the team with the project name as the subject and all assigned members as initial participants.
Event coordination: An event management workflow creates a dedicated WhatsApp group for each event, adding the event organiser and key stakeholders as initial members for real-time coordination.
Customer cohort groups: A loyalty programme creates a VIP customer group for each tier (Gold, Platinum) and adds newly promoted customers to the corresponding group automatically.
Incident response bridge: A monitoring system detects a critical incident and creates a WhatsApp response group, instantly adding the on-call engineers and the incident commander.
Cohort-based learning: An e-learning platform creates a WhatsApp study group per course cohort, adding all enrolled students as the cohort starts, enabling peer-to-peer communication.

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 create and admin the group.
`apiVersion`	Optional	Meta Graph API version. Defaults to `v18.0`.

Operation

Field	Required	Description
`subject`	Required	Group name (subject). Max 25 characters. Visible to all participants.
`participants`	Required	Array of participant phone numbers in E.164 format (e.g. `["14155552671", "447911123456"]`). At least one participant is required.

Sample Configuration

{
  "resource": "group",
  "operation": "create",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "123456789012345",
  "subject": "Project Alpha Team",
  "participants": ["14155552671", "447911123456", "61412345678"]
}

Validation Errors

Error	Cause
`accessToken is required`	The `accessToken` field is empty.
`phoneNumberId is required`	No Phone Number ID supplied.
`subject is required`	No group name provided.
`subject too long`	Group subject exceeds 25 characters.
`participants is required`	No participants array provided or array is empty.
`100` (Meta)	One or more phone numbers in `participants` is not a valid WhatsApp account.
`131026` (Meta)	The business number is not permitted to create groups — check WABA permissions.

Output

Success Port

Field	Type	Description
`groupId`	string	The new group's ID. Store this — required for all subsequent group operations.
`subject`	string	Group name as stored.
`status`	string	`"created"`.
`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

{
  "groupId": "120363xxxxxxxxxx@g.us",
  "subject": "Project Alpha Team",
  "status": "created",
  "rawResponse": "{\"id\":\"120363xxxxxxxxxx@g.us\"}"
}

Expression Reference

Value	Expression	Notes
Group ID	`{{ $output.createGroup.groupId }}`	Store immediately in the project/event database. Required for all subsequent group operations.
Group subject	`{{ $output.createGroup.subject }}`	Confirm the group name matches the intended value.
Creation status	`{{ $output.createGroup.status }}`	Gate downstream steps — proceed only if `"created"`.

Node Policies & GuardRails

Policy Area	Recommendation
Credential storage	Store the access token in BizFirst Credentials Manager.
Group ID persistence	Store the returned `groupId` immediately in a database. It is the only permanent reference to the group — there is no lookup-by-name API.
Participant phone numbers	Participants must be in E.164 format without the `+` prefix (e.g. `14155552671`). Validate and normalise numbers in a Function node before passing them as the `participants` array.
Group limit	The WhatsApp Business API enforces limits on the number of groups a phone number can create. Monitor group creation frequency and clean up unused groups via `group/delete`.
Error port	Connect the error port. A `131026` error means the WABA account does not have group creation permissions — contact Meta support to enable it.

Examples

Automated Project Team Group

{
  "resource": "group",
  "operation": "create",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "123456789012345",
  "subject": "{{ $input.projectName }}",
  "participants": "{{ $input.teamPhoneNumbers }}"
}

A project creation webhook triggers this workflow. The project name is used as the group subject and the team members' phone numbers (normalised to E.164 without + by a preceding Function node) are passed as participants. The returned groupId is stored in the project record, and a welcome message is sent via message/sendText with recipient_type: group using the new group ID.

Incident Response Bridge

{
  "resource": "group",
  "operation": "create",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "123456789012345",
  "subject": "INC-{{ $input.incidentId }} Bridge",
  "participants": ["{{ $input.oncallEngineer }}", "{{ $input.incidentCommander }}"]
}

A PagerDuty webhook fires when a critical alert is raised. This node creates a dedicated incident bridge group named with the incident ID. The on-call engineer and incident commander (retrieved from the on-call schedule workflow step) are added immediately. An initial message is posted with the incident summary and a link to the monitoring dashboard.