> ## 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 Tech Provider Embedded Signup

> Enable your end-customers to self-serve onboard WhatsApp Business Accounts through your platform using Meta's embedded signup flow integrated with Telnyx.

WhatsApp Tech Provider Embedded Signup lets ISVs and SaaS platforms embed Meta's WhatsApp onboarding flow directly into their own portal. Your end-customers can create and register a WhatsApp Business Account (WABA), claim a phone number, and begin messaging — all without leaving your application.

Unlike the [standard embedded signup flow](/docs/messaging/whatsapp/embedded-signup), which is designed for direct Telnyx customers, the Tech Provider flow is built for partners who manage multiple end-customers and need programmatic control over WABA provisioning.

## Overview

As a Tech Provider, you build the onboarding experience into your own product. The end-customer clicks a button in your portal, completes Meta's embedded signup flow, and your backend receives the resulting WABA ID and phone number ID. You then register the WABA with Telnyx so that it can use Telnyx's messaging infrastructure.

```mermaid theme={null}
sequenceDiagram
    participant EndCustomer as End Customer
    participant PartnerPortal as Your Portal
    participant Meta as Meta
    participant Telnyx as Telnyx API

    EndCustomer->>PartnerPortal: Clicks "Connect WhatsApp"
    PartnerPortal->>Meta: Launches embedded signup (FB.login)
    Meta->>EndCustomer: Shows signup & business verification
    EndCustomer->>Meta: Completes signup
    Meta-->>PartnerPortal: Returns WABA ID + Phone Number ID
    PartnerPortal->>Telnyx: POST /whatsapp/business_accounts/tech_provider
    Telnyx-->>PartnerPortal: 200 OK — WABA registered
    Telnyx->>PartnerPortal: Credit line applied, number ready
    PartnerPortal->>EndCustomer: WhatsApp connected ✅
```

### Tech Provider vs. Direct Customer

|                    | Tech Provider                          | Direct Customer          |
| ------------------ | -------------------------------------- | ------------------------ |
| **Who uses this?** | ISVs, SaaS platforms, resellers        | Individual businesses    |
| **Onboarding**     | Embedded in your portal                | Via Telnyx portal or API |
| **WABA ownership** | Your end-customers own their WABAs     | You own your WABA        |
| **API calls**      | You call Telnyx on behalf of customers | You call Telnyx directly |
| **Scale**          | Many WABAs under one integration       | One WABA per integration |

## Prerequisites

Before you begin, make sure you have:

