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 from Meta on how to complete this. When you embed the signup flow there are two pieces of extra data (as shown in the extras.setup object below) that it is important you set correctly

  1. Solution_Id: The solution id must be set to the solution id you got from completing this step. This ensures that your end customer is onboarded for both your business and for Bird to send messages for this customer

  2. Preverified_id: If you have acquired a number from Bird for your customer, this should already be pre-verified (authenticated) for use on WhatsApp. By including the preverified_id when launching the signup flow will mean the customer can onboard without having to get an OTP code for the number. See how to get the pre-verified id below

<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 to get the phone_number_id and waba_id after the user completes the embedded signup.

Adding test users to the embedded flow

For the embedded signup to work for real customers, you must apply for advanced access to the whatsapp_business_management permission. This requires you to demonstrate the end to end onboarding flow to Meta. To test the embedded signup flow see the following guide to add test users for your app

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

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

"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"
    }

Embedded signup completion

Once your customer has completed the embedded signup, you should collect the phone_number_id and waba_id from the sessionInfo object

{
  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 object which will contain a token which will be exchanged for a long lived access token

{
  "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 you have a long lived access token. You should use the Meta App_ID and App_Secret from the app you created earlier.

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.

pageInstall WhatsApp phone number in Bird CRM

Last updated