WhatsApp Embedded Signup

WhatsApp Embedded Signup connects a Meta business portfolio to Telnyx. The business completes Meta’s signup window, and Telnyx then provisions the WhatsApp Business Account (WABA) and its phone numbers for Cloud API messaging. Tech providers that onboard their own customers use the Tech Provider guide instead.

Prerequisites

Telnyx account:

A Telnyx account above the trial level. Trial accounts cannot use WhatsApp.

Meta business portfolio:

A Facebook account with admin access to a business portfolio, or permission to create one during signup
Business verification is not required to start. Meta applies a messaging limit of 250 to new business portfolios, and business verification is one of the ways to raise it.
The business must comply with WhatsApp’s Commerce Policy

Phone number:

A Telnyx number or a number from another carrier. See Phone numbers.
Able to receive an SMS or a voice call for Meta’s verification code
Not registered to another WhatsApp account, unless it is migrated from another provider
For standard Cloud API signup, not active in the WhatsApp or WhatsApp Business app. To keep using an existing WhatsApp Business app number, use WhatsApp Coexistence.

Phone numbers

The business enters and verifies the number in Meta’s signup window. The number does not need to be on Telnyx, and Telnyx does not import or port it.

Number	Requirements
Telnyx number	SMS and voice keep working on the same number. To receive the SMS verification code, assign the number to a messaging profile with a webhook URL. To receive the voice code, assign it to a voice connection or application.
Number from another carrier	The number stays with its carrier. Telnyx only registers it with WhatsApp.
Number on another WhatsApp provider	Meta supports migrating the number through Embedded Signup once two-step verification is disabled on it. See Meta’s migration guide.

After signup, assign each number to a messaging profile to receive inbound WhatsApp messages. See Signup webhook. Start Embedded Signup from Messaging Suite → WhatsApp Messaging in the Telnyx Portal with Connect WhatsApp Business, Add Account on the Business Accounts tab, or Add Number on the WhatsApp Numbers tab. Meta’s signup window then handles the business-side steps:

Grant permissions

Select a business portfolio

Select an existing business portfolio or create a new one.

Select a WhatsApp Business Account

Select an existing WhatsApp Business Account or create a new one. Meta creates the WABA, not Telnyx.

Add and verify the phone number

Enter the phone number and verify it with the code Meta sends by SMS or voice call.

Some platforms, including Meta, may not deliver SMS verification codes to virtual numbers (VoIP and DID ranges). Meta rates SMS OTP delivery to VoIP numbers as Not Recommended, while voice OTP is Standard (see Meta’s phone number requirements). If the SMS code doesn’t arrive, request verification by voice call instead.

Telnyx then provisions the account asynchronously and tracks progress in a signup session.

Provisioning states

The signup session moves through these states in order. The state field shows the current step, or the step that failed.

State	Description
`SUBSCRIBE_WEBHOOKS`	Subscribes the Telnyx app to the WABA’s webhooks
`ASSIGNED_USERS`	Assigns the Telnyx system user to the WABA
`SHARE_CREDIT_LINE`	Shares the Telnyx credit line with the WABA
`REGISTER_PHONE_NUMBER`	Registers the phone numbers with Cloud API, including the two-step verification PIN. Skipped for coexistence.
`ADD_WABA_TO_DB`	Stores the WABA in the Telnyx account
`ADD_PHONE_NUMBERS_TO_DB`	Stores the WABA’s phone numbers in the Telnyx account
`COMPLETE`	Provisioning finished

The status field reports the session outcome:

Status	Description
`INCOMPLETE`	The session is waiting for the Meta signup code
`PENDING`	Provisioning is in progress. Telnyx retries transient Meta errors automatically.
`SUCCESS`	Provisioning finished and the WABA and phone numbers are available
`FAILURE`	Provisioning stopped. `errors` contains the reason, and `state` shows the failed step.

A SUCCESS session can still list errors. Telnyx records an error for each retried attempt, and a phone number that fails registration does not stop the session, unless the number is active in the WhatsApp Business app. Check each number’s status after signup. Retrieve a signup session with GET /v2/whatsapp/signup/{session_id}/status:

