WhatsApp — phone-number/update

Display name change requires Meta review: Updating verified_name submits a name-change request to Meta for review. The number continues operating under its current name until Meta approves the new one. This process can take 1–3 business days.

When to Use

Brand rename propagation: After a company rebranding, a setup workflow updates the verified display name on all active phone numbers to reflect the new brand identity.
PIN rotation for security compliance: A quarterly security workflow rotates the two-step verification PIN on all WhatsApp Business phone numbers as part of the organisation's credential rotation policy.
Regional name localisation: A multi-region deployment sets different display names on different phone numbers to match local brand guidelines in each market.
Post-acquisition update: Following an acquisition, the operations team uses a workflow to update verified names on inherited phone numbers to reflect the parent company branding.
Automated PIN management: A secrets manager integration triggers a workflow to rotate the WhatsApp two-step PIN whenever the account's master credential set is cycled.

Configuration

Connection

Field	Required	Description
`accessToken`	Required	Permanent System User access token. Store in BizFirst Credentials Manager.
`phoneNumberId`	Required	Numeric string ID of the WhatsApp Business phone number to update.
`apiVersion`	Optional	Meta Graph API version. Defaults to `v18.0`.

Operation

Field	Required	Description
`phoneNumberId`	Optional	Override the connection-level Phone Number ID for this operation.
`displayName`	Optional	New verified display name to request. Subject to Meta review. Must comply with Meta's business name policy.
`newPin`	Optional	New 6-digit two-step verification PIN. Provide to rotate the PIN for the number.

At least one of displayName or newPin must be provided. Providing both updates both in a single call.

Sample Configuration

{
  "resource": "phone-number",
  "operation": "update-display-name",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "123456789012345",
  "displayName": "Acme Corp (New Brand)"
}

Validation Errors

Error	Cause
`accessToken is required`	The `accessToken` field is empty.
`phoneNumberId is required`	No Phone Number ID at connection or operation level.
`displayName or newPin required`	Neither update field was provided — at least one is required.
`newPin must be 6 digits`	The PIN field contains non-numeric characters or is not exactly 6 digits.
`132000` (Meta)	Display name does not meet Meta's business name policy guidelines.
`100` (Meta)	Invalid Phone Number ID.

Output

Success Port

Field	Type	Description
`success`	bool	`true` when the update request was accepted by Meta.
`status`	string	`"updated"`.
`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

{
  "success": true,
  "status": "updated",
  "rawResponse": "{\"success\":true}"
}

Expression Reference

Value	Expression	Notes
Update success flag	`{{ $output.updatePhone.success }}`	Gate downstream steps on this boolean — proceed only if `true`.
Status string	`{{ $output.updatePhone.status }}`	Log to audit trail: expected value is `"updated"` on success.

Node Policies & GuardRails

Policy Area	Recommendation
Credential storage	Store the access token in BizFirst Credentials Manager. Never inline in configuration.
Name change approval lag	Do not assume the new display name is active immediately. Follow up with a `phone-number/get` call on a schedule until the name is reflected, or monitor Meta's webhook for the name-change event.
PIN security	Never store the new PIN in workflow configuration. Pass it from BizFirst Credentials Manager or a secrets vault using an expression. Rotate PINs on a quarterly schedule or following any suspected credential compromise.
Audit logging	Log every update operation to an audit table with timestamp, phone number ID, and changed field names (not the PIN value itself) for compliance purposes.
Error port	Connect the error port. A `132000` Meta error means the display name violates their policy — review the name before resubmitting.

Examples

Rebranding Name Update

{
  "resource": "phone-number",
  "operation": "update-display-name",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "123456789012345",
  "displayName": "{{ $input.newBrandName }}"
}

A brand change project triggers this workflow with the approved new display name. The node submits the update request. A confirmation email is sent to the brand team noting that Meta review is in progress (1–3 business days). A follow-up scheduled workflow uses phone-number/get daily to detect when verifiedName changes to confirm approval.

Quarterly PIN Rotation

{
  "resource": "phone-number",
  "operation": "update-display-name",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "{{ $env.WHATSAPP_PHONE_ID }}",
  "newPin": "{{ $credentials.whatsAppNewPin }}"
}

A quarterly security schedule triggers the workflow. The new 6-digit PIN is retrieved from the secrets vault and injected via $credentials.whatsAppNewPin. After the node confirms success: true, the old PIN entry is invalidated in the vault and the new PIN is stored. The audit log records the rotation timestamp and phone number ID.