Two-step flow: This operation calls POST /{phoneNumberId}/request_code with code_method (SMS or VOICE) and language. Meta delivers a 6-digit code to the physical phone. Follow this node with phone-number/verifyCode to complete verification.
When to Use
- New number onboarding: When adding a phone number to a WhatsApp Business Account, this operation initiates the required verification step before the number can send messages.
- Re-verification after deregistration: After calling
phone-number/deregister and then phone-number/register, a re-verification workflow requests a new code to restore the number to active status.
- Automated provisioning pipeline: A DevOps workflow provisions new WhatsApp sending numbers for new client tenants and calls this operation to kick off the verification sequence without manual intervention.
- Voice fallback: When an SMS code is not received within a timeout window, a fallback branch requests a new code via
VOICE call to the same number.
- Localised verification: A multi-region deployment specifies the
language field to ensure the code is delivered in the local language of the team managing the physical device.
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 requesting verification. |
apiVersion | Optional | Meta Graph API version. Defaults to v18.0. |
Operation
| Field | Required | Description |
|---|
phoneNumberId | Optional | Override the connection-level Phone Number ID. |
codeMethod | Required | Delivery method: SMS or VOICE. |
language | Required | BCP-47 language code for the verification message (e.g. en_US, fr_FR, de_DE). |
Sample Configuration
{
"resource": "phone-number",
"operation": "request-verification",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "123456789012345",
"codeMethod": "SMS",
"language": "en_US"
}
Validation Errors
| Error | Cause |
|---|
accessToken is required | The accessToken field is empty. |
phoneNumberId is required | No Phone Number ID at connection or operation level. |
codeMethod is required | No delivery method specified. Must be SMS or VOICE. |
language is required | No language code specified. |
100 (Meta) | Invalid code_method value or unsupported language code. |
131031 (Meta) | Rate limit — too many verification code requests for this number in a short period. |
Output
Success Port
| Field | Type | Description |
|---|
success | bool | true when the code request was accepted and Meta has dispatched the code. |
status | string | "code_requested". |
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": "code_requested",
"rawResponse": "{\"success\":true}"
}
Expression Reference
| Value | Expression | Notes |
|---|
| Request accepted | {{ $output.requestCode.success }} | Gate downstream steps — only proceed to human verification or verifyCode if true. |
| Status string | {{ $output.requestCode.status }} | Log to provisioning audit trail: expected value "code_requested". |
Node Policies & GuardRails
| Policy Area | Recommendation |
|---|
| Credential storage | Store the access token in BizFirst Credentials Manager. |
| Rate limiting | Meta limits the number of verification code requests per number per day. Do not retry in a tight loop — implement exponential backoff and alert on repeated failures. |
| Human-in-the-loop handoff | After a successful code request, pause the workflow and route to a human approval step (or BizFirst HIL node) for the operator to enter the code from the physical device. Never attempt to automate reading the code from a device. |
| Voice fallback | After an SMS request, wait at least 2 minutes before trying a VOICE fallback to give the SMS time to arrive before occupying the phone line. |
| Error port | Connect the error port. A 131031 rate-limit error means a prior request is still pending — wait before retrying. |
Examples
New Number Provisioning — SMS Verification
{
"resource": "phone-number",
"operation": "request-verification",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "{{ $input.newPhoneNumberId }}",
"codeMethod": "SMS",
"language": "en_US"
}
A new tenant provisioning workflow calls this node after adding a phone number to the WABA. On success, the workflow pauses and a notification is sent to the technical onboarding engineer to retrieve the SMS code from the physical device and enter it into the next workflow step (phone-number/verifyCode).
Voice Fallback After SMS Timeout
{
"resource": "phone-number",
"operation": "request-verification",
"accessToken": "{{ $credentials.whatsAppToken }}",
"phoneNumberId": "{{ $input.phoneNumberId }}",
"codeMethod": "VOICE",
"language": "{{ $input.languageCode }}"
}
If the SMS code path times out after 3 minutes without a verification code entry, the workflow branches to this node which requests a voice call. The voice call delivers the code audibly to the operator at the physical device, who then enters it into the phone-number/verifyCode step.
