Migrating a WABA from one Multi-Partner Solution to another via Meta Business Suite

You can use the API and the Meta Business Suite's Business settings panel to migrate a business customer's WABA from one Multi-Partner Solution (the "source solution") to another (the "destination solution").

As part of this process, a new WhatsApp Business Account (WABA) will be created for the business customer, templates within the source WABA will be duplicated in the destination WABA, and access to the WABA and its assets will be granted to the destination solution's Solution Partner.

Note that both you and the destination solution's Solution Partner must perform one or more API requests to complete the process.

Requirements

Your app (or apps, if you are using separate apps) used to create or accept each solution must be associated with the same business portfolio, and the destination solution must be in an active state.

Templates

Billing

Tech Provider steps

Step 1: Tag the customer's WABA for migration

Request

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

Response

Upon success:

{
  "id": "<MIGRATION_INTENT_ID>"
}

Capture the migration intent ID.

Step 2: Send the migration intent ID to your Solution Partner

Send the migration intent ID you just captured to the Solution Partner of your destination solution. They will need this ID to determine if the customer has accepted the migration request.

Step 3: Disable two-step verification on the business phone number

If you have access to the business customer's WABA in WhatsApp Manager, disable two-step verification on the business phone number associated with their WABA.

Alternatively, instruct the business customer to do this on their own. You can provide them with these instructions:

Step 4: Instruct the customer to accept the request

Instruct the customer to use the Meta Business Suite to review and accept the request. You can provide them with these instructions:

When the customer completes this step, an account_update webhook indicating that a customer has been onboarded will be triggered and sent to both you and the destination solution's Solution Partner.

Solution Partner steps

Step 1: Get the customer's business token

Request

curl 'https://graph.facebook.com/<API_VERSION>/<SOLUTION_ID>/access_token?business_id=<CUSTOMER_BUSINESS_PORTFOLIO_ID>' \
-H 'Authorization: Bearer <SYSTEM_TOKEN>'

The customer's business portfolio ID is included in the account_update webhook triggered when the customer accepts the migration intent.

Response

Upon success:

{
  "data": [
    {
      "access_token": "<CUSTOMER_BUSINESS_TOKEN>"
    }
  ]
}

Step 2: Get the status of the migration intent

Use the GET /<SOLUTION_MIGRATION_INTENT_ID> endpoint to get the status of the migration intent that the Tech Provider created. Your Tech Provider should provide you with this ID.

Request

curl 'https://graph.facebook.com/<API_VERSION>/<MIGRATION_INTENT_ID>' \
-H 'Authorization: Bearer <BUSINESS_TOKEN>'

Response

Upon success:

{
  "solution": {
    "name": "<DESTINATION_SOLUTION_NAME>",
    "status": "<DESTINATION_SOLUTION_STATUS>",
    "status_for_pending_request": "<DESTINATION_SOLUTION_PENDING_REQUEST_STATUS>",
    "id": "<DESTINATION_SOLUTION_ID>"
  },
  "status": "<MIGRATION_INTENT_STATUS>",
  "destination_waba": {
    "id": "<BUSINESS_CUSTOMER_WABA_ID>",
    "name": "<BUSINESS_CUSTOMER_WABA_NAME>",
    "currency": "<BUSINESS_CUSTOMER_WABA_CURRENCY>",
    "timezone_id": "<BUSINESS_CUSTOMER_WABA_TIMEZONE>",
    "business_type": "ent",
    "message_template_namespace": "<BUSINESS_CUSTOMER_WABA_TEMPLATE_NAMESPACE>"
  },
  "id": "<MIGRATION_INTENT_ID>"
}

If <MIGRATION_INTENT_STATUS> is ACCEPTED, it means the customer has reviewed and accepted the migration intent and you can proceed to the next step. If it's any other value, do not proceed.

Note that when a customer accepts the migration intent in the Meta Business Suite, an account_update webhook is triggered with status set to PARTNER_ADDED. Although the webhook won't tell if the customer onboarded via the Meta Business Suite, you may wish to perform this query when you get one of these webhooks.

Step 3: Subscribe to webhooks on the customer's WABA

Note that <WABA_ID> should be the customer's destination WABA ID.

Request

curl -X POST 'https://graph.facebook.com/<API_VERSION>/<WABA_ID>/subscribed_apps' \
-H 'Authorization: Bearer <BUSINESS_TOKEN>'

Response

Upon success:

{
  "success": true
}

Step 4: Share your credit line with the customer

Use the POST /<EXTENDED_CREDIT_LINE_ID>/whatsapp_credit_sharing_and_attach endpoint to share your credit line with an onboarded business customer.

Request

curl -X POST 'https://graph.facebook.com/<API_VERSION>/<EXTENDED_CREDIT_LINE_ID>/whatsapp_credit_sharing_and_attach?waba_currency=<CUSTOMER_BUSINESS_CURRENCY>&waba_id=<CUSTOMER_WABA_ID>' \
-H 'Authorization: Bearer <SYSTEM_TOKEN>'

Note that <CUSTOMER_WABA_ID> should be the customer's destination WABA ID.

Response

Upon success:

{
  "allocation_config_id": "<ALLOCATION_CONFIGURATION_ID>",
  "waba_id": "<CUSTOMER_WABA_ID>"
}

Step 5: Get the customer's connected phone number ID

Use the GET /<WABA_ID>/phone_numbers endpoint and request the status field to get a list of business phone numbers on a WABA and their Cloud API registration statuses.

Note that <WABA_ID> should be the customer's source WABA ID.

Request

curl 'https://graph.facebook.com/<API_VERSION>/<WABA_ID>/phone_numbers?fields=status' \
-H 'Authorization: Bearer <BUSINESS_TOKEN>'

Response

Upon success:

{
  "data": [
    {
      "status": "<STATUS>",
      "id": "<BUSINESS_PHONE_NUMBER_ID>"
    }
  ],
  "paging": {
    "cursors": {
      "before": "<PAGING_BEFORE_CURSOR>",
      "after": "<PAGE_AFTER_CURSOR>"
    }
  }
}

A status of CONNECTED indicates that the customer's business phone number is registered and in use with Cloud API.

Step 6: Migrate the customers phone number to their new WABA

Use the POST /<WABA_ID>/phone_numbers endpoint to migrate the customer's business phone number to the destination WABA.

Note that <WABA_ID> should be the customer's destination WABA ID.

Request

curl 'https://graph.facebook.com/<API_VERSION>/<WABA_ID>/phone_numbers' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <BUSINESS_TOKEN>' \
-d '
{
  "migrate_phone_number": true,
  "cc": "<BUSINES_PHONE_NUMBER_COUNTRY_CALLING_CODE>",
  "phone_number": "<BUSINESS_PHONE_NUMBER>",
  "display_phone_number": "<BUSINESS_PHONE_NUMBER_DISPLAY_NUMBER>",
  "verified_name": "<BUSINESS_PHONE_NUMBER_VERIFIED_NAME>"
}'

Response

Upon success:

{
  "id": "<BUSINESS_PHONE_NUMBER_ID>"
}

Step 7: Register the customer's phone number for use with Cloud API

Use the POST /<BUSINESS_PHONE_NUMBER_ID>/register endpoint to register the customer's business phone number for use with Cloud API.

Request

curl 'https://graph.facebook.com/<API_VERSION>/<BUSINESS_PHONE_NUMBER_ID>/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <BUSINESS_TOKEN>' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "<DESIRED_PIN>"
}'

Response

Upon success:

{
  "success": true
}