UCal
  • Welcome
  • πŸš€Getting Started
    • Quick Start
      • What is IS-Messenger?
      • Setting Up an Account
      • Connecting Channels
      • Inviting Your Teammates
      • Getting Contacts to Message You
      • Automated Welcome and Away Messages
      • Responding to Messages
      • Glossary of Terms
    • Connecting a Channel
    • Invite your teammates
    • Getting Contacts to Message You
    • Automated Welcome and Away Messages
    • Responding to messages
    • Glossary of Terms
    • Creating a Chatbot
  • βš™οΈWorkspace Modules
    • Dashboard
    • Inbox
      • Inbox Overview
      • Assignment and closing a conversations
      • Custom Inboxes
      • Interacting with Respond AI Prompts
      • Using AI Assist
    • Contacts
      • Contact Details
      • Contacts Overview
      • Merge Suggestions
      • Contact Activity
      • Contact Channels
      • Contact Import
      • Segments
    • Broadcast
      • Broadcast Overview
      • Managing Broadcasts
    • Workflow
      • Triggers
      • Workflow Step
        • Step: Send a Message
        • Step: Ask a Question
        • Step: Assign To
        • Step: Branch
        • Step: Update Contact Tag
        • Step: Update Contact Field
        • Step: Open Conversation
        • Step: Close Conversation
        • Step: Add Comment
        • Step: Jump To
        • Step: Wait
        • Step: Date & Time
        • Step: HTTP Request
        • Step: Trigger Another Workflow
        • Step: Add Google Sheets Row
        • Step: AI Agent
      • Workflow Templates
    • Reports
      • Reports: Conversations
      • Reports: Responses
      • Reports: Resolutions
      • Reports: Messages
      • Reports: Contacts
      • Reports: Assignments
      • Reports: Leaderboard
      • Reports: Users
      • Reports: Broadcasts
  • βš™οΈWorkspace Setting
    • Managing a Workspace
    • General
    • Users
      • Access Levels
    • Teams
    • Channels
      • Chat Menus
    • Contact Fields
    • Growth Widgets
      • Website Chat Widget Quick Start
      • Website Chat Widget Overview
      • Workspace Settings: Growth Widgets
      • Install Website Chat Widget on Squarespace
      • Install Website Chat Widget on Joomla
      • Install Website Chat Widget on Wix
      • Install Website Chat Widget on Shopify
      • Install Website Chat Widget on WordPress
      • How to Track Conversation Source from Multiple Websites
    • Respond AI
    • Integrations
      • Dialogflow
        • Dialogflow: Connecting to Dialogflow
        • Dialogflow: Creating a Chatbot
        • Dialogflow : Managing Intents
        • Dialogflow: Parameters
        • Dialogflow: Events
        • Dialogflow: Response Templates
        • Dialogflow: Custom Payloads
        • Dialogflow: Fulfillment Webhook Request
      • E-Commerce & CRM Integrations
        • E-Commerce Integration: Shopify
        • E-Commerce Integration: BigCommerce
        • E-Commerce Integration: WooCommerce
        • E-Commerce Integration: Magento
        • CRM Integration: HubSpot
        • CRM Integration: Salesforce
        • CRM Integration: Pipedrive
        • CRM Integration: ActiveCampaign
      • Zapier
      • Developer API
      • Webhooks
      • Make (formerly Integromat)
    • Closing Notes
    • Snippets
    • Files
    • Data Export
    • Data Import
  • βš™οΈUser Account
  • Profile
  • User Activity Status
  • Notifications
  • Resetting your Passwords
  • πŸ‘¨β€πŸ‘§β€πŸ‘¦CONTACT AND MESSAGES
    • Dynamic Variables
      • Dynamic Variables Overview
      • How to Use Dynamic Variables
    • Contact Search and Custom Inbox
    • Conversations
  • βš™οΈMESSAGING CHANNELS
    • Channel Overview
    • Facebook Messenger
      • Facebook Messenger Quick Start
      • Facebook Chat Plugin
      • Private Replies
      • Message Tag
    • Instagram
      • Instagram Overview
      • Instagram Quick Start
    • WhatsApp
      • WhatsApp Business API Quick Start
      • Getting Ready for Inbound Conversations
      • Getting Ready for Promotional Messaging
      • WhatsApp Official Business Account (Green Tick)
      • Grow your WhatsApp Audience by Maximizing Entry Points
      • Get WhatsApp API Account for Government Agencies
      • Meta Business Verification
      • WhatsApp Message Templates
      • WhatsApp Pricing
      • WhatsApp Business Platform (API) Channel Configuration
      • WhatsApp Messaging Limits
      • Meta Product Catalog
      • Change Your WhatsApp Business Display Name
      • Phone Number Migration to IS-Messenger WhatsApp Business API
      • Turn-off WhatsApp Number Two-Step Verification
      • WhatsApp Cloud API
        • Migrating from On-Premises API to Cloud API
        • Migrating from Cloud API to On-Premises API
        • Set up the WhatsApp Echo Bot
        • Load Testing on Cloud API
        • Experiments
        • Webhooks Setup
      • 360Dialog WhatsApp
      • Twillio WhatsApp
      • MessageBird WhatsApp
      • Vonage WhatsApp
      • Phone Number Migration to WhatsApp Cloud API
    • Website Chat Widget
      • Install on WordPress
      • Install on Shopify
      • Install on Wix
      • Install on Squarespace
      • Install Website Chat Widget on Joomla
    • LINE
      • LINE Overview
      • LINE Quick Start
    • Telegram
      • Telegram Overview
      • Telegram Quick Start
    • Viber
      • Viber Overview
      • Viber Quick Start
    • SMS Overview
      • Twilio SMS Quick Start
        • Importing Contacts to Twilio SMS
      • MessageBird SMS Quick Start
      • Vonage SMS Quick Start
    • Twitter Overview
      • Twitter Quick Start
    • WeChat
      • WeChat Overview
      • WeChat Quick Start
    • Google Business Message
    • Email
      • Google Workspace Quick Start
      • Other Email
    • Custom Channel
      • Custom Channel Overview
      • Custom Channel Quick Start
  • New Release Update
  • Support Use Cases
    • How to Identify Contacts by Email and Phone NumberI
    • How to Enrich Customer Data from a CRM or other Business Software
    • How to Route Customers to the Right Team Automatically
    • How to Auto-Assign Customers to a Team or Dedicated Agent
    • How to Send Outbound Support Messages
    • Support: Closing Conversations
    • How to Supervise Your Support Agents
    • How to Analyze Reports for Support
    • How to Send CSAT to Customer and Save Data in Google Sheets or CRMs
  • Handling Inbound Conversations
    • Managing Spam
    • Create Automated Welcome and Away Messages
    • Get Contacts’ Consent for Personal Data Collection
    • Create Automated Chat Menus
    • Collect Contacts’ Emails and Phone Numbers
    • Route Contacts by Shifts
    • Route Contacts by Team Functions
    • Route New & Returning Contacts
    • Route VIP Contacts
    • Assignment Strategy: Automatic Contact Distribution & Load Balancing
    • Assignment Strategy: Unassign Agents after Conversations Closed
  • Capture Conversations
    • How to Streamline Meeting Scheduling via CTC Ads
    • How to Automate Product Info Sharing in Conversations Initiated via CTC Ads
    • How to Track Conversation Source from Multiple Websites
    • How to Route Contacts from CTC Ads to Agents
  • Automate Conversations
    • How to Maximize Customer Service Potential with AI Agent
    • How to Automate Contact Information Collection with AI
    • How to Route Contacts to Preferred AI Agent
    • How to Automatically Qualify Contacts Based on Budget Using AI Agent
    • How to Route Contacts by their Preferred Language
    • How to Create Automated Chat Menus
    • Assignment Strategy: How to Automate Contact Distribution & Load Balancing
    • Assignment Strategy: Unassign Agents after Conversations Closed
    • How to Create Automated Welcome and Away Messages
    • How to Block Contacts and Manage Spam
    • How to Route New and Returning Contacts
    • How to Collect Contacts’ Emails and Phone Numbers
    • How to Route New and Returning Contacts
    • How to Route Contacts by Team Functions
    • How to Route Contacts by Shifts
    • How to Get Contacts’ Consent for Personal Data Collection
    • How to Route VIP Contacts
  • How to Promptly Transfer Conversation Between Agents
  • How to Guide Customers from Exploration to Purchase with Engaging Menus
  • How to Optimize Customer Onboarding with Automated & Customized Welcome Messages
  • Converse with Customers
    • How to Get a Complete View of the Customers
    • How to Simplify Customer Escalation with Automation
    • How to Transfer Contacts to the Next Shift Automatically
    • How to Optimize Agents’ Productivity in the Messages Module
    • How to Align AI Conversations with Your Brand Voice
    • How to Draft Customer Replies with AI
    • How to Convert Image to Text Using AI
    • How Automate Calculations Using AI
  • Broadcasts Use Cases
    • How to Sending a Simple Broadcast
    • How to Start a Workflow Based on Broadcast Response
    • How to Import to Broadcast via WhatsApp
    • How to Troubleshoot a Failed Broadcast
  • Sales Use Cases
    • How to Collect Leads' Email and Phone Number
    • How to Enrich Contact Data and Qualify Leads
    • How to Route Leads
    • How to Auto-Assign Leads to Sales Agents
    • How to Send Outbound Sales Messages
    • How to Track Productivity by Closing Conversations
    • How to Supervise Sales Agents
    • How to Analyze Reports for Sales
  • Accessing Help Menu
