Embedded Signup

Embedded Signup is an authentication and authorization desktop- and mobile-compatible interface that makes it easy for your business customers to generate the assets you will need to successfully onboard them to the WhatsApp Business Platform.

Something Went Wrong

We're having trouble playing this video.

Learn more

The Embedded Signup flow gathers business-related information from your business customers, automatically generates all WhatsApp assets needed by the platform, and grants your app access to these assets, so you can quickly provide your business customers with WhatsApp messaging services.

Customers onboarded via Embedded Signup own all of their WhatsApp assets and can leverage these assets with other Meta solutions such as Ads that Click to WhatsApp.

How it works

Embedded Signup leverages the Facebook Login for Business product and our JavaScript SDK. Once configured, you can add a link or button to your website or portal that launches the flow.

Business customers who click the link or button will be presented with a new window where they can:

• authenticate their identity using their Facebook or Meta Business Credentials
• grant your app access to their WhatsApp assets
• select an existing business portfolio or create a new one
• select an existing WhatsApp Business Account (WABA) or create a new one
• enter and verify their business phone number (their own, or one you have provided)
• enter a display name that can appear in place of their number in the WhatsApp client

Upon successful completion, Embedded Signup returns the customer's WABA ID, business phone number ID, and an exchangeable token code, to the window that spawned the flow. You must send this data to your server and use it in a server-to-server call to:

• exchange the code for a customer-scoped business token
• register the customer's business phone number for Cloud API use
• subscribe your app to webhooks on the customer's WABA
• share your credit line with the customer (Solution Partners only)

When these steps are complete, if you are a Solution Partner or are partnered with one, the customer can begin using your or your partner's app for messaging immediately. If you are not a Solution Partner, or not partnered with one, the customer must first attach a payment method to their WABA before they can begin messaging.

Limitations

Onboarding limits

By default, you can onboard up to 10 new business customers in a rolling 7-day window. Only newly onboarded customers count against this limit. You can see your current onboarded customer count in the WhatsApp Manager > Partner overview panel. You will be notified by email if you approach this limit.

If you complete Business Verification, App Review, and Access Verification, we will automatically increase your limit to 200 new business customers in a rolling 7-day window. If you need to onboard more than 200 customers per week, apply to become a Meta Business Partner.

Business customer messaging limits

Business customers onboarded via Embedded Signup start with standard messaging limits, which can be increased through API usage.

Business customer phone number limits

• Business business phone numbers can only be registered for use with Cloud API.
• Businesses phone numbers already registered for use with On-Premises API, or in use with WhatsApp or the WhatsApp Business App, are not supported.
• Business customers onboarded via Embedded Signup start with default business phone number limits.

Default flow

See Default Flow for descriptions of each screen that your business customers will be presented with as part of the default implementation of Embedded Signup.

Note that if you know information about your customer's business, you can inject this data, which can significantly reduce the number of screens that your customers have to interact with.

Access tokens

Embedded Signup generates business integration system user access tokens ("business tokens"). When a business customer completes the Embedded Signup flow, an exchangeable token code will be returned as a message event and captured by the JavaScript SDK. You must exchange this code for a business token using a server-to-server call.

If you are a Tech Provider, you will use business tokens exclusively.

If you are a Solution Partner, you will use your system user access token ("system token") to share your credit line with onboarded business customers, and business tokens for everything else. Note that the system user who the token represents must have granted your app the business_management permission, and must have been granted an Admin or Financial Editor role on your business portfolio, in order to be able to share your credit line.

Permissions

Embedded Signup can be configured to request most permissions from your business customers, but you are likely only going to need:

• whatsapp_business_management — necessary if your app needs access to onboarded customer WhatsApp Business Account settings and message templates.
• whatsapp_business_messaging — necessary if your app needs access to onboarded customer business phone number settings, or if your app will be used by customers to send and receive messages.

You can specify which permissions your app needs during the implementation process.

Note that while your app is in development mode, these permissions will appear in Embedded Signup's authorization screen to anyone who has an admin, developer, or tester role on your app. However, once you switch your app to live mode, only permissions that have been approved for advanced access through the App Review process will appear in the flow.

Billing

Solution Partners

If you are a Solution Partner, you must already have a line of credit and have accepted the Credit Allocation API terms in the Business Settings > Payments panel in the Meta Business Suite. In addition, you must share your line of credit with any customers as part of the onboarding process.

Tech Providers and Tech Partners

If you are a Tech Provider or Tech Partner, your onboarded business customers must add a payment method to their WhatsApp Business Account. They can do this by following the steps described in our Add a credit card to your WhatsApp Business Platform account Help Center article.

Sandbox accounts

You can test the Embedded Signup flow using your own Facebook account, but this can result in additional business portfolios, WABAs, and business phone numbers. If you don't want to clutter your account with test data, you can claim a sandbox test account instead, and use it to simulate a business customer completing the flow.

When you complete the flow using the sandbox test account, the sandbox test account's WABA ID, business phone number ID, and an exchangeable token code will be returned, just as if it were a real customer completing the flow.

To claim your sandbox test user, navigate to the App Dashboard > WhatsApp > Quickstart panel, locate the Testing Integrations section, then click the Claim sandbox account button.

Sandbox account limitations

• Sandbox accounts are only available to Tech Providers and Tech Partners.
• Sandbox accounts are valid for 30 days, after which they will be deactivated and must be reclaimed in order to be used again.
• The sandbox account cannot be used to create additional sandbox business portfolios, WABAs, or business phone numbers; the assets are generated automatically and will appear in the Embedded Signup flow.
• The sandbox account is associated with the app's admin. In order for the sandbox account's assets to appear in the Embedded Signup flow, the app admin must be signed into their Meta developer account.
• The sandbox account's business portfolio will not appear in the Meta Business Suite or WhatsApp Manager
• You can exchange the returned token code for the sandbox account's business token and use it to get data on the account's WABA ID, but the business phone number cannot be used to send or receive messages.

555 business phone numbers

Business customers with verified businesses or businesses that have had their Cloud API messaging limits increased are eligible for up to two 555 business phone numbers.

These numbers behave the same way as standard business phone numbers (display names must be reviewed and approved, subject to conversation-based pricing rules, impacted by quality ratings, etc.), with the following key differences:

• Have a US country calling code (+1)
• Have a 555 area code
• Are verified automatically
• Cannot be migrated to another WhatsApp Business Account, or used outside of the WhatsApp Business platform

If your business customers are eligible for 555 numbers and want to register one as an additional number, instruct them to go through your implementation of Embedded Signup again. When asked to select a business phone number, they will automatically be given the option to choose a 555 number:

Asset migration

Embedded Signup can be used to migrate onboarded business customer assets in several ways. See Migrating business customer assets.

App Review

You will not be able to onboard business customers until your app has been approved for advanced access for each of the permissions it requires.

See App Review to learn more about App Review and what you must provide in order to complete the process successfully.

Integration Helper

The Embedded Signup Integration Helper is a setup and testing tool within the App Dashboard. The tool allows you to:

• launch Embedded Signup in various flow configurations
• see data that gets returned when a business customer completes the flow
• generate implementation code and onboarding queries, which you can copy and paste into your website, business customer portal, and server
• send API queries to endpoints you will need to use when onboarding customers who complete the flow

You can access the integration helper by navigating to App Dashboard > WhatsApp > ES Integration.

Webhooks

As part of the onboarding process, you must subscribe your app to webhooks on the WABA of each business customer who completes the Embedded Signup flow.

Webhooks will be triggered and sent to the callback URL configured on your app, according to the webhook fields you have subscribed to. This means that all webhooks for all of your onboarded business customers will be sent to your app's callback URL. However, you can override the callback URL on an individual WhatsApp Business Account or business phone number. See Webhook Overrides to learn how to do this.

Localization

The Embedded Signup flow is available in 30 languages. The localized flow is automatically triggered based on the language that the business customer uses Facebook in.

Arabic, Czech, Danish, Greek, English (UK), Spanish (Spain), Spanish, Finnish, French (France), Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Norwegian (bokmal), Dutch, Polish, Portuguese (Brazil), Portuguese (Portugal), Romanian, Russian, Swedish, Thai, Turkish, Vietnamese, Simplified Chinese (China), Traditional Chinese (Hong Kong), Traditional Chinese (Taiwan).

Next steps

Learn how to implement Embedded Signup into your website or portal.