curl -X GET "https://api.telnyx.com/v2/whatsapp/signup/019f4253-e09a-7622-bc6f-625378711d78/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

This example shows a session that failed at the credit line step:

{
  "data": {
    "record_type": "whatsapp_session_id",
    "session_id": "019f4253-e09a-7622-bc6f-625378711d78",
    "user_id": "00000000-0000-4000-8000-000000000000",
    "state": "SHARE_CREDIT_LINE",
    "status": "FAILURE",
    "created_at": "2026-10-01T09:58:25Z",
    "updated_at": "2026-10-01T09:58:27Z",
    "waba_id": "123456789012345",
    "errors": [
      "[ShareCreditLine] Bad status received: Invalid parameter Credit Allocation Not Allowed During Month-End Close: This WhatsApp Business Account cannot be moved onto a credit line while the monthly billing close is running. Please try again once the close has completed, usually within the first few days of the month."
    ]
  }
}

List finished signup sessions with GET /v2/whatsapp/signup. Filter by WABA with filter[waba_id], or by the tech provider’s customer reference with filter[customer_id]:

curl -g -X GET "https://api.telnyx.com/v2/whatsapp/signup?filter[waba_id]=123456789012345" \
  -H "Authorization: Bearer YOUR_API_KEY"

Telnyx sends a whatsapp.waba_added event when a signup session succeeds or fails. Set the destination with PATCH /v2/whatsapp/user_data:

{
  "webhook_url": "https://example.com/whatsapp/signup",
  "webhook_failover_url": "https://example.com/whatsapp/signup-failover"
}

The event payload contains:

Field	Description
`record_type`	Always `waba_account_added`
`waba_id`	Meta WABA ID
`phone_numbers`	Phone numbers found on the WABA. Omitted for standard sessions started with a `phone_number_id`, and for sessions that fail before Telnyx fetches the numbers.
`status`	`SUCCESS` or `FAILURE`
`event_id`	Signup session ID
`errors`	Errors recorded during provisioning

When a phone number fails registration for a reason other than being active in the WhatsApp Business app, Telnyx sends a FAILURE event, continues provisioning, and sends another event for the same event_id when the session ends. Telnyx sends events only when webhook_url or webhook_failover_url is set. A session that fails before a WABA is identified sends no event. Inbound messages for a provisioned number are delivered to the webhook of the messaging profile assigned to that number. Assign the profile by setting profile_id with PATCH /v2/whatsapp/phone_numbers/{phone_number}/profile. See Receiving Webhooks.

Verify the result

After the session reaches SUCCESS, list the WABAs with GET /v2/whatsapp/business_accounts and retrieve each number with GET /v2/whatsapp/phone_numbers/{phone_number}. The WABA status is derived from Meta’s account_review_status and business_verification_status:

Status	Meaning
`ACTIVE`	Account review is `APPROVED` and business verification is `verified`
`PENDING`	Account review is `PENDING`
`REJECTED`	Account review is `REJECTED`
`INACTIVE`	Any other combination, such as an approved account with business verification not yet completed

INACTIVE does not block sending. Meta applies the messaging limit for unverified businesses until business verification completes. The phone number status is Meta’s value. A number is ready for Cloud API messaging when status is CONNECTED. Coexistence numbers also need coexistence_state to reach active. See WhatsApp Coexistence.

Remove a phone number

DELETE /v2/whatsapp/phone_numbers/{phone_number} deregisters the number from Cloud API at Meta and removes it from Telnyx. The number stays in its WhatsApp Business Account at Meta. To register it in a different WABA, first delete it from the original WABA in WhatsApp Manager or migrate it through Embedded Signup. Coexistence numbers cannot be removed through this endpoint. Disconnect them from the WhatsApp Business app instead. See Disconnect coexistence.

Next steps

Send Messages

Send templates, text, media, and interactive messages

Quickstart

Send a first WhatsApp message end-to-end

Receiving Webhooks

Handle inbound messages and delivery status callbacks

Troubleshooting

Credit line step fails