Powered by GitBook
On this page
  • How It Works
  • Requirements
  • Best Practices
  • API Differences
  • Downtime
  • Throughput
  • Migration Support
  • Step 1: Disable Two-Step Verification
  • Step 2: Generate Phone Number Metadata
  • Step 3: Register the Number
  1. MESSAGING CHANNELS
  2. WhatsApp
  3. WhatsApp Cloud API

Migrating from On-Premises API to Cloud API

This document explains how to migrate business phone numbers from On-Premises API to Cloud API.

PreviousWhatsApp Cloud APINextMigrating from Cloud API to On-Premises API

Last updated 1 year ago

Note that migrating a business phone number from one API to another is not the same as .

To migrate from Cloud API to On-Premises API, see .

How It Works

The migration process involves generating metadata about the business phone number, then using that data to register the number for use with Cloud API. This in turn deregisters the number from On-Premises API, since a number can only be registered for use with one API at a time.

Migration does NOT affect:

  • the business phone number's display name, verification status, or quality rating

  • templates used by the business phone number, or their statuses

  • the owning WABA, its Official Business Account status, or its messaging limit

In order to support migration, however, you must be aware of any and take appropriate action to address them before performing the migration steps described in this document.

Requirements

Meta App

You must have a Meta business app that is able to use Cloud API and Business Management API with onboarded customer data, and that is able to digest Cloud API and Business Management API . The app must also be associated with, or claimed by, your verified Meta Business Account.