* A [Meta Business Account](https://business.facebook.com/) with admin access
* A **Meta Tech Provider App** that has been approved by Meta with the following permissions:
  * `whatsapp_business_messaging`
  * `whatsapp_business_management`
* The Tech Provider onboarding process completed in [Meta App Dashboard](https://developers.facebook.com/apps/)
* A [Telnyx account](https://telnyx.com/sign-up) with an API key

<Warning>
  All links to Meta documentation in this guide require that you are logged in to a Meta Business account. If you don't have one, create one at [business.facebook.com](https://business.facebook.com/) before proceeding.
</Warning>

## Step 1: Create and configure your Meta Tech Provider App

<Steps>
  <Step title="Create a Meta App">
    Go to [Meta App Dashboard](https://developers.facebook.com/apps/) and create a new app. Select **Business** as the app type.
  </Step>

  <Step title="Add WhatsApp product">
    In your app's dashboard, add the **WhatsApp** product. This will generate the permissions you need.
  </Step>

  <Step title="Request required permissions">
    Under **App Review > Permissions and Features**, request the following permissions:

    | Permission                     | Purpose                                                        |
    | ------------------------------ | -------------------------------------------------------------- |
    | `whatsapp_business_messaging`  | Send and receive WhatsApp messages on behalf of your customers |
    | `whatsapp_business_management` | Manage WhatsApp Business Accounts and phone numbers            |

    Both permissions require **Advanced Access** for production use.
  </Step>

  <Step title="Complete Tech Provider onboarding">
    Follow Meta's [Tech Provider onboarding guide](https://developers.facebook.com/docs/development/create-an-app/business-onboarding) to complete the Tech Provider registration process. This includes business verification and agreeing to Meta's Tech Provider terms.
  </Step>

  <Step title="Submit for App Review">
    Submit your app for Meta's App Review. Meta will evaluate your use case and grant (or deny) the requested permissions. This process typically takes several business days.
  </Step>
</Steps>

<Note>
  While waiting for App Review approval, you can test in **Development Mode** with your own test users. Production use requires **Live Mode** and Advanced Access permissions.
</Note>

## Step 2: Link your Meta App to Telnyx

Once your Meta App is configured, you need to link it to Telnyx so that WABAs created through your embedded signup flow are registered on Telnyx's infrastructure.

<Steps>
  <Step title="Switch your app to Live mode">
    In the [Meta App Dashboard](https://developers.facebook.com/apps/), change your app mode from **Development** to **Live**. This is required for Telnyx to initiate the partner invitation.
  </Step>

  <Step title="Contact Telnyx">
    Reach out to your Telnyx representative or contact [support](https://support.telnyx.com) and provide:

    * Your **Meta App ID** (found in your app's dashboard)
    * Your **business name** as registered with Meta
  </Step>

  <Step title="Accept the partner invitation">
    Within 1–2 business days, you'll receive an email from Meta containing a partner invitation link. Click the link and accept the invitation to link your app with Telnyx.
  </Step>

  <Step title="Switch back to Development mode">
    After accepting the invitation, you can switch your app back to **Development** mode for testing. The link persists regardless of the app mode.
  </Step>
</Steps>

<Warning>
  You must switch your app to **Live mode** before Telnyx can send the partner invitation. The invitation will fail if your app is in Development mode. After accepting the invite, you can switch back to Development mode for testing.
</Warning>

## Step 3: Implement the frontend embedded signup

Meta's embedded signup flow is triggered from your web application using the Facebook JavaScript SDK. Your frontend launches the signup dialog, the end-customer completes it, and you receive the resulting credentials.

<Steps>
  <Step title="Include the Facebook SDK">
    Add the Facebook SDK to your web application:

    ```html theme={null}
    <script>
      window.fbAsyncInit = function () {
        FB.init({
          appId: 'YOUR_APP_ID',
          autoLogAppEvents: true,
          xfbml: true,
          version: 'v19.0',
        });
      };
    </script>
    <script
      async
      defer
      crossorigin="anonymous"
      src="https://connect.facebook.net/en_US/sdk.js"
    ></script>
    ```
  </Step>

  <Step title="Trigger the embedded signup flow">
    Call `FB.login()` with the `config_id` of your WhatsApp Business Configuration. This opens Meta's embedded signup dialog for your end-customer.

    ```javascript theme={null}
    function launchWhatsAppSignup() {
      // The response_type must include 'code' and 'setup_token'
      FB.login(
        function (response) {
          if (response.authResponse) {
            const code = response.authResponse.code;
            // Send the code to your backend to exchange for credentials
            sendCodeToBackend(code);
          } else {
            console.error('User cancelled login or did not fully authorize.');
          }
        },
        {
          config_id: 'YOUR_CONFIG_ID',
          response_type: 'code',
          override_default_response_type: true,
          extras: {
            setup: {},
            featureType: '',
            sessionInfoVersion: '3',
          },
        }
      );
    }
    ```
  </Step>

  <Step title="Exchange the code for WABA ID and Phone Number ID">
    After the user completes the signup, Meta returns an authorization code. Exchange this code using Meta's API to obtain the WABA ID and phone number ID.

    ```bash theme={null}
    curl -X GET \
      "https://graph.facebook.com/v19.0/oauth/access_token?\
    client_id=YOUR_APP_ID\
    &client_secret=YOUR_APP_SECRET\
    &code=AUTHORIZATION_CODE"
    ```

    The response contains access token information. Use this access token to retrieve the WABA ID and phone number ID from the signed request or the response payload:

    ```json theme={null}
    {
      "access_token": "EAAJc...",
      "token_type": "bearer",
      "expires_in": 5183814
    }
    ```
  </Step>

  <Step title="Capture the WABA ID and Phone Number ID">
    From the embedded signup response, extract the two critical identifiers:

    | Field             | Description                                                    |
    | ----------------- | -------------------------------------------------------------- |
    | `waba_id`         | The WhatsApp Business Account ID (e.g., `123456789012345`)     |
    | `phone_number_id` | The phone number ID within that WABA (e.g., `987654321098765`) |

    <Note>
      Refer to Meta's [embedded signup documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/implementation) for full details on parsing the response. You only need the **frontend (web) portion** of Meta's guide — the backend registration is handled by Telnyx in the next step.
    </Note>
  </Step>
</Steps>

## Step 4: Register the WABA with Telnyx

Once you have the `waba_id` and `phone_number_id` from the embedded signup flow, send them to Telnyx to register the WABA and activate messaging.

### Request

```bash theme={null}
curl -X POST https://api.telnyx.com/v2/whatsapp/business_accounts/tech_provider \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "waba_id": "123456789012345",
    "phone_number_id": "987654321098765",
    "app_id": "123456789012345",
    "customer_id": "acme-corp-42"
  }'
```

### Request body parameters

| Parameter         | Type   | Required | Description                                                                                |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `waba_id`         | string | Yes      | The WABA ID returned by Meta's embedded signup flow                                        |
| `phone_number_id` | string | Yes      | The phone number ID returned by Meta's embedded signup flow                                |
| `app_id`          | string | Yes      | Your Meta App ID                                                                           |
| `customer_id`     | string | No       | An optional identifier you assign to track this customer (e.g., your internal customer ID) |

<Note>
  This endpoint requires authentication with a Telnyx API key via the `Authorization: Bearer` header. Use an API key from your Telnyx account — you can create one in the [API Keys](https://portal.telnyx.com/#/app/api-keys) page.
</Note>

### Response

A successful response confirms that the WABA has been registered with Telnyx:

```json theme={null}
{
  "data": {
    "waba_id": "123456789012345",
    "phone_number_id": "987654321098765",
    "status": "registered",
    "customer_id": "acme-corp-42"
  }
}
```

### What happens after registration

When the Telnyx API returns a successful response:

1. **Credit line is applied** — The WABA is associated with your Telnyx billing account
2. **WABA is registered** — The WhatsApp Business Account is linked to Telnyx's messaging infrastructure
3. **Number is ready for messaging** — The phone number can send and receive WhatsApp messages through Telnyx

## Troubleshooting

<AccordionGroup>
  <Accordion title="I didn't receive the Meta partner invitation email">
    * Verify that your app was in **Live mode** when you contacted Telnyx
    * Check your spam and junk folders
    * Ensure the email associated with your Meta Business account is correct
    * Confirm with your Telnyx representative that they initiated the invitation
    * The invitation typically arrives within 1–2 business days
  </Accordion>

  <Accordion title="Meta App Review was denied">
    * Review Meta's rejection reasons carefully in the App Review section of your dashboard
    * Common reasons include: insufficient permissions justification, unclear use case description, or missing screencast
    * Update your submission with clearer documentation and resubmit
    * Ensure your app is functional and testable during the review period
  </Accordion>

  <Accordion title="FB.login() doesn't open the embedded signup dialog">
    * Confirm the Facebook SDK is loaded before calling `FB.login()`
    * Check that your `config_id` is correct and matches a WhatsApp Business Configuration in your app
    * Ensure your app has the `whatsapp_business_messaging` and `whatsapp_business_management` permissions
    * Open your browser's developer console for error messages from the SDK
  </Accordion>

  <Accordion title="The Telnyx API returns a 401 Unauthorized error">
    * Verify you are using a valid Telnyx API key
    * Ensure the `Authorization: Bearer YOUR_API_KEY` header is included in your request
    * Check that your API key has not expired or been revoked
  </Accordion>

  <Accordion title="The embedded signup completes but no WABA ID is returned">
    * Ensure the `response_type` parameter includes `code`
    * Check that `override_default_response_type` is set to `true`
    * Verify the user completed all steps in the Meta signup flow (business verification, phone number selection)
    * Inspect the full response object in your `FB.login()` callback for debug information
  </Accordion>

  <Accordion title="The phone number verification code never arrives">
    * Verify the phone number entered by the end-customer is correct and can receive SMS
    * Check that the phone number is not already registered with another WhatsApp account
    * Try requesting the verification code via phone call instead of SMS
    * Ensure the end-customer's phone carrier is not blocking Meta's verification messages
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="WhatsApp Quickstart" icon="rocket" href="/docs/messaging/whatsapp/quickstart/index">
    Send your first WhatsApp message with Telnyx
  </Card>

  <Card title="Standard Embedded Signup" icon="plug" href="/docs/messaging/whatsapp/embedded-signup/index">
    Direct customer embedded signup flow
  </Card>

  <Card title="WhatsApp API Reference" icon="code" href="/api-reference/whatsapp">
    Explore WhatsApp API endpoints
  </Card>

  <Card title="Messaging API" icon="message" href="/docs/messaging/messages/send-message">
    Send messages across all channels
  </Card>
</CardGroup>