WhatsApp — phone-number/register

PIN required: Registration requires the 6-digit two-step verification PIN that was set when the number was first enrolled. This PIN is separate from the verification code delivered via SMS/voice during the requestVerificationCode/verifyCode flow. Store the PIN securely in BizFirst Credentials Manager.

When to Use

Initial number activation: After verifying ownership via requestVerificationCode and verifyCode, this node completes the registration step that enables the number to send messages via the Cloud API.
Re-registration after deregistration: When a number has been deregistered (e.g. during a WABA migration), this node re-registers it in the new account so messaging can resume.
Tenant provisioning automation: A SaaS onboarding workflow programmatically registers a client's phone number as the final step of their WhatsApp Business Account setup.
Disaster recovery: A DR workflow re-registers phone numbers after a platform incident that required deregistration of all numbers on a compromised WABA.
Multi-region deployment: A deployment pipeline registers a set of regional phone numbers in their respective WABAs as part of the infrastructure-as-code roll-out.

Configuration

Connection

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

Operation

Field	Required	Description
`phoneNumberId`	Optional	Override the connection-level Phone Number ID.
`pin`	Required	6-digit two-step verification PIN for the phone number. Retrieve from BizFirst Credentials Manager.

Sample Configuration

{
  "resource": "phone-number",
  "operation": "register",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "123456789012345",
  "pin": "{{ $credentials.whatsAppPin }}"
}

Validation Errors

Error	Cause
`accessToken is required`	The `accessToken` field is empty.
`phoneNumberId is required`	No Phone Number ID at connection or operation level.
`pin is required`	No PIN was provided.
`pin must be 6 digits`	The PIN is not exactly 6 numeric digits.
`132012` (Meta)	Incorrect PIN — the supplied PIN does not match the one set for this number.
`132016` (Meta)	Number is already registered — call `phone-number/deregister` first if re-registration is needed.
`100` (Meta)	Invalid Phone Number ID.

Output

Success Port

Field	Type	Description
`success`	bool	`true` when registration was accepted.
`status`	string	`"registered"`.
`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": "registered",
  "rawResponse": "{\"success\":true}"
}

Expression Reference

Value	Expression	Notes
Registration success	`{{ $output.registerPhone.success }}`	Gate provisioning completion on this boolean.
Status string	`{{ $output.registerPhone.status }}`	Log `"registered"` to the provisioning audit trail.

Node Policies & GuardRails

Policy Area	Recommendation
Credential storage	Store both the access token and PIN in BizFirst Credentials Manager. Never inline credentials in configuration.
PIN management	The two-step verification PIN is a long-lived credential. Rotate it periodically via `phone-number/update` and update the Credentials Manager entry accordingly.
Already-registered guard	Call `phone-number/get` before registration to confirm the number is not already registered. A `132016` error on an already-registered number is harmless but should be handled gracefully.
Post-registration confirmation	After success, call `phone-number/get` to confirm the number is in a sendable state before routing traffic to it.
Error port	Connect the error port. A `132012` wrong PIN error should trigger a credential review alert rather than an automated retry.

Examples

New Tenant Number Activation

{
  "resource": "phone-number",
  "operation": "register",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "{{ $input.phoneNumberId }}",
  "pin": "{{ $credentials.newTenantWhatsAppPin }}"
}

The final step of a new tenant onboarding workflow. After requestVerificationCode and verifyCode have completed, this node registers the number with the tenant's 2-step PIN. On success: true, the tenant's account is marked WHATSAPP_ACTIVE in the provisioning database and a welcome notification is sent.

Re-Registration After WABA Migration

{
  "resource": "phone-number",
  "operation": "register",
  "accessToken": "{{ $credentials.newWabaToken }}",
  "phoneNumberId": "{{ $workflow.migratedPhoneId }}",
  "pin": "{{ $credentials.migratedPhonePin }}"
}

After a WABA migration, the workflow deregisters numbers from the old WABA and registers them in the new one using the new WABA's access token. Each number is registered with its existing 2-step PIN. The workflow confirms registration of all numbers before routing production traffic to the new WABA.