State: SHARE_CREDIT_LINEMeta rejects the credit line in these cases:

is already using a payment method: The WABA already has a payment method, for example from a previous provider or its own Meta billing, so Meta does not attach the Telnyx credit line. Select or create a different WABA in the signup window. To move a number from the old WABA, delete it there first.
Credit Allocation Not Allowed During Month-End Close: Meta’s monthly billing close is running. Retry once the close completes, usually within the first few days of the month.
Balance from previous month: The WABA has spend from the previous billing cycle on its own Meta billing. Retry once that billing is settled.

Telnyx cannot access the WABA

State: SUBSCRIBE_WEBHOOKS or ASSIGNED_USERSerrors contains Telnyx cannot access WhatsApp Business Account. The WABA was not shared with Telnyx during signup. Grant the Telnyx system user named in the error the MANAGE task on the WABA, then retry. Tech providers can avoid this by passing extras.setup.solutionID in Embedded Signup. See the Tech Provider guide.

Number is active in the WhatsApp Business app

State: REGISTER_PHONE_NUMBERerrors reports that the phone number is active in the WhatsApp Business App. Standard Cloud API signup cannot register these numbers. Use WhatsApp Coexistence instead.

Phone number stuck on Connecting phone number to Telnyx

WhatsApp Manager shows Please contact Telnyx to resolve phone number connection issue and the number does not appear in the Telnyx Portal. Meta completed its steps, but the signup result never reached Telnyx. This happens when Meta’s signup window stays open after the last step instead of closing. Retry Embedded Signup and select the same WABA and phone number. If the number still does not appear, contact Telnyx support with the WABA ID and phone number.

Number registered to another WhatsApp account

Meta returns This number is registered to an existing WhatsApp account. To use this number, disconnect it from the existing account. Disconnect or delete the number from the existing account first. Meta notes it may take up to 3 minutes for the number to become available.

Verification code not received

Meta verifies numbers by SMS or voice call only. SMS delivery to virtual numbers (VoIP and DID ranges) is not guaranteed, so request the code by voice call instead. Confirm the number accepts inbound calls.

Phone number limit reached

Meta initially caps new business portfolios at two registered phone numbers. Meta raises the cap to 20 when the business is verified or reaches a messaging limit of 2,000.

WABA limit reached

Meta initially limits each business portfolio to 20 WABAs. Remove unused WABAs from the business portfolio or use an existing WABA.

Symptom: Embedded signup popup fails to load, shows a blank page, or gets stuck during the Facebook OAuth step.Causes:

Ad blockers (uBlock Origin, Adblock Plus, etc.) blocking Facebook/Meta domains
Privacy extensions (Privacy Badger, Ghostery) blocking third-party scripts
Browser security settings blocking cross-origin popups

Solutions:

Temporarily disable ad blockers and privacy extensions for the signup flow
Add facebook.com and meta.com domains to the extension’s allowlist
Try using a different browser profile without extensions
Use Chrome Incognito mode (extensions are typically disabled by default)
Ensure popup blockers allow popups from the Telnyx Portal domain

Note: The WhatsApp embedded signup flow is powered by Meta/Facebook. The OAuth consent screen and business verification steps are hosted on Facebook’s servers, which means browser extensions that block Facebook domains will prevent the signup from completing.

Getting Started

Sending Messages

Coexistence

Calling

Management API

Sending API

For AI Agents

WhatsApp Embedded Signup

Prerequisites

Phone numbers

Provisioning states

Verify the result

Remove a phone number

Next steps

Send Messages

Quickstart

Receiving Webhooks

Troubleshooting

​WhatsApp Embedded Signup

​Prerequisites

​Phone numbers

​Meta signup window

​Provisioning states

​Check signup status

​Signup webhook

​Verify the result

​Remove a phone number

​Next steps

Send Messages

Quickstart

Receiving Webhooks

​Troubleshooting

WhatsApp Embedded Signup

Prerequisites

Phone numbers

Meta signup window

Provisioning states

Check signup status

Signup webhook

Verify the result

Remove a phone number

Next steps

Troubleshooting