WhatsApp — phone-number/deregister

Messaging stops immediately: Deregistration is not reversible without going through the full register/verify/code flow again. All in-flight messages will fail after deregistration. Ensure all queued messages are drained before calling this operation in a production context.

When to Use

WABA migration: Before moving a phone number from one WhatsApp Business Account to another, it must be deregistered from the source WABA. The migration workflow calls this node first, then registers the number in the destination WABA.
Tenant offboarding: When a client terminates their WhatsApp Business subscription, the offboarding workflow deregisters their phone number to release it from the WABA.
Security incident response: If a WABA is compromised, an incident response workflow deregisters all associated phone numbers to prevent unauthorised message sending while the compromise is contained.
Phone number recycling: Before a phone number is transferred to a different legal entity, it must be deregistered from the current WABA as a prerequisite for the Meta transfer process.
Test environment teardown: A test environment cleanup workflow deregisters sandbox phone numbers to avoid ongoing billing or quota consumption.

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 deregister.
`apiVersion`	Optional	Meta Graph API version. Defaults to `v18.0`.

Operation

Field	Required	Description
`phoneNumberId`	Optional	Override the connection-level Phone Number ID. Useful when deregistering a number different from the connection default.

Sample Configuration

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

Validation Errors

Error	Cause
`accessToken is required`	The `accessToken` field is empty.
`phoneNumberId is required`	No Phone Number ID at connection or operation level.
`100` (Meta)	Invalid Phone Number ID or the number does not belong to this WABA.
`200` (Meta)	Insufficient permissions to deregister this number.
`timeout`	The Meta Graph API did not respond within the configured timeout.

Output

Success Port

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

Expression Reference

Value	Expression	Notes
Deregistration success	`{{ $output.deregisterPhone.success }}`	Gate the next migration or offboarding step on this boolean.
Status string	`{{ $output.deregisterPhone.status }}`	Log `"deregistered"` to the migration/offboarding audit trail.

Node Policies & GuardRails

Policy Area	Recommendation
Credential storage	Store the access token in BizFirst Credentials Manager.
Message drain	Before deregistering in production, pause all message-sending workflows and wait for the queue to drain completely. Any messages sent after deregistration will fail silently on the receiving side.
Human approval gate	Route deregistration requests through a BizFirst HIL approval step before execution. Deregistering a production number is a high-impact, non-reversible operation.
Audit logging	Log every deregistration event to a permanent audit table with timestamp, phone number ID, WABA ID, and the initiating user identity. This record is critical for compliance and incident post-mortems.
Immediately follow with re-registration	If the intent is WABA migration, call `phone-number/register` on the destination WABA immediately after a successful deregistration to minimise the window where the number is unavailable.

Examples

WABA Migration Deregister Step

{
  "resource": "phone-number",
  "operation": "deregister",
  "accessToken": "{{ $credentials.sourceWabaToken }}",
  "phoneNumberId": "{{ $input.phoneNumberId }}"
}

Step 1 of a WABA migration workflow. After an approved HIL step, this node deregisters the number from the source WABA. On success: true, the workflow immediately proceeds to phone-number/register with the destination WABA's token to minimise downtime. The migration audit log records the deregistration timestamp.

Security Incident Deregistration

{
  "resource": "phone-number",
  "operation": "deregister",
  "accessToken": "{{ $credentials.emergencyAdminToken }}",
  "phoneNumberId": "{{ $item.phoneNumberId }}"
}

An incident response workflow retrieves all phone numbers via phone-number/getMany, then uses SplitInBatches to iterate through each number and call this deregister node. After all numbers are deregistered, a Slack alert is sent to the security team confirming that no further messages can be sent from the compromised WABA.