Prerequisites
  • As a new or existing customer and if you have not used the new WhatsApp Self-service Onboarding process, create a new WhatsApp Business Account (WABA) using the Embedded Signup Flow.
    • Register at least one new phone number as part of this WABA and create a WhatsApp integration in your Genesys Cloud organization. The new phone number can be a test number or integration, which you can delete later, once you migrate the other numbers to this WABA. Without registering at least one new number through the Embedded Signup, you cannot attach the Genesys credit line or payment method to the WABA. Without a valid payment method, WhatsApp cannot migrate phone numbers to a WABA. Hence, you must register at least one new number.
  • Create a Meta App in the Meta Business Manager and add the WhatsApp product to it. You need this app setup to execute a Graph API request with the WhatsApp permissions to start the phone number migration process. You dont use the app for any other purpose other than generating an access or user token, exercising permissions, and starts the migration. You can delete the app later from the Business Manager once you migrate all the numbers. 
  • Start the migration using the Graph API. Genesys cannot perform migration on your behalf because the WABAs created through Embedded Signup are owned by the business and not by Genesys.

To create a Meta app with the WhatsApp product, perform the following steps:

  1. In the Meta Business Settings page, do the following:
    1. Accounts section click Apps.
    2. Click Add and select Create a new app ID.
    3. In the Create an app page, select Other.
    4. In the Select an app type page, select Business.
    5. Click Next.
    6. In the Add an app name field, enter the app name.
    7. (Optional) In the Business Account field, select Genesys Cloud Services, Inc.
    8. Click Create app. The Meta App Dashboard is displayed.
    9. In the Add products to your app page, in the WhatsApp tile, click Set up.
    10. In the Quickstart page, in the on the left side pane, under App Review, click Permissions and Features.
    11. In the Permissions and Features page, in the Search field, type business_management.
    12. In the Permissions and features section, view the WhatsApp_business_management and business_management options with access level as standard access.
  2. Navigate to the Meta tab and click Refresh.
  3. View the Genesys Cloud App that you created in the business settings page.

Once you create the app, configure a test webhook callback URL for your WhatsApp product in the app. To configure the WhatsApp Webhook Callback URL for your Meta app, perform the following steps:

  1. In the unique URL finder, create the unique URL. 
  2. Copy-paste the unique URL in another browser tab and then switch back to your Webhook site URL.
  3. In the Webhook site URL, do the following:
    1. From the top of the page, click Edit.
    2. In the Edit URL dialog box, in the Response body field, type $request.query.hub_challenge$ as the variable.
    3. Click Save.
  4. In the Meta app, do the following:
    1. In the left-side panel, navigate to WhatsApp > Configuration, click Edit.
    2. In the Edit Webhook’s callback URL dialog box, in the Callback URL field, paste the unique URL. 
    3. In the Verify token field, enter the details of the token ( whichcan include any string of text).
    4. Click Verify and save to save your configuration.
  5. Next to the Webhook field, do the following:
    1. Under the Edit field, click Manage.
    2. In the Webhook fields dialog box, in the Subscribe column, select all the boxes under the Subscribe column.
    3. Click Done.

Note: You need the webhook setup only if you are migrating your numbers from another BSP who is on the WhatsApp Cloud platform. If you are migrating numbers from a WhatsApp on-premise platform or an existing Genesys-owned WABA to your new embedded WABA, proceed directly to initiate phone migration.

Stay logged in to your Meta Business Account and navigate to Meta’s Graph API Explorer. On the right side of the API Explorer page, ensure that the authentication parameters are set properly before making any POST requests using the APIs.
To initiate a phone migration, perform the following steps:
  1. In the Access Token dialog box, in the Meta App field, select the Meta App name that you created earlier.
  2. In the User or Page field, select User Token.
  3. In the Add a Permission field, include whatsapp_business_management and business_management permissions in the list of permissions. If not click the dropdown list and select them. You can locate the  whatsapp_business_management option in the Other permissions category and business_management in the Events Groups Pages permissions category.
  4. Click the Generate Access Token button. If system prompts select all WABAs. Usually for a migration you only need to select the WABA that the number is being migrated. The access token expires after a period of idle time. In case of expiry, refresh the page or generate the token again.
  5. Click Submit. 

To confirm if you have initiated the migration, navigate to your WhatsApp Manager and under Account tools > Phone numbers, view your number added to the WABA in Pending or Offline status.

Note: When you initiate the migration, it only adds the number to the new WABA. However, the traffic flows through your existing WhatsApp integration associated with the old WABA until you complete the migration.

Use WhatsApp Embedded Signup Flow in Genesys Cloud and complete your WhatsApp Phone Verification and Registration. If two-factor authentication is not disabled for the number, the phone will be verified, however, you cannot create the embedded WhatsApp integration. Disabling 2FA is a hard requirement. Please reach out to GenesysCloudWhatsAppRequests@genesys.com to get the two-step verification disabled from your number in the old WABA managed by Genesys. If you are migrating the number from another BSP and they are managing your WABA, then you will need to have them disable it for you.

You can activate your phone number if you API request was successful and you were able to initiate the number migration. If the API request returns an error indicating that at least one of your Meta apps must be subscribed to webhooks for the destination WABA, create a new webhook subscription for the destination WABA, by making a POST call to the /WHATSAPP_BUSINESS_ACCOUNT_ID/subscribed_apps endpoint. 

You can verify that the subscription was successful by issuing a GET call to the /WHATSAPP_BUSINESS_ACCOUNT_ID/subscribed_apps endpoint.

Note:To avoid any risk of downtime on your WhatsApp channel, for production numbers, activate the phone number during a planned maintenance window when your contact center is closed for business. Your WhatsApp traffic is not impacted and will not switch over until the old integration is deleted and a new integration is created and activated in GC.

To activate the phone number using embedded signup flow, perform the following steps:

  1. Delete your current WhatsApp integration in Genesys Cloud associated with the phone number from the old WABA. You may need to delete the Message Route associated with the integration first, before deleting the integration itself.
  2. Configure a new WhatsApp integration for the number you initiated as part of the new WABA. For more information on configuring a new WhatsApp integration, see Work with embedded signup flow. 
  3. Once you complete the process, do the following: 
    1. Select your Meta Business Account.
    2. Select the WhatsApp business account where the number was added after initiating the migration.
    3. Select the migrated phone number/business profile.
    4. Verify/register the number and save the integration.

It may take a few minutes for all your approved WhatsApp Message Templates to be automatically migrated from your old WABA to the new WABA. Once done, a new Message Template Namespace is assigned by WhatsApp. To reconfigure canned responses, perform the following steps:

  1. Log in to your Meta Business Manager.
  2. Select your business.
  3. Navigate to WhatsApp Manager > Account tools > Message Templates
  4. Re-configure the message templates/canned responses in your Genesys Cloud Org due to the new Namespace assigned by WhatsApp. For more information on how to add a WhatsApp template message and use a WhatsApp template message, see Add a WhatsApp template message and Use a WhatsApp template message. 

    If you created a new webhook subscription for the Destination WABA and to delete the request, perform the following steps:

    1. In the Graph API Explorer, Access Token section, remove it by making a DELETE call to the /WHATSAPP_BUSINESS_ACCOUNT_ID/subscribed_apps endpoint.
    2. Enter the WhatsApp Business Account ID.
    3. Click Submit.