Embedded Signup

The Embedded Signup process collects business-related information from your enterprise customers, automatically generates all WhatsApp assets required by the platform, and grants your applicatio

This document explains how to implement Embedded Signup and capture the data it generates, so that new customers can create a WABA through your software.

Step 1: Add Allowed Domains

Log in to the Meta Developer App Dashboard and go to Facebook Login for Business > Settings > Client OAuth settings:

Set the following switches to Yes:

Client OAuth Login
Web OAuth Login
Enforce HTTPS
Embedded Browser OAuth Login
Use Strict Mode for redirect URIs
Login with the JavaScript SDK

⚠️ Notes:

Embedded Signup relies on the JavaScript SDK.
When enterprise customers complete the Embedded Signup flow, their WABA ID, business phone number ID, and an exchangeable token code are returned to the window that initiated the flow, but only if that page’s domain has been added to both Allowed Domains and Valid OAuth Redirect URIs.
Add all domains where you plan to deploy Embedded Signup (including test domains in development environments).
Only HTTPS-enabled domains are supported.

A Facebook Login for Business configuration defines which permissions to request and what additional information to collect when enterprise customers use Embedded Signup.

In the console, navigate to Facebook Login for Business > Configurations.

Click Create from template and select WhatsApp Embedded Signup Configuration With 60 Expiration Token to create a configuration.

This template generates a configuration with the most commonly used permissions and access levels.

After configuration is complete, record the Configuration ID — it will be needed in the next step.

Add the following HTML and JavaScript code to your website. This is the complete code required to implement Embedded Signup.

We recommend building different Embedded Signup flows depending on your solution or customer needs:

<html>
  <head>
    <meta charset="utf-8" />
    <script>
      window.fbAsyncInit = function () {
        FB.init({
          appId: '{YOUR-FACEBOOK-APP-ID}', // Facebook App ID
          cookie: true,
          xfbml: true,
          version: 'v22.0', // Graph API version
        })
      }

      ;(function (d, s, id) {
        var js, fjs = d.getElementsByTagName(s)[0]
        if (d.getElementById(id)) return
        js = d.createElement(s)
        js.id = id
        js.setAttribute('defer', true)
        js.src = 'https://connect.facebook.net/en_US/sdk.js'
        fjs.parentNode.insertBefore(js, fjs)
      })(document, 'script', 'facebook-jssdk')

      function launchWhatsAppSignup() {
        FB.login(
          function (response) {
            if (response.status === 'connected' && response.authResponse) {
              const code = response.authResponse.code
              console.log('User authResponse code:', code)
              // Send the code to your backend to exchange for a System User access token
            } else {
              console.log('User cancelled login or did not fully authorize.')
            }
          },
          {
            config_id: '{YOUR-CONFIGURATION-ID}',
            response_type: 'code',
            override_default_response_type: true,
            extras: {
              features: [{ name: 'marketing_messages_lite' }],
              setup: { solutionID: '{YOUR-SOLUTION-ID}' },
              sessionInfoVersion: '3',
            },
          },
        )
      }

      const sessionInfoListener = (event) => {
        if (!event.origin?.endsWith('facebook.com')) return
        try {
          const data = JSON.parse(event.data)
          if (data.type === 'WA_EMBEDDED_SIGNUP') {
            if (data.event === 'FINISH') {
              const { phone_number_id, waba_id, businessId } = data.data
              console.log(
                'Business ID ', businessId,
                'Phone number ID ', phone_number_id,
                'WABA ID ', waba_id
              )
            } else if (data.event === 'ERROR') {
              console.error('error ', data.data.error_message)
            } else {
              console.warn('Cancel at ', data.data.current_step)
            }
          }
        } catch {
          console.log('Non JSON Response', event.data)
        }
      }

      window.addEventListener('message', sessionInfoListener)
    </script>
  </head>
  <body>
    <button onclick="launchWhatsAppSignup()" style="background-color:#1877f2;border:0;border-radius:4px;color:#fff;cursor:pointer;font-family:Helvetica,Arial,sans-serif;font-size:16px;font-weight:bold;height:40px;padding:0 24px;">
      Launch Embedded Signup
    </button>
  </body>
</html>

⚠️ Notes:

Replace appId, config_id, and solutionID with real values.
The frontend must pass waba_id and phone_number_id to your backend to retrieve the WABA and register the number (see below).

More details: https://developers.facebook.com/docs/whatsapp/embedded-signup/implementation

2. Retrieve WABA and Register Phone Number

After customers complete Embedded Signup, your frontend will receive waba_id and phone_number_id. Pass them to your backend for API calls.

Retrieve WABA

curl 'https://api.ycloud.com/v2/whatsapp/businessAccounts/{{waba_id}}' \
  -H 'X-API-Key: {{YOUR-API-KEY}}'

Sample Response

{
  "id": "{{waba_id}}",
  "name": "WABA name",
  "accountReviewStatus": "APPROVED",
  "paymentMethodAttached": true,
  "currency": "EUR",
  "timezoneId": "1"
}

👉 If paymentMethodAttached is true, YCloud has successfully attached a payment method to this WABA. Otherwise, contact the YCloud team.

Register Phone Number

curl -XPOST 'https://api.ycloud.com/v2/whatsapp/phoneNumbers/{{waba_id}}/{{phone_number_id}}/register' \
  -H 'X-API-Key: {{YOUR-API-KEY}}'

Sample Response

