Migrating customers off of a Multi-Partner Solution using Meta Business Suite

If you are a Tech Provider, you can migrate a business customer off of a Multi-Partner Solution by tagging their WhatsApp Business Account ("WABA") for migration and instructing them to use Meta Business Suite to review and accept the request. Once migrated, you can provide messaging services to the customer independently.

Migrating a customer off of a solution via Meta Business Suite does not require business phone number reverification, so any downtime due to reverification is eliminated.

Requirements

Your app must already be approved for advanced access for the whatsapp_business_management permission

Templates

Billing

Step 1: 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, you can instruct the business customer to do this on their own. You can provide them with these instructions:

Step 2: 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 '
{
  "app_id": "<YOUR_APP_ID>"
}'

Response

Upon success:

{
  "id": "<MIGRATION_INTENT_ID>"
}

Capture the migration intent ID.

Step 3: Instruct the customer to accept the request and add a payment method

Instruct the customer to use the Meta Business Suite to review and accept the request. Until the business customer adds a payment method, they will be unable to use your app to send template messages to their own customers.

You can provide them with these instructions:

Note that an email from WhatsApp for Business (notification@facebookmail.com) will also be sent to anyone who has admin access on the WABA, requesting review and acceptance of the request. The button in the email just loads the Business settings panel in a new window, so any WABA admin can review and accept the request.

Step 4: Get migration status and WABA ID

Use the GET /<SOLUTION_MIGRATION_INTENT_ID> endpoint to get the status of the migration intent as well as the business customer's new WABA ID.

Request

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

Response

Upon success:

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

Be sure to capture the business customer's destination WABA ID (<BUSINESS_CUSTOMER_WABA_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.

Step 5: Get the customer's business token

Use the POST /<BUSINESS_PORTFOLIO_ID>/system_user_access_tokens endpoint to get the business customer's business token.

Step 6: 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 7: 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, and their Cloud API registration statuses, on the business customer's source WABA.

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 8: 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 their destination WABA.

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

• Set <BUSINES_PHONE_NUMBER_COUNTRY_CALLING_CODE> to the business phone number's country calling code.
• Set <BUSINESS_PHONE_NUMBER> to the business phone number without a plus symbol or country calling code.
• Set <BUSINESS_PHONE_NUMBER_DISPLAY_NUMBER> to the business phone number, with or without a plus symbol and country calling code.
• Set <BUSINESS_PHONE_NUMBER_VERIFIED_NAME> to the business phone number's existing display name.

Response

Upon success, the API returns a business phone number ID. Capture this ID for use in the next step.

{
  "id": "<BUSINESS_PHONE_NUMBER_ID>"
}

Step 9: Register the customer's number

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
}