If you do not have a Meta business app, or if you have one but have not configured the WhatsApp product on it, complete the steps in our Cloud API guide. Completing these steps will generate all of the assets needed to test Cloud API and Business Management API.

App Review

Your Meta app must undergo and be approved (i.e. have advanced access) for the whatsapp_business_messaging and whatsapp_business_management permissions.

Best Practices

After making sure that your app can handle all API differences, we recommend that you first migrate a low-volume business phone number and verify that all functionality that you intend to offer with Cloud API works correctly. After verifying that everything is working properly, migrate additional numbers.

We also recommend that you perform migration when traffic to your On-Premises API deployment is low.

API Differences

The following On-Premises API features are either unsupported or are treated differently by Cloud API. Make sure your app is able to handle these differences before starting the migration process.

Webhooks

Cloud API and Business Management API webhooks payload structures are different from On-Premises API payload structures. We recommend that you create a new webhook endpoint that can handle Cloud API and Business Management API exclusively.

Refer to the following documents to help you understand payload differences and how to configure webhooks on your app using the App Dashboard:

Request Syntax

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

Once migration to Cloud API is complete, the business phone number's On-Premises API webhooks will no longer be delivered and Cloud API webhooks delivery will begin.

Media

Error Codes

Cloud API and Business Management API error codes are different from On-Premises API error codes. See the following documents:

Property Validation

  • On-Premises API can accept unknown properties in message post body payloads, but Cloud API will reject these requests, so make your message send requests use only supported properties.

  • On-Premises API allows the omission of button indexes when sending messages with only one button, but Cloud API will reject these requests, so make sure your message send requests that include buttons also include indexes and their values.

  • On-Premises API accepts text strings that contain leading or trailing spaces (or only spaces) on action and button object properties when sending interactive messages, but Cloud API will reject these requests.

Push-To-Talk Messages

On-Premises identifies push-to-talk (PTT) messages in webhooks by setting messages.type to voice, but Cloud API identifies PTT messages by setting messages.audio.voice to true.

