Migrating customer assets

You can use Embedded Signup to migrate various types of customer assets, such as WhatsApp Business Accounts (WABAs) and business phone numbers, among Solution Partners and Tech Providers.

Switching Solution Partners without Multi-Partner Solutions

If you are Solution Partner, business customers can switch from their current Solution Partner over to you by unsharing their WABA with their current partner and resharing it with you. All business phone numbers and templates associated will continue to work normally once the process is complete.

Once the customer initiates the process, they will be unable to send messages again until you replace their current credit line with yours. This happens on the 1st of the following month in which you use the API to share your credit line. Note, however, that you cannot use the API to share your credit line (with a customer who has switched partners) the last 3 days or first 4 days of any month. Therefore, to ensure the shortest amount of downtime for customers, advise them to begin the process near the end of the month, but at least 3 days before it ends, so you can perform the API call in the same month.

Limitations

• Customers must own their WABA. WABAs owned by Solution Partners (the On-Behalf-Of model) are not supported.
• Once the customer initiates the process, they will be prevented from sending messages until your credit line replaces their current credit line. This happens on the 1st of the month after which you successfully use the API to share your credit line with the customer.
• You cannot use the API to share your credit line (with a customer who has switched providers) the last 3 days or first 4 days of any month.
• Business phone numbers in-use with the On-Premises API must be re-registered as part of the process. Business phone numbers in-use with Cloud API do not need to be re-registered.

Step 1: Instruct customer to unshare WABA

Instruct the customer to use the Business Manager to unshare their WhatsApp Business Account with their current partner. They can do this by in Business Manager by navigating to:

Business Settings > Accounts (menu section) > WhatsApp Accounts > Partners (tab)

Once in the Partners tab, they can select their current partner, click the delete icon (trash can), and complete the flow to unshare their WABA.

You can provide the customer with the following link, which allows them to directly load their business portfolio in the Business Settings panel:

https://business.facebook.com/settings

Alternatively, you can direct the customer to the following Help Center article:

Manage Your WhatsApp Business Solution Provider’s Permissions

Keep in mind that once the customer completes this step, they will be prevented from sending messages until your credit line replaces their current credit line. This happens on the first of the month after you share your credit line with the customer.

If the customer attempts to send a message during this period, the API will return error code 131042 and a messages webhook will be sent to their current Solution Partner containing the same code.

Step 2: Instruct customer to complete Embedded Signup

Direct the customer to your implementation of Embedded Signup. Instruct them to complete the flow and to select their existing WABA when they see the This WhatsApp Business account was previously shared warning.

Once they select their existing WABA and proceed, the flow will end, so they do not need to select a business phone number.

Step 3: Get Asset IDs From Session Log

If you are using session logging, capture the customer's WABA ID when they complete the flow. Note that their business phone number will not be included in the session log.

Step 4: Exchange Code for Token

Exchange the returned code when the customer completes the flow for a business integration system user access token.

Step 5: Add System User to WABA

If you are using a system user access token (which is not recommended) instead of business integration system user access tokens, add your system user to the WABA using Business Manager:

Business Settings > Accounts (menu section) > WhatsApp Accounts > [Customer WABA] > People (tab) > Assign People (button)

Step 6: Share Your Credit Line

Share your credit line with the customer. This change will not be reflected until the first of the following month. Until then, the customer will continue to share their previous Solution Partner's credit line, but will be prevented from sending messages.

On the first of the following month, your credit line will replace the customer's previous credit line, and the customer can resume messaging.

Example

• April 20: A customer unshares their WABA with their previous Solution Partner. The customer is now prevented from messaging.
• April 21: The customer completes your implementation of Embedded Signup. You capture the customer's credentials and access token, and share your credit line with them. The previous Solution Partner's credit line is still shared with the customer, but the customer is still being prevented from messaging.
• May 1: Your credit line replaces the customer's previous credit line. The customer can now send messages again. Any conversations opened by the customer will be billed to your credit line.

Switching Solution Partners with Multi-Partner Solutions

If you are a Tech Provider, you can migrate a business customer from one Solution Partner who you are partnered with as part of a Multi-Partner Solution (the "source" partner and solution) to another Solution Partner who you partnered with as part of another Multi-Partner Solution (the "destination" partner and solution).

