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

# Tech Provider Integration

> Set up your Meta Tech Provider integration with Plivo as the WhatsApp BSP — architecture, Embedded Signup, and API reference

Meta requires any company that resells WhatsApp Business APIs to register as a [Tech Provider](https://business.whatsapp.com/partners/become-a-partner) and comply with the [Tech Provider Terms](https://www.facebook.com/legal/BM-tech-provider-terms). This guide walks you through the architecture, prerequisites, Meta configuration, Embedded Signup implementation, and API reference for integrating with Plivo as the underlying BSP.

## Overview and architecture

### Three-layer model

WhatsApp's Multi-Partner Solution uses a three-layer model. Meta sits at the top as the platform owner, Plivo operates as the BSP (Business Solution Provider) in the middle, and you operate as the Tech Provider that serves your customers.

| Layer                   | Role                       | Responsibilities                                                                                                                           |
| ----------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Meta**                | Platform owner             | Owns the WhatsApp Cloud API, enforces policies, reviews apps, and manages the Multi-Partner Solution program.                              |
| **Plivo (BSP)**         | Business Solution Provider | Hosts the Cloud API infrastructure, manages credit lines, processes messages, and provides the Embedded Signup API.                        |
| **You (Tech Provider)** | Reseller / ISV             | Builds the customer-facing product, implements Embedded Signup, manages your customers' onboarding, and handles billing to your customers. |

### Multi-Partner Solution — who controls what

| Capability                      | Plivo (BSP)         | You (Tech Provider)            | Your customer                  |
| ------------------------------- | ------------------- | ------------------------------ | ------------------------------ |
| Cloud API message sending       | Yes                 | Via Plivo API                  | -                              |
| Credit line and billing         | Yes                 | Bills your customer            | Pays you                       |
| WABA creation (Embedded Signup) | Backend processing  | Frontend implementation        | Completes signup flow          |
| Phone number registration       | Yes                 | Triggers via API               | Provides phone number          |
| Template management             | Via API             | Via Plivo API                  | Submits templates              |
| Webhook delivery                | Configures per WABA | Receives and routes            | -                              |
| Business verification with Meta | -                   | Must complete own verification | Must complete own verification |

## Prerequisites

### What you need (Tech Provider requirements)

Before you begin the integration, make sure you have the following in place.

| Requirement                             | Details                                                                                                                                                                                    |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Meta Business Portfolio**             | A verified Meta Business Portfolio in [Meta Business Suite](https://business.facebook.com/). This is the top-level entity that owns your Meta assets.                                      |
| **Meta Developer Account**              | An active account at [developers.facebook.com](https://developers.facebook.com/) linked to your Meta Business Portfolio.                                                                   |
| **Business Verification with Meta**     | Complete [Meta Business Verification](https://www.facebook.com/business/help/1095661473946872) for your business. This typically takes fewer than 5 business days.                         |
| **Meta App (type: Business)**           | Create a Meta App with the type set to **Business** and add the **WhatsApp** product to it.                                                                                                |
| **Facebook Login for Business**         | Configure the **WhatsApp Embedded Signup** variant of Facebook Login for Business within your Meta App. This generates the `config_id` you need for the frontend SDK.                      |
| **App Review submission**               | Submit your app for Meta App Review with two screen-recorded demo videos (details below).                                                                                                  |
| **Plivo account with WhatsApp enabled** | An active Plivo account with the WhatsApp channel enabled. Contact your Plivo account manager or [Plivo support](https://support.plivo.com/hc/en-us/requests/new) if you do not have this. |

### What Plivo sets up

Once you share your Meta App details, Plivo configures the following on the backend.

| Item                              | Description                                                                                                                              |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Partner Solution acceptance**   | Plivo accepts your Multi-Partner Solution request, linking your Tech Provider app to Plivo's BSP infrastructure.                         |
| **Credit line configuration**     | Plivo extends the Meta credit line to cover conversation charges for WABAs onboarded through your integration.                           |
| **Webhook endpoint registration** | Plivo registers webhook endpoints so that inbound messages and status callbacks route correctly for each WABA.                           |
| **API credentials**               | Plivo provides an Auth ID and Auth Token scoped to a Tech Provider sub-account. Use these credentials for all Embedded Signup API calls. |

<Warning>
  Do not begin the Embedded Signup implementation until both your Meta Business Verification and Multi-Partner Solution approval are complete. Starting before both are confirmed can cause onboarding failures that are difficult to reverse.
</Warning>

## Setup steps — Meta configuration

### 3.1 Create a Meta App and add WhatsApp

Follow these steps to create your Meta App and add the WhatsApp product.

1. Go to [developers.facebook.com](https://developers.facebook.com/) and log in with your Meta Developer Account.
2. Click **Create App** and select the app type **Business**.
3. Enter your app name and contact email, then select the Meta Business Portfolio you verified earlier.
4. On the app dashboard, find **WhatsApp** in the product list and click **Set Up**.
5. Confirm that the WhatsApp product appears in the left sidebar of your app dashboard.

<Note>
  You do not need to configure a WhatsApp phone number or WABA in your own app. Your app serves as the container for the Embedded Signup flow that your customers complete.
</Note>

### 3.2 Create a Multi-Partner Solution

1. In your Meta App dashboard, navigate to **WhatsApp** > **Multi-Partner Solutions**.
2. Click **Create Solution** and give it a descriptive name (for example, "Plivo WhatsApp Integration").
3. Select **Plivo** as the BSP partner from the list.
4. Submit the solution request. Plivo receives a notification and accepts the request on the backend.
5. Wait for confirmation from Plivo that the Multi-Partner Solution is active before proceeding.

### 3.3 Configure Facebook Login for Business

1. In your Meta App dashboard, go to **Facebook Login for Business** in the left sidebar. If you do not see it, click **Add Product** and add it.
2. Click **Settings** under Facebook Login for Business.
3. Under **Login Type**, select **WhatsApp Embedded Signup**.
4. Configure the **Redirect URI** to point to your backend endpoint that handles the OAuth callback.
5. Save your settings and note the **Config ID** generated on this page. You need this value for the frontend JavaScript SDK integration.
6. Under **Permissions**, ensure that `whatsapp_business_messaging` and `whatsapp_business_management` are listed.

<Info>
  The **Config ID** is specific to your Facebook Login for Business configuration. You pass this value to the `FB.login()` call in your frontend code. Do not confuse it with your Meta App ID.
</Info>

### 3.4 App Review submission

Submit your Meta App for App Review to gain production access. You must request two permissions and provide a screen-recorded demo video for each.

| Permission                     | Video requirement                                                                                         |
| ------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `whatsapp_business_messaging`  | Record a demo showing your app sending a WhatsApp message through the Plivo API on behalf of a test WABA. |
| `whatsapp_business_management` | Record a demo showing your app creating a WhatsApp message template through the Plivo API.                |

**Video guidelines:**

* Each video must demonstrate the full end-to-end flow, from your application's UI to the API call and the result.
* Use a real test WABA (not a mock) for the demo.
* Keep each video under 5 minutes.
* Upload the videos as part of the App Review submission at **App Review** > **Requests** in your Meta App dashboard.

<Note>
  Meta typically reviews App Review submissions within 5 business days. You cannot use the Embedded Signup flow in production until Meta approves your app.
</Note>

## Embedded Signup implementation

### 4.1 Full Embedded Signup flow

The Embedded Signup flow involves coordinated actions between your frontend, your backend, Meta, and Plivo. Here is the complete sequence.

| Step | Actor         | Action                                                                                                                                                                                                       |
| ---- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1    | Your customer | Opens your onboarding page and clicks the "Connect WhatsApp" button.                                                                                                                                         |
| 2    | Your frontend | Calls `FB.login()` with the `config_id`, `response_type: 'code'`, and `override_default_response_type: true`.                                                                                                |
| 3    | Meta          | Displays the Embedded Signup dialog where your customer logs in to their Meta account.                                                                                                                       |
| 4    | Your customer | Creates or selects a Meta Business Portfolio in the signup dialog.                                                                                                                                           |
| 5    | Your customer | Creates a new WABA or selects an existing one.                                                                                                                                                               |
| 6    | Your customer | Creates a new WhatsApp business profile and registers a phone number, including OTP verification.                                                                                                            |
| 7    | Your customer | Grants the requested permissions (`whatsapp_business_messaging`, `whatsapp_business_management`) and completes the flow.                                                                                     |
| 8    | Meta          | Returns an authorization code to your frontend via the `FB.login()` callback. The `sessionInfoVersion: 2` response also includes the WABA ID, phone number ID, and business ID in the `authResponse` extras. |
| 9    | Your frontend | Sends the authorization code and session info (WABA ID, phone number ID, business ID) to your backend.                                                                                                       |
| 10   | Your backend  | Calls the Meta Graph API `debug_token` endpoint to exchange the code for a validated token and extract the WABA ID, phone number ID, and business ID if not already available from step 8.                   |
| 11   | Your backend  | Calls the Plivo Embedded Signup API (`POST /WhatsApp/EmbeddedSignup/`) with the WABA ID, phone number ID, and business ID to complete the onboarding.                                                        |

### 4.2 JavaScript SDK integration

Add the following code to your onboarding page to load the Meta SDK and trigger the Embedded Signup flow.

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Connect WhatsApp</title>
</head>
<body>
  <!-- Load the Meta JavaScript SDK -->
  <script async defer crossorigin="anonymous"
    src="https://connect.facebook.net/en_US/sdk.js">
  </script>

  <script>
    // Initialize the Facebook SDK
    window.fbAsyncInit = function () {
      FB.init({
        appId: 'YOUR_META_APP_ID',   // Replace with your Meta App ID
        autoLogAppEvents: true,
        xfbml: true,
        version: 'v19.0'
      });
    };

    // Launch Embedded Signup
    function launchEmbeddedSignup() {
      FB.login(
        function (response) {
          if (response.authResponse) {
            const code = response.authResponse.code;

            // sessionInfoVersion: 2 returns extras with WABA and phone details
            const extras = response.authResponse;
            console.log('Authorization code:', code);
            console.log('WABA ID:', extras.waba_id);
            console.log('Phone Number ID:', extras.phone_number_id);
            console.log('Business ID:', extras.business_id);

            // Send these values to your backend
            fetch('/api/whatsapp/embedded-signup', {
              method: 'POST',
              headers: { 'Content-Type': 'application/json' },
              body: JSON.stringify({
                code: code,
                waba_id: extras.waba_id,
                phone_number_id: extras.phone_number_id,
                business_id: extras.business_id
              })
            })
              .then(res => res.json())
              .then(data => {
                console.log('Onboarding complete:', data);
              })
              .catch(err => {
                console.error('Onboarding failed:', err);
              });
          } else {
            console.log('User cancelled or did not authorize.');
          }
        },
        {
          config_id: 'YOUR_CONFIG_ID',              // Replace with your Config ID from step 3.3
          response_type: 'code',
          override_default_response_type: true,
          extras: {
            sessionInfoVersion: 2                    // Returns WABA ID, phone number ID, business ID
          }
        }
      );
    }
  </script>

  <button onclick="launchEmbeddedSignup()"
    style="background-color: #1877f2; color: #ffffff; padding: 12px 24px; border: none; border-radius: 6px; font-size: 16px; cursor: pointer;">
    Connect WhatsApp
  </button>
</body>
</html>
```

<Note>
  Replace `YOUR_META_APP_ID` with your actual Meta App ID and `YOUR_CONFIG_ID` with the Config ID from your Facebook Login for Business settings (step 3.3).
</Note>

### 4.3 Backend — exchange code and share WABA

Your backend performs two steps after receiving the authorization code and session info from the frontend.

**Step A: Validate the authorization code with Meta**

Call the Meta Graph API `debug_token` endpoint to validate the code and retrieve the associated WABA details.

```bash theme={null}
curl -G "https://graph.facebook.com/v19.0/debug_token" \
  --data-urlencode "input_token=CODE_FROM_FRONTEND" \
  --data-urlencode "access_token=YOUR_META_APP_ID|YOUR_META_APP_SECRET"
```

The response confirms the code is valid and returns metadata including the scopes granted. If you already received the WABA ID, phone number ID, and business ID from the `sessionInfoVersion: 2` response in step 4.1, you can use those values directly.

**Step B: Call the Plivo Embedded Signup API**

Send a POST request to the Plivo Embedded Signup endpoint with the WABA ID, phone number ID, and business ID. This tells Plivo to onboard the WABA, attach it to the credit line, register webhooks, and activate the phone number for messaging.

```bash theme={null}
curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/WhatsApp/EmbeddedSignup/" \
  -H "Content-Type: application/json" \
  -u "<auth_id>:<auth_token>" \
  -d '{
    "waba_id": "WABA_ID_FROM_SIGNUP",
    "business_id": "BUSINESS_ID_FROM_SIGNUP",
    "phone_number_id": "PHONE_NUMBER_ID_FROM_SIGNUP",
    "client_ref": "customer-12345"
  }'
```

<Info>
  Replace `{auth_id}` and `{auth_token}` with the API credentials Plivo provided for your Tech Provider sub-account.
</Info>

## Embedded Signup API reference

### Endpoint

```bash theme={null}
POST https://api.plivo.com/v1/Account/{auth_id}/WhatsApp/EmbeddedSignup/
```

### Authentication

Use [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) with your Plivo Auth ID as the username and Auth Token as the password. These credentials are scoped to your Tech Provider sub-account.

### Request parameters

<ParamField body="waba_id" type="string" required>
  The WhatsApp Business Account ID returned by the Embedded Signup flow. This is the WABA that your customer created or selected during the signup dialog.
</ParamField>

<ParamField body="business_id" type="string" required>
  The Meta Business ID associated with your customer's Meta Business Portfolio. Returned by the Embedded Signup flow.
</ParamField>

<ParamField body="phone_number_id" type="string" required>
  The phone number ID registered during the Embedded Signup flow. This is the WhatsApp-enabled phone number your customer verified with an OTP.
</ParamField>

<ParamField body="client_ref" type="string">
  An optional reference string you can use to map this WABA to your internal customer identifier. Maximum 64 characters.
</ParamField>

### Sample request

```bash theme={null}
curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/WhatsApp/EmbeddedSignup/" \
  -H "Content-Type: application/json" \
  -u "<auth_id>:<auth_token>" \
  -d '{
    "waba_id": "109876543210987",
    "business_id": "198765432109876",
    "phone_number_id": "112233445566778",
    "client_ref": "customer-12345"
  }'
```

### Success response

**HTTP 200 OK**

```json theme={null}
{
  "api_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Embedded signup completed successfully.",
  "waba_id": "109876543210987",
  "phone_number_id": "112233445566778",
  "business_id": "198765432109876"
}
```

### Error responses

**HTTP 401 Unauthorized**

Returned when the Auth ID or Auth Token is invalid or missing.

```json theme={null}
{
  "api_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": "Authentication credentials were not provided or are invalid."
}
```

**HTTP 403 Forbidden**

Returned when your account does not have Tech Provider permissions or WhatsApp is not enabled.

```json theme={null}
{
  "api_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": "Your account is not authorized for the Embedded Signup API."
}
```

**HTTP 400 Bad Request**

Returned when request parameters are missing or invalid. The following table lists common scenarios.

| Scenario                          | Error message                                                               |
| --------------------------------- | --------------------------------------------------------------------------- |
| Missing `waba_id`                 | `waba_id is required.`                                                      |
| Missing `business_id`             | `business_id is required.`                                                  |
| Missing `phone_number_id`         | `phone_number_id is required.`                                              |
| Invalid `waba_id` format          | `waba_id is not a valid WhatsApp Business Account ID.`                      |
| WABA already onboarded            | `This WABA is already registered with Plivo.`                               |
| Phone number already registered   | `This phone number is already registered under another WABA.`               |
| Multi-Partner Solution not active | `Multi-Partner Solution is not active for your app. Contact Plivo support.` |

```json theme={null}
{
  "api_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": "waba_id is required."
}
```

**HTTP 500 Internal Server Error**

Returned when an unexpected error occurs on the server side. Retry the request after a short delay. If the error persists, contact [Plivo support](https://support.plivo.com/hc/en-us/requests/new).

```json theme={null}
{
  "api_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": "An internal error occurred. Please try again later."
}
```

### HTTP status summary

| Status code | Meaning               | When it occurs                                                                                        |
| ----------- | --------------------- | ----------------------------------------------------------------------------------------------------- |
| 200         | OK                    | Embedded Signup completed successfully. The WABA, phone number, and webhooks are configured.          |
| 400         | Bad Request           | One or more required parameters are missing, invalid, or the WABA/phone number is already registered. |
| 401         | Unauthorized          | Auth ID or Auth Token is missing or invalid.                                                          |
| 403         | Forbidden             | Your account lacks Tech Provider permissions or WhatsApp is not enabled.                              |
| 500         | Internal Server Error | An unexpected server-side error occurred. Retry after a short delay.                                  |