Stickerpacks

Cloud API does not support stickerpacks.

Downtime

Downtime begins as soon as you perform the final migration step (registering the number for use with Cloud API) and should only last a few seconds. During this time, messages sent to the number from WhatsApp users will be silently dropped.

We highly encourage you to schedule migration during a time when the number experiences low activity, to minimize any downtime impact.

Throughput

Migration Support

If you have questions or need help with migration, submit a Direct Support ticket with:

  • Topic: WABiz: Cloud API

  • Request Type: On-Premises API -> Cloud API Migration Issues

Step 1: Disable Two-Step Verification

If you know the business phone number's PIN, you can skip this step.

Step 2: Generate Phone Number Metadata

Request Syntax

POST /v1/settings/backup
{
  "password": "<PASSWORD>"
}

The <PASSWORD> can be any string. This value will be used to encode the metadata, so keep track of it as you will need it in the next step.

Response

{
  "settings": {
    "data": "<METADATA>"
  },
  "meta": {
    "api_status": "<API_STATUS>",
    "version": "<API_VERSION>"
  }
}

The API will return an encoded string assigned to the data property that describes your business phone number and its settings. Capture this value as you will need it in the next step.

  • <METADATA> β€” This is the encoded string that describes your business phone number and its settings. Capture this value as you will need it in the next step.

  • <API_STATUS> β€” The status of your On-Premises API deployment.

  • <API_VERSION> β€”The On-Premises API version number that you are running.

Example Request

curl 'https://localhost:9090/v1/settings/backup' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "password": "tacocat"
}'

Example Response

{
  "settings": {
    "data": "V0FCS..."
  },
  "meta": {
    "api_status": "stable",
    "version": "2.49.3"
  }
}

Step 3: Register the Number

Request Syntax

POST /<BUSINESS_PHONE_NUMBER_ID>/register

Post Body

{
  "messaging_product": "whatsapp",
  "pin": "<NEW_OR_EXISTING_PIN>",
  "backup": {
    "password": "<PASSWORD>",
    "data": "<METADATA>"
  }
}
  • <NEW_OR_EXISTING_PIN> β€” The existing PIN or the PIN you want to set on the business phone number.

  • <PASSWORD> β€” The password you used to generate your business phone number's metadata in the previous step.

  • <METADATA> β€” The encoded string that describes your business phone number and its settings, generated in the previous step.

Response

{
  "success": <SUCCESS>
}

The API will respond with success set to true if registration is successful, or false if there was an error.

Example Request

curl 'https://graph.facebook.com/v18.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "134568",
  "backup": {
    "password": "tacocat",
    "data": "V0FCS..."
  }
}'

Example Response

{
  "success": true

Configuration:

Cloud API webhook payloads:

Business Management API webhook payloads:

Note that after you migrate a business phone number to Cloud API, you must use the endpoint to subscribe your Meta app to webhooks on the WABA associated with the business number:

Media IDs for any media uploaded to On-Premises API cannot be used when sending messages with Cloud API, so you must either to generate new media IDs, or use media URLs if the media is hosted on a public server. See and .

Note that to ensure message integrity, some media hosting domains that are allowed by On-Premises API are not allowed by Cloud API. If you use a hosting service for your media, we recommend that you test media URLs in free-form messages and template messages prior to migration. If you believe your host is blocked in error, please .

If the On-Premises business phone number has multi-connect running 2 or more shards, it will automatically be upgraded to on Cloud API.

You will need the business phone number's PIN when performing step 3, so if you do not know the PIN, you must first on the business phone number. If you do not own the business phone number, ask the owner to disable it for you.

Use the to generate metadata about your business phone number.

Use the Cloud API endpoint to register the number for use with Cloud API. Include the encoded business phone number metadata value and the password from the previous step.

βš™οΈ
migrating a number from one WhatsApp Business Account (WABA) to another
Migrating from Cloud API to On-Premises API
API differences
webhooks
Get Started
App Review
Webhooks for WhatsApp
Webhooks Notification Payload Reference
Webhooks Setup
WhatsApp Business Account > Subscribed Apps
reupload media using Cloud API
Media Messages
Media-Based Message Templates
contact support
Cloud API Error Codes
Business Management API Error Codes
high throughput
disable two-step verification
Backup and Restore API
WhatsApp Business Phone Number > Register