{
  "phoneNumber": "{{phonenumber}}",
  "wabaId": "{{waba_id}}",
  "verifiedName": "Phone number name",
  "qualityRating": "GREEN",
  "messagingLimit": "TIER_250",
  "status": "CONNECTED"
}

<html>
  <head>
    <meta charset="utf-8" />
    <script>
      window.fbAsyncInit = function () {
        FB.init({
          appId: '{YOUR-FACEBOOK-APP-ID}',
          cookie: true,
          xfbml: true,
          version: 'v22.0',
        })
      }

      ;(function (d, s, id) {
        var js, fjs = d.getElementsByTagName(s)[0]
        if (d.getElementById(id)) return
        js = d.createElement(s)
        js.id = id
        js.setAttribute('defer', true)
        js.src = 'https://connect.facebook.net/en_US/sdk.js'
        fjs.parentNode.insertBefore(js, fjs)
      })(document, 'script', 'facebook-jssdk')

      function launchWhatsAppSignup() {
        FB.login(
          function (response) {
            if (response.status === 'connected' && response.authResponse) {
              const code = response.authResponse.code
              console.log('User authResponse code:', code)
            } else {
              console.log('User cancelled login or did not fully authorize.')
            }
          },
          {
            config_id: '{YOUR-CONFIGURATION-ID}',
            response_type: 'code',
            override_default_response_type: true,
            extras: {
              setup: { solutionID: '{YOUR-SOLUTION-ID}' },
              sessionInfoVersion: 3,
              featureType: 'whatsapp_business_app_onboarding',
            },
          },
        )
      }

      const sessionInfoListener = (event) => {
        if (!event.origin?.endsWith('facebook.com')) return
        try {
          const data = JSON.parse(event.data)
          if (data.type === 'WA_EMBEDDED_SIGNUP') {
            if (data.event === 'FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING') {
              const { business_id, waba_id, phone_number_id } = data.data
              console.log(
                'Business ID ', business_id,
                'WABA ID ', waba_id,
                'Phone number ID ', phone_number_id
              )
            } else if (data.event === 'ERROR') {
              console.error('error ', data.data.error_message)
            } else {
              console.warn('Cancel at ', data.data.current_step)
            }
          }
        } catch {
          console.log('Non JSON Response', event.data)
        }
      }

      window.addEventListener('message', sessionInfoListener)
    </script>
  </head>
  <body>
    <button onclick="launchWhatsAppSignup()" style="background-color:#1877f2;border:0;border-radius:4px;color:#fff;cursor:pointer;font-family:Helvetica,Arial,sans-serif;font-size:16px;font-weight:bold;height:40px;padding:0 24px;">
      Launch Embedded Signup
    </button>
  </body>
</html>

2. Retrieve WABA and Bind to YCloud

After customers complete Embedded Signup, your frontend will receive waba_id. Pass it to your backend for further API calls.

Call the YCloud SMB Bind API. Once successful, associate the WABA with your customer’s account in your system.

curl 'POST /v2/whatsapp/businessAccounts/{wabaId}/smb/bind' \
  -H 'X-API-Key: {{YOUR-API-KEY}}'

Sample Response

{
  "id": "{{phonenumber_id}}",
  "phoneNumber": "{{phonenumber}}",
  "wabaId": "{{waba_id}}",
  "qualityRating": "GREEN",
  "messagingLimit": "TIER_1K",
  "verifiedName": "John's Cake Shop",
  "codeVerificationStatus": "VERIFIED",
  "isOfficialBusinessAccount": true,
  "status": "PENDING",
  "nameStatus": "APPROVED",
  "newNameStatus": "APPROVED",
  "decision": "APPROVED",
  "requestedVerifiedName": "string",
  "rejectionReason": "string",
  "qualityUpdateEvent": "ONBOARDING"
}

FAQ

How to verify whether the Embedded Signup configuration is correct?

If you have configured the solutionID correctly, customers will see the real name of the Solution Partner during Facebook authorization. If they do not see it, the configuration has not taken effect.

Please make sure that App Review has been completed.

In what cases can YCloud fail to attach a payment method to a WABA?

This may happen if the user selects an existing WABA instead of creating a new one. The existing WABA may already have a payment method that has not been removed.

Embedded Signup Error: App not active

When opening the Embedded Signup page, the following message may appear:

App not active This app is not currently accessible and the app developer is aware of the issue. You will be able to log in when the app is reactivated.

This happens when the app is in Development mode, where only test users have permission (see App Dashboard > App roles > Roles / Test Users).

Solution: Switch the app mode to Live via Meta Apps by opening the corresponding app in the Dashboard. Alternatively, authorize the current user. See: Assign business assets to people in your business portfolio.

Embedded Signup Error: Feature unavailable

When opening the Embedded Signup page, the following message may appear:

Feature unavailable Facebook Login is currently unavailable for this app as we are updating additional details for this app. Please try again later.

Solution: Go to App Dashboard > App Review > Permissions and Features and apply for public_profile advanced access.

PreviousTechnical Development Partner Onboarding NextTechnical Development Partner Pricing, Billing, and Payment Methods

Last updated 2 minutes ago

Step 1: Add Allowed Domains

Step 2: Create a Facebook Login for Business Configuration ID

Step 3: Integrate Embedded Signup into Your Website

Embedded Signup – Creating a WhatsApp API Account

1. Create the Embedded Signup Button

2. Retrieve WABA and Register Phone Number

Embedded Signup – WhatsApp Business App Coexistence

1. Create the Embedded Signup Button

2. Retrieve WABA and Bind to YCloud

FAQ