# Setting up the WhatsApp Embedded flow

To onboard your customers onto WhatsApp, you will need to integrate the WhatsApp embedded flow into your own platform. This enables your customers to share permissions for you and Bird to manage their WhatsApp business account and send messages on their behalf. Customers share permissions by logging in through the embedded signup flow.

## Setting up the embedded flow

See the following [guide](https://developers.facebook.com/docs/whatsapp/embedded-signup/embed-the-flow#embed-the-signup-flow) from Meta on how to complete this. When embedding the signup flow, there are two important extra data fields (as shown in the `extras.setup` object below) that must be set correctly:

1. **Solution\_Id**: This should be set to the `solutionId` obtained after you [connected to Bird as a solutions provider](https://docs.bird.com/applications/channels/channels/supported-channels/whatsapp/how-to/become-a-whatsapp-tech-provider/connecting-to-bird-as-solutions-provider). This ensures that your end customer is onboarded for both your business and allows Bird to send messages on behalf of this customer
2. **Preverified\_Id**: If you’ve [obtained a number from Bird](https://docs.bird.com/api/channels-api/supported-channels/programmable-whatsapp/whatsapp-isv-integration/setting-up-your-customer-workspaces/buying-a-number-through-bird) for your customer, it will already be pre-verified (authenticated) for WhatsApp. Including the `preverified_id` when launching the signup flow enables the customer to onboard without needing to receive an OTP code for the number. See the instructions below on how to obtain the [pre-verified Id.](#getting-pre-verified-number-id-optional)

```javascript
<script type="text/javascript">
  document.getElementById('login-btn').onclick = () =>
    FB.login(response => {}, {
      config_id: '{{config_id}}', 
      response_type: 'code',    
      override_default_response_type: true, 
      extras: {
        setup: {
          solutionID: {{solution_id}}
          preVerifiedPhone: {
            ids: ['{{preverified Id}}']
          },...
        }
      }
    });
</script>

```

You should also implement [session logging](https://developers.facebook.com/docs/whatsapp/embedded-signup/embed-the-flow#step-7--optional---session-logging) to get the phone\_number\_id and waba\_id after the user completes the embedded signup.

### **Resolving the phone number (BYON - Bring your own number)**

&#x20;If your customer is bringing their own number, you can resolve the `phone_number_id` to the actual phone number by calling the Meta Graph API:\
`GET https://graph.facebook.com/v25.0/{phone_number_id}?fields=display_phone_number`

Use the Business Integration System User Access Token returned during the Embedded Signup flow (see [Meta's documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/access-tokens/#business-integration-system-user-access-tokens)). Ensure your app has **advanced access** to the `whatsapp_business_management` permission.

## Apply for advanced access to Meta public\_profile

For the embedded signup to work, you must apply for advanced access to the public\_profile permission on your Meta app. In the Meta for developers app dashboard, navigate to your **App Review > Permissions** **and features** are ensure you have advanced access as shown

&#x20;

<figure><img src="https://3210271997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FwT1gsl9DZ500XMayMe5P%2Fimage.png?alt=media&#x26;token=0ac1a0a4-c9f7-4d5e-8a4b-0f74a3fc721d" alt=""><figcaption></figcaption></figure>

## Getting pre-verified number ID (optional)

If you have purchased a number for your customer through Bird CRM, this should be automatically pre-verified for use on WhatsApp. This typically takes around 5 minutes from completing the number purchase. To list the numbers in your workspace you can list them as follows

{% openapi src="<https://global--openapi-specs--151603429280--use1.s3.amazonaws.com/public-specs/numbers/numbers.yml>" path="/workspaces/{workspaceId}/numbers/{numberId}" method="get" %}
<https://global--openapi-specs--151603429280--use1.s3.amazonaws.com/public-specs/numbers/numbers.yml>
{% endopenapi %}

{% tabs %}
{% tab title="WhatsApp object" %}
To get the pre-verified number ID check the number.whatsApp object as follows. You should make use of the `whatsAppId.`In addition before starting the embedded flow ensure that:

1. status: verified
2. stage: final
3. verificationExpiresAt is after now

```json
"whatsApp": {
        "whatsAppId": "7734737979921234",
        "status": "verified",
        "stage": "final",
        "attempt": 0,
        "nextAttemptAt": "0001-01-01T00:00:00Z",
        "requestedCodeAt": "2024-05-22T22:22:11.351Z",
        "verificationExpiresAt": "2024-08-20T22:22:58Z",
        "createdAt": "2024-05-22T22:21:51.099Z",
        "updatedAt": "2024-05-22T22:24:09.555Z"
    }
```

{% endtab %}

{% tab title="Full Response" %}
The below is the example response when getting your Bird number

```json
{
    "type": "local",
    "country": "US",
    "number": "+1234567890",
    "capabilities": {
        "voice": {
            "inbound": true,
            "outbound": true
        },
        "sms": {
            "inbound": true,
            "outbound": true
        },
        "mms": {
            "inbound": true,
            "outbound": true
        },
        "fax": {
            "inbound": false,
            "outbound": false
        }
    },
    "monthlyRecurringPrice": {
        "currencyCode": "EUR",
        "amount": 110000,
        "exponent": -6
    },
    "complianceRequirements": [
        {
            "name": "kyc:origin",
            "scope": "number-activation",
            "type": "kycForm",
            "selector": {
                "scope": "number",
                "countryCode": "US",
                "numberType": "local"
            }
        },
        {
            "name": "usecase:sms",
            "scope": "sms-outbound",
            "type": "useCase",
            "selector": {
                "platform": "sms-messagebird",
                "countryCode": "US",
                "numberType": "local"
            }
        },
        {
            "name": "whatsapp:verification",
            "scope": "whatsapp",
            "type": "whatsappVerification",
            "inventoryId": "00000000-0000-46b1-a954-961702a4c88f"
        }
    ],
    "id": "00000000-0000-46b1-a954-961702a4c88f",
    "workspaceId": "00000000-0000-46b1-a954-961702a4c88f",
    "status": "active",
    "configurations": {},
    "createdAt": "2024-05-22T22:21:51.049Z",
    "updatedAt": "2024-05-22T22:21:51.049Z",
    "activatedAt": "2024-05-22T22:21:51.049Z",
    "deactivatedAt": null,
    "deactivatesAt": null,
    "subscription": {
        "status": "active",
        "subscribedAt": "2024-05-01T00:00:00Z",
        "updatedAt": "2024-05-01T00:00:00Z",
        "cancelledAt": "0001-01-01T00:00:00Z"
    },
    "endpointSubscription": {
        "id": "00000000-0000-46b1-a954-961702a4c88f",
        "correlationId": "00000000-0000-46b1-a954-961702a4c88f",
        "status": "active",
        "subscribedAt": "2024-05-01T00:00:00Z",
        "updatedAt": "2024-05-01T00:00:00Z"
    },
    "requirements": [
        {
            "requirement": {
                "name": "kyc:origin",
                "scope": "number-activation",
                "type": "kycForm",
                "selector": {
                    "scope": "number",
                    "countryCode": "US",
                    "numberType": "local"
                }
            },
            "status": "ok",
            "reference": null
        },
        {
            "requirement": {
                "name": "usecase:sms",
                "scope": "sms-outbound",
                "type": "useCase",
                "selector": {
                    "platform": "sms-messagebird",
                    "countryCode": "US",
                    "numberType": "local"
                }
            },
            "status": "no-reference",
            "reference": null,
            "notOkSince": "2024-05-22T22:21:51.095Z"
        },
        {
            "requirement": {
                "name": "whatsapp:verification",
                "scope": "whatsapp",
                "type": "whatsappVerification",
                "inventoryId": "00000000-0000-46b1-a954-961702a4c88f"
            },
            "status": "ok",
            "reference": "7734737979921234"
        }
    ],
    "whatsApp": {
        "whatsAppId": "7734737979921234",
        "status": "verified",
        "stage": "final",
        "attempt": 0,
        "nextAttemptAt": "0001-01-01T00:00:00Z",
        "requestedCodeAt": "2024-05-22T22:22:11.351Z",
        "verificationExpiresAt": "2024-08-20T22:22:58Z",
        "createdAt": "2024-05-22T22:21:51.099Z",
        "updatedAt": "2024-05-22T22:24:09.555Z"
    },
    "endpoint": {
        "id": "00000000-0000-46b1-a954-961702a4c88f",
        "type": "long-code-number",
        "instanceId": "00000000-0000-46b1-a954-961702a4c88f",
        "name": "+1234567890",
        "provisioningStatus": "provisioned",
        "createdAt": "2024-05-22T22:21:51.049Z",
        "updatedAt": "2024-05-23T10:47:12.325Z",
        "capabilities": [
            {
                "name": "voice",
                "inbound": {
                    "status": "active"
                },
                "outbound": {
                    "status": "active",
                    "destinationStatuses": {
                        "active": 1,
                        "available": 185
                    },
                    "supportsDestinations": true
                }
            },
            {
                "name": "sms",
                "inbound": {
                    "status": "active"
                },
                "outbound": {
                    "status": "active",
                    "destinationStatuses": {
                        "active": 1,
                        "available": 185
                    },
                    "supportsDestinations": true
                }
            },
            {
                "name": "mms",
                "inbound": {
                    "status": "active"
                },
                "outbound": {
                    "status": "active",
                    "destinationStatuses": {
                        "active": 1,
                        "available": 1
                    },
                    "supportsDestinations": true
                }
            },
            {
                "name": "whatsapp",
                "inbound": {
                    "status": "active"
                },
                "outbound": {
                    "status": "unavailable",
                    "supportsDestinations": false
                }
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

## Embedded signup completion

\
Once your customer has completed the embedded signup, you should collect the phone\_number\_id and waba\_id from the [sessionInfo](https://developers.facebook.com/docs/whatsapp/embedded-signup/embed-the-flow#step-7--optional---session-logging) object

```json
{
  data: {
    phone_number_id: "<PHONE-ID>",
    waba_id: "<WABA-ID>",
  },
  type: "WA_EMBEDDED_SIGNUP",
  event: "FINISH",
  version: 2
}
```

In addition you should get an [authResponse](https://developers.facebook.com/docs/whatsapp/embedded-signup/embed-the-flow#after-business-completes-signup-flow) object which will contain a token which will be exchanged for a long lived access token

```json
{
  "authResponse": {
    "userID": null,
    "expiresIn": null,
    "code": "<CODE_TO_BE_EXCHANGED>"
  },
  "status": "connected"
}
```

## Exchange debug token for long lived token

Once the embedded signup has been completed and you have the `phone_number_id`, `waba_id`, and `code` you should submit this to an api endpoint e.g. \<somedomain>/installwhatsapp. In addition if you are using a number bought via Bird then you should also include the unique id of the number

From this API you can then [exchange the code](https://developers.facebook.com/docs/whatsapp/embedded-signup/embed-the-flow#after-business-completes-signup-flow) you have a long lived access token. You should use the Meta App\_ID and App\_Secret from the app you created earlier.

```bash
GET https://graph.facebook.com/v20.0/oauth/access_token?
  client_id=<APP_ID>
  &client_secret=<APP_SECRET>
  &code=<CODE>

```

You should securely associate the long lived token and WABA ID with the customer account in your platform.

{% content-ref url="install-whatsapp-phone-number-in-bird-crm" %}
[install-whatsapp-phone-number-in-bird-crm](https://docs.bird.com/api/channels-api/supported-channels/programmable-whatsapp/whatsapp-isv-integration/whatsapp-channel-onboarding/install-whatsapp-phone-number-in-bird-crm)
{% endcontent-ref %}