> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Embedded Signup

> Complete the WhatsApp Business Platform embedded signup flow in the Telnyx portal. Create your WABA and register phone numbers for WhatsApp messaging.

# WhatsApp Embedded Signup

WhatsApp Embedded Signup enables businesses to connect their Facebook Business Manager account to Telnyx and provision WhatsApp Business Account (WABA) resources through a streamlined browser-based workflow.

## Prerequisites

Before starting the embedded signup process:

<Steps>
  <Step title="Telnyx Account Setup">
    **Required account status:**

    * Active Telnyx account with messaging enabled
    * Valid payment method configured
    * Account in good standing with no billing issues

    **Portal access:**

    * Log in to [Telnyx Portal](https://portal.telnyx.com)
    * Navigate to **Messaging** → **WhatsApp**
    * Ensure you have admin permissions for your organization
  </Step>

  <Step title="Facebook Business Manager">
    **Business Manager requirements:**

    * Facebook Business Manager account ([business.facebook.com](https://business.facebook.com))
    * Admin access to the Business Manager account
    * Business verification completed (recommended for production use)

    **Important limitations:**

    * Each phone number can only be associated with one Business Manager
    * Business Manager must have appropriate permissions for WhatsApp Business API
    * Account must comply with Facebook Business policies
  </Step>
</Steps>

<Warning>
  Ensure your Facebook Business Manager is fully set up and verified before starting embedded signup. Incomplete Business Manager setup can cause signup failures that require manual intervention.
</Warning>

## Signup Flow Overview

The embedded signup process follows a multi-step finite state machine (FSM) that progresses through these states:

```mermaid theme={null}
graph LR
    A[initiated] --> B[facebook_auth]
    B --> C[waba_created] 
    C --> D[phone_registered]
    D --> E[verified]
    
    B --> F[failed]
    C --> F
    D --> F
    E --> G[active]
    
    style A fill:#e1f5fe
    style E fill:#c8e6c9
    style F fill:#ffcdd2
    style G fill:#4caf50,color:#fff
```

Each state represents a checkpoint in the signup process with specific completion criteria and potential failure points.

## Step-by-Step Signup Process

<Steps>
  <Step title="Initiate Embedded Signup">
    **From Telnyx Portal:**

    1. Navigate to **Messaging** → **WhatsApp** → **Getting Started**
    2. Click **Connect WhatsApp Business**
    3. Review the permissions and requirements displayed
    4. Click **Begin Setup** to start the embedded signup flow

    **What happens:**

    * Telnyx creates a signup session with state `initiated`
    * Portal generates a secure OAuth URL for Facebook authorization
    * Session tracking begins for completion monitoring

    **Verification:**

    <Note>Signup session monitoring is handled automatically by the portal. API-based signup tracking may not be available in all configurations.</Note>

    ```bash theme={null}
    # Check signup session status via API
    curl -X GET "https://api.telnyx.com/v2/whatsapp/signup/{signup_id}/status" \
      -H "Authorization: Bearer YOUR_API_KEY"

    # Response
    {
      "data": {
        "id": "signup_123abc",
        "state": "initiated",
        "created_at": "2024-01-15T10:30:00Z"
      }
    }
    ```
  </Step>

  <Step title="Facebook OAuth Authorization">
    **Facebook authorization flow:**

    1. Browser redirects to Facebook Business Manager OAuth consent screen

    2. Review the requested permissions:
       * **WhatsApp Business Management** — Create and manage WABA
       * **Business Asset Management** — Associate phone numbers and templates
       * **Webhook Management** — Configure message and status webhooks

    3. Click **Continue** to grant permissions

    4. Select target Business Manager if you have multiple

    **What happens:**

    * Facebook validates your Business Manager admin status
    * OAuth token is generated and securely transmitted to Telnyx
    * Signup state advances to `facebook_auth`

    **Common issues:**

    * **Permission denied:** Ensure you have admin access to Business Manager
    * **Business not verified:** Some features require verified Business Manager
    * **Already connected:** Phone number may be connected to another provider

    **Verification:**
    The Portal will show "Connected to Facebook" with Business Manager details when successful.
  </Step>

  <Step title="WhatsApp Business Account Creation">
    **WABA provisioning:**

    Telnyx automatically creates your WhatsApp Business Account using the connected Business Manager:

    1. WABA is created under your Business Manager
    2. Telnyx is granted the necessary permissions as a solution partner
    3. Initial configuration is applied (timezone, business category)
    4. Webhook endpoints are pre-configured for Telnyx integration

    **What happens:**

    * Facebook creates the WABA resource
    * Telnyx receives WABA credentials and configuration details
    * Signup state advances to `waba_created`
    * WABA settings are synced to Telnyx systems

    **WABA configuration:**

    * **Business category:** Inherited from Business Manager
    * **Webhooks:** Configured via your messaging profile webhook settings

    **Verification:**

    ```bash theme={null}
    # List WABAs for your account
    curl -X GET "https://api.telnyx.com/v2/whatsapp/business_accounts" \
      -H "Authorization: Bearer YOUR_API_KEY"

    # Response
    {
      "data": [
        {
          "id": "waba_456def",
          "name": "Your Business Name",
          "status": "APPROVED",
          "waba_id": "2019979452207634"
        }
      ]
    }
    ```
  </Step>

  <Step title="Phone Number Registration">
    **Number selection and registration:**

    1. Portal displays available phone numbers from your Telnyx inventory
    2. Select the phone number to register for WhatsApp
    3. Choose the WABA to associate with the number
    4. Confirm the registration request

    **Phone number requirements:**

    * Must be a Telnyx number with an active messaging profile assigned
    * Cannot be currently registered with another WhatsApp provider
    * Can be used alongside SMS/voice on the same number — WhatsApp uses a separate API path

    <Warning>
      The embedded signup flow currently requires a Telnyx-owned number with a messaging profile. Bring-your-own-number (non-Telnyx numbers) is not yet supported through the portal signup flow. If you need to register an external number, contact support for assistance.
    </Warning>

    **What happens:**

    * Phone number is submitted to Facebook for WhatsApp registration
    * Facebook begins the verification process
    * Signup state advances to `phone_registered`
    * Number status changes to "pending verification"

    **Registration details:**

    * **Number format:** E.164 format (+1234567890)
    * **Verification method:** Automatically determined by Facebook
    * **Processing time:** Usually 1-5 minutes for verification

    **Verification:**

    ```bash theme={null}
    # Check phone number registration status
    curl -X GET "https://api.telnyx.com/v2/whatsapp/phone_numbers" \
      -H "Authorization: Bearer YOUR_API_KEY"

    # Response
    {
      "data": [
        {
          "phone_number": "+15551234567",
          "business_account_id": "waba_456def",
          "status": "pending_verification",
          "registered_at": "2024-01-15T11:15:00Z"
        }
      ]
    }
    ```
  </Step>

  <Step title="Phone Number Verification">
    **Facebook verification process:**

    Facebook automatically verifies phone numbers using multiple methods:

    1. **Carrier validation:** Facebook verifies number ownership with telecom provider
    2. **SMS verification:** Test SMS may be sent to validate delivery capability
    3. **API validation:** Facebook tests webhook delivery and response handling

    **Verification timeline:**

    * **Typical duration:** 1-15 minutes
    * **Complex cases:** Up to 24 hours for carrier validation
    * **Failed attempts:** May require manual review or different number

    **What happens:**

    * Facebook completes all verification checks
    * Number status updates to "verified" in Facebook systems
    * Signup state advances to `verified`
    * Number becomes available for sending messages

    **Verification methods Facebook may use:**

    <Tabs>
      <Tab title="Voice Call">
        Automated voice call to verify number is operational and accessible.

        **Duration:** 30 seconds\
        **Requirements:** Number must accept incoming calls
      </Tab>

      <Tab title="SMS Delivery">
        Test SMS sent to verify message delivery capability.

        **Message:** "Facebook verification code: \[CODE]"
        **Requirements:** Number must receive SMS messages
      </Tab>

      <Tab title="Carrier API">
        Direct verification with mobile carrier for number ownership.

        **Duration:** Instant to 24 hours
        **Requirements:** Carrier must support Facebook verification API
      </Tab>
    </Tabs>

    **Verification completion:**

    ```bash theme={null}
    # Final verification status
    curl -X GET "https://api.telnyx.com/v2/whatsapp/phone_numbers/+15551234567" \
      -H "Authorization: Bearer YOUR_API_KEY"

    # Response
    {
      "data": {
        "phone_number": "+15551234567",
        "business_account_id": "waba_456def", 
        "status": "verified",
        "verified_at": "2024-01-15T11:20:00Z",
        "enabled": true,
        "calling_enabled": false
      }
    }
    ```
  </Step>
</Steps>

## Signup Completion

When verification succeeds, your WhatsApp integration is ready:

### Account Status

* **WABA Status:** Active and ready for messaging
* **Phone Number:** Verified and enabled for sending/receiving
* **Webhooks:** Configured and receiving events
* **Templates:** Ready for submission and approval

### Next Steps After Signup

<CardGroup cols={2}>
  <Card title="Send Messages" href="/docs/messaging/whatsapp/send-messages" icon="paper-plane">
    Send templates, text, media, and interactive messages
  </Card>

  <Card title="Quickstart" href="/docs/messaging/whatsapp/quickstart" icon="bolt">
    Send your first WhatsApp message end-to-end
  </Card>

  <Card title="Receiving Webhooks" href="/docs/messaging/messages/receiving-webhooks" icon="webhook">
    Handle inbound messages and delivery status callbacks
  </Card>
</CardGroup>

## Troubleshooting Common Issues

<AccordionGroup>
  <Accordion title="Facebook OAuth Permission Denied">
    **Error:** "You don't have permission to complete this action"

    **Causes:**

    * Not admin of Business Manager account
    * Business Manager doesn't have WhatsApp permissions
    * Account suspended or restricted

    **Solutions:**

    1. Verify admin access in Business Manager
    2. Contact Facebook Business Support if account restricted
    3. Use different Business Manager account
    4. Check account verification status
  </Accordion>

  <Accordion title="WABA Creation Failed">
    **Error:** "Unable to create WhatsApp Business Account"

    **Causes:**

    * Business Manager doesn't meet Facebook requirements
    * Too many existing WABAs on Business Manager
    * Business policy violations

    **Solutions:**

    1. Complete Business Manager verification
    2. Review and resolve any policy violations
    3. Remove unused WABAs from Business Manager
    4. Contact Telnyx support with signup session ID
  </Accordion>

  <Accordion title="Phone Number Already Registered">
    **Error:** "This phone number is already connected to WhatsApp Business API"

    **Causes:**

    * Number registered with another Business Service Provider
    * Number previously registered but not properly disconnected
    * Number registered to different WABA

    **Solutions:**

    1. Disconnect number from previous provider
    2. Contact previous provider to release number
    3. Use different phone number for registration
    4. Contact Facebook Business Support for assistance
  </Accordion>

  <Accordion title="Verification Timeout or Failure">
    **Error:** "Phone number verification failed" or timeout

    **Causes:**

    * Number doesn't support voice calls or SMS
    * Carrier blocking verification attempts
    * Number routing issues

    **Solutions:**

    1. Verify number accepts incoming calls and SMS
    2. Try different phone number if possible
    3. Contact carrier to check for blocks
    4. Wait and retry verification process
    5. Contact Telnyx support with verification details
  </Accordion>

  <Accordion title="Webhook Configuration Issues">
    **Error:** Webhooks not receiving events after successful signup

    **Causes:**

    * Webhook URL not properly configured
    * Firewall blocking webhook delivery
    * Invalid webhook signature verification

    **Solutions:**

    1. Verify webhook URL accessibility from Facebook servers
    2. Check webhook signature verification implementation
    3. Review webhook configuration in Portal
    4. Test webhook endpoint with manual POST requests
    5. Check logs for delivery attempts and errors
  </Accordion>

  <Accordion title="Browser Extensions Blocking Signup Flow">
    **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:**

    1. Temporarily disable ad blockers and privacy extensions for the signup flow
    2. Add `facebook.com` and `meta.com` domains to your extension's allowlist
    3. Try using a different browser profile without extensions
    4. Use Chrome Incognito mode (extensions are typically disabled by default)
    5. 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.
  </Accordion>
</AccordionGroup>

## API Integration

### Signup Session Monitoring

Monitor signup progress programmatically using the Signup API:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.telnyx.com/v2/whatsapp/signup/{signup_id}/status" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

### Webhook Events

Receive real-time signup progress updates:

```json theme={null}
{
  "data": {
    "event_type": "whatsapp.signup.state_updated",
    "payload": {
      "signup_id": "signup_123abc",
      "state": "verified",
      "previous_state": "phone_registered",
      "waba_id": "waba_456def",
      "phone_number": "+15551234567",
      "occurred_at": "2024-01-15T11:20:00Z"
    }
  }
}
```