As part of this process, a new WhatsApp Business Acount (WABA) will be created for the business customer, and templates within the source WABA will be duplicated in the destination WABA.

Requirements

Your app (or apps, if you are using separate apps) used to create or accept the source and destination Multi-Partner Solutions must be associated with the same business portfolio. The destination solution must be in an Active state.

Templates

Billing

Tech Provider steps

Step 1: Tag the customer WABA for migration

Use the POST /<WHATSAPP_BUSINESS_ACCOUNT>/set_solution_migration_intent endpoint to tag the business customer's WABA for migration.

Request:

curl 'https://graph.facebook.com/v21.0/486585971195941/set_solution_migration_intent' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <BUSINESS_TOKEN>' \
-d '
{
"solution_id": <DESTINATION_MULTI-PARTNER_SOLUTION_ID>
}'

Response:

{
"id": "<MIGRATION_INTENT_ID>"
}

Capture the migration intent ID. Currently this ID is not used but later can be used to look up migration status.

Step 2: Instruct the customer to disable two-factor authentication

Instruct the business customer to disable two-step verification on their number. You can provide them with these instructions:

1. Access the WhatsApp Manager at https://business.facebook.com/latest/whatsapp_manager/.
2. Navigate to Account tools > Phone numbers, and click the phone number's settings (gear) icon. If you don't see your business phone number, click Overview in the menu on the left, then locate the number and click it.
3. Click the Two-step verification tab.
4. Click the Turn off two-step verification button and complete the flow.

Alternatively, if you have access to the business customer's WhatsApp Manager, you can disable two-step verification for them.

Step 3: Instruct the customer to complete Embedded Signup

Instruct the customer to complete the Solution Partner's implementation of Embedded Signup.

Make sure that you are directing the customer to the Embedded Signup implementation correctly configured with the destination Multi-Partner Solution ID, otherwise the customer could be onboarded via the wrong solution.

You can provide the customer with these instructions:

1. Enter your existing business portfolio name in the business portfolio screen.
2. Create a new WhatsApp Business Account (WABA) in the WABA selection screen.
3. Enter your existing business phone number in the phone number addition screen. This will trigger a warning that the number will be moved to a new WhatsApp Business Account.

Destination Solution Partner steps

Provide the Tech Provider with a link to your implementation of Embedded Signup configured with the Multi-Partner Solution ID, and whenever a business customer completes the flow successfully, onboard the business customer as you normally would.

Migrating Phone Numbers Between WhatsApp Business Accounts

See Migrating Phone Numbers Between WhatsApp Business Accounts via Embedded Signup.

Adding a WABA to a Multi-Partner Solution

If you are a Solution Partner and are part of an active multi-partner solution, you can designate a WABA as eligible for the solution. This sends a Business Manager request to the business customer who owns the WABA. The customer can then use the Business Manager to accept and confirm the request.

Confirmation associates the WABA with the solution, thereby granting permissions (already defined on the solution) to any Tech Providers who are part of it.

Note that if you own the WABA and are sharing it with your customer (the On-Behalf-Of ownership model, you can transfer ownership to your customer, and as part of the transfer process, designate the WABA as eligible for the solution by including the solution ID in the post body. The customer can then either confirm or reject the access request using Embedded Signup or the Business Manager.

If you're unsure of the WABA's ownership model, request the ownership_type field on the WABA ID. A value of ON_BEHALF_OF indicates you own the WABA, while CLIENT_OWNED indicates that your business customer owns the WABA.

Requirements

• The WABA must have been onboarded by you.
• The WABA cannot already be part of an existing active solution.
• The solution must be in an active state.

Step 1: Designate the WABA as solution eligible

Use the POST /<WABA_ID>/set_solution_migration_intent endpoint to designate a WABA owned by your business customer as eligible for an active solution. If you own the WABA, you must use the WABA ownership transfer process instead.

Request Syntax

POST /<WABA_ID>/set_solution_migration_intent

Post Body

{
  "solution_id": "<SOLUTION_ID>"
}

Response

Upon success:

{
  "id": "<WHATSAPP_BUSINES_ACCOUNT_SOLUTION_MIGRATION_INTENT_ID>"
}

In addition, a confirmation request will be sent to the business customer who owns the WABA.

Example Request

curl -X POST 'https://graph.facebook.com/v21.0/102290129340398/set_solution_migration_intent' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "solution_id": "795033096057724"
}'

