> ## 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.

Telnyx offers two integration paths: a **hosted signup** option where Telnyx manages the entire signup UI and backend processing (recommended for most Tech Providers), and a **custom integration** option where you embed Meta's Facebook SDK directly into your own portal for full control over the experience. See [Step 3](#step-3-choose-your-integration-path) for a comparison.

```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: Choose your integration path

After your Meta App is linked to Telnyx, you have two ways to onboard your end-customers' WABAs. Both paths complete the same Meta embedded signup — the difference is **where the signup UI lives** and **how much you build**.

|                             | Option A: Hosted signup (recommended)        | Option B: Custom integration                                       |
| --------------------------- | -------------------------------------------- | ------------------------------------------------------------------ |
| **Who it's for**            | Most Tech Providers — fastest to ship        | ISVs who want full control over the UX                             |
| **What you build**          | One API call to generate a shareable URL     | Facebook SDK integration in your own frontend                      |
| **Signup UI**               | Telnyx-hosted page at `acct.fyi`             | Embedded directly in your portal                                   |
| **End-customer experience** | Clicks a link → completes Meta signup → done | Clicks a button in your app → Meta popup → you handle the response |
| **Backend code exchange**   | Telnyx handles it automatically              | You exchange the code with Meta's Graph API                        |
| **WABA registration**       | Telnyx handles it automatically              | You call Telnyx's registration API                                 |

<Tabs>
  <Tab title="Option A: Hosted signup (recommended)">
    With the hosted signup flow, Telnyx hosts the embedded signup page. You generate a time-limited onboarding URL via API and share it with your end-customer. The customer visits the URL, completes Meta's signup, and Telnyx handles the rest — code exchange, webhook subscription, credit line sharing, and phone number registration. No Facebook SDK, no custom JavaScript.

    ```mermaid theme={null}
    sequenceDiagram
        participant TechProvider as Tech Provider
        participant Telnyx as Telnyx API
        participant EndCustomer as End Customer
        participant HostedPage as Telnyx hosted page
        participant Meta as Meta

        TechProvider->>Telnyx: POST /v2/whatsapp/hosted_signups
        Telnyx-->>TechProvider: Returns onboarding URL (acct.fyi?token=…)
        TechProvider->>EndCustomer: Shares URL via email/SMS/embed
        EndCustomer->>HostedPage: Visits URL
        HostedPage->>Meta: Launches Meta embedded signup
        Meta->>EndCustomer: Shows signup & business verification
        EndCustomer->>Meta: Completes signup
        Meta-->>HostedPage: Returns credentials
        HostedPage->>Telnyx: Registers WABA, applies credit line, subscribes webhooks
        Telnyx-->>TechProvider: WABA registered & ready ✅
    ```

    ### Step 3A.1: Generate an onboarding URL

    Call the Telnyx API to create a JWT-authenticated onboarding URL for your end-customer. The URL is valid for up to 3 days.

    ```bash theme={null}
    curl -X POST https://api.telnyx.com/v2/whatsapp/hosted_signups \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -d '{
        "app_id": "123456789012345"
      }'
    ```

    #### Request body parameters

    | Parameter    | Type              | Required | Description                                                                       |
    | ------------ | ----------------- | -------- | --------------------------------------------------------------------------------- |
    | `app_id`     | string            | Yes      | Your Meta App ID (the same one linked to Telnyx in Step 2)                        |
    | `expires_at` | string (RFC 3339) | No       | When the URL expires. Must be at most 3 days in the future. Defaults to 24 hours. |

    <Note>
      This endpoint requires authentication with a Telnyx API key. You can create one in the [API Keys](https://portal.telnyx.com/#/app/api-keys) page.
    </Note>

    ### Response

    ```json theme={null}
    {
      "data": {
        "id": "0192345a-7b8c-7d9e-0f12-3456789abcde",
        "record_type": "whatsapp_jwt",
        "app_id": "123456789012345",
        "created_at": "2026-07-08T12:00:00Z",
        "expires_at": "2026-07-09T12:00:00Z",
        "jwt": "eyJhbGciOiJSUzI1NiIs...",
        "url": "https://acct.fyi?token=eyJhbGciOiJSUzI1NiIs..."
      }
    }
    ```

    | Field        | Description                                               |
    | ------------ | --------------------------------------------------------- |
    | `url`        | The hosted onboarding URL to share with your end-customer |
    | `jwt`        | The raw JWT token (also embedded in the URL)              |
    | `expires_at` | When the URL expires (max 3 days)                         |
    | `id`         | Unique identifier for this signup session                 |

    ### Step 3A.2: Share the URL with your end-customer

    Send the `url` to your end-customer via email, SMS, or embed it as a link in your own portal. When the customer visits the URL:

    1. Telnyx validates the JWT and renders a signup page branded with your app's Meta configuration
    2. The customer clicks **Get Started** to launch Meta's embedded signup popup
    3. The customer signs in to Facebook, creates or selects a WABA, and verifies their phone number
    4. On completion, Telnyx automatically handles the backend: code exchange, webhook subscription, credit line sharing, and phone number registration

    You can poll the signup status via `GET /v2/whatsapp/signup/{session_id}/status` to track progress and surface it in your own dashboard.

    ### Step 3A.3: Check signup status (optional)

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

    Returns the signup session record with `status`, `state`, `waba_id`, and any errors. Use this to build a progress indicator in your portal or trigger downstream workflows when onboarding completes.

    ### What happens after signup

    When the end-customer completes the hosted signup:

    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. **Webhooks are subscribed** — Telnyx subscribes to Meta webhook events on the WABA's behalf
    4. **Number is ready for messaging** — The phone number can send and receive WhatsApp messages through Telnyx
  </Tab>

  <Tab title="Option B: Custom integration">
    If you prefer to embed Meta's signup flow directly into your own portal and handle the code exchange yourself, follow the steps below. This gives you full control over the UX but requires integrating the Facebook JavaScript SDK and calling Meta's Graph API.

    ### Step 3B.1: 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 3B.2: 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
  </Tab>
</Tabs>

## 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 hosted signup URL shows 'Missing Signup Token'">
    * Ensure you're using the full URL returned by `POST /v2/whatsapp_hosted_signups`, including the `?token=` query parameter
    * Check that the JWT hasn't expired — tokens are valid for a maximum of 3 days from creation
    * If the token has expired, generate a new one via the API
  </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">
    Send your first WhatsApp message with Telnyx
  </Card>

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

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

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