Example Response

{
  "id": "102290129340398"
}

Step 2: Instruct the customer to confirm

Instruct your business customer to use the Meta Business Suite to accept and confirm the solution partner access request.

Send the customer the following steps:

1. Go to https://business.facebook.com/settings/requests/ and log into your account.
2. If you have multiple business portfolios, you will be presented with all of them. Click the portfolio that contains your WABA.
3. In the Received tab, locate the request and complete the flow.

Note that if your customer does not complete this step within 90 days, acceptance and confirmation will happen automatically.

Transferring Ownership of a WABA

There are two WABA ownership models: OBO and WABA Sharing.

If you are a Solution Partner and want to transfer ownership of an OBO WABA to your customer, you can enable ownership transfer on the WABA and your customer can then claim ownership of it by completing your implementation of Embedded Signup.

Transferring ownership requires no downtime and does not affect your app's ability to send customer messages. It simply converts the WABA from the OBO model to the WABA Sharing model. Your credit line will still be attached to the customer's WABA (although you must share your credit line for compliance reasons), and any existing functionality that your app relies on, such as API access, WhatsApp Manager access, and access to the WABA and its resources, are all unaffected.

Note that transferring ownership is one-way. WABAs cannot be converted from the WABA Sharing model back to the OBO model.

Step 1: Enable WABA Ownership Transfer

Use the POST /<WABA_ID>/set_obo_mobility_intent endpoint to enable ownership transfer on a WABA, so your customer can claim ownership of it using Embedded Signup.

Request Syntax

curl -X POST 'https://graph.facebook.com/v21.0/<WABA_ID>/set_obo_mobility_intent' \
-H 'Authorization: Bearer EAAJB...'

Post Body (Optional)

{
  "solution_id": "<MULTI-PARTNER_SOLUTION_ID>"
}

The post body is optional. If you have configured a multi-partner solution, you can include the solution ID in the post body. If included, when the customer claims ownership of the WABA using Embedded Signup, the customer can grant each partner of the solution the permissions specified in the solution's configuration.

Note that once you call this endpoint with a solution ID in the post body, you cannot call it again using the same WABA ID and different solution ID.

Response

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_OBO_MOBILITY_INTENT_ID>"
}

Upon success, the API will return a WhatsAppBusinessAccountOBOMobilityIntent node ID. Currently, you cannot access this node, so there's no need to store it.

Step 2: Instruct Customer to Claim WABA Ownership

Once enabled, instruct your customer to use Meta Business Suite or your implementation of Embedded Signup to claim ownership of the WABA. Using Meta Business Suite

Using Meta Business Suite

Send the customer the following steps:

1. Go to https://business.facebook.com/settings/requests/ and log into your account.
2. If you have multiple business portfolios, you will be presented with all of them. Click the portfolio that contains your WABA.
3. In the Received tab, locate the request and complete the flow.

Using Embedded Signup

Send the customer a link to your implementation of Embedded Signup and instruct them to complete the flow. As part of the flow, the customer will be asked to confirm migration of their WABA(s) to the WABA Sharing model:

If you used the post body to include the ID of a multi-partner solution, the customer will be asked to individually grant each partner of the solution the permissions specified in the solution configuration:

Checking WABA Ownership

These endpoints can be helpful when attempting to identify WABA ownership:

• Use the GET /<BUSINESS_PORTFOLIO_ID>/owned_whatsapp_business_accounts endpoint to get a list of all WABAs that you own.
• Use the GET /<BUSINESS_PORTFOLIO_ID>/client_whatsapp_business_accounts endpoint to get a list of all customer-owned WABAs that have been shared with you.
• Use the GET <WABA_ID> endpoint and request the ownership_type field to determine the WABA's ownership model. A value of ON_BEHALF_OF indicates you own the WABA, while CLIENT_OWNED indicates that your business customer owns the WABA.