This document covers the details about Meta’s on-premise API sunset scheduled in October 2025 and the steps required to avoid any service disruption


Context


The WhatsApp On-Premise API was launched in August 2018 as the original hosting option for the WhatsApp Business API, allowing businesses to host and maintain the API on their own infrastructure or through a Business Solution Provider (BSP) like Exotel. It is now considered the legacy model, as WhatsApp's Cloud API, launched in April 2022, is now the preferred and modern solution, gradually replacing the on-premise version, which is scheduled to be shut down in October 2025.


What does it mean for you?


Post the on-premise API sunset in October 2025, if you are on the legacy model, you will no longer be able to send or receive WhatsApp messages, resulting in a complete downtime of services


Please ignore this article if your WhatsApp Phone numbers are already on the Cloud API model. Services for this model remain unaffected.


What are the next steps?


To avoid service disruption due to the Meta sunset, you need to ensure that all your WhatsApp setup is compatible with the Cloud API environment. What this essentially means is that: 

  1. Your system should be compatible with sending messages through Exotel’s WhatsApp Cloud APIs

  2. Your system should be compatible with receiving webhook responses from Exotel’s cloud API system

  3. Your WhatsApp Phone Number should be a Cloud API number


A prerequisite for implementing these changes is to have a Full-active Exotel Account. If you don’t have an Exotel account, kindly create one by following the article below.


Creating an Exotel account

To convert the account into a full active account, please raise a request to our Support Team at hello@exotel.com or get in touch with your Account Manager or Customer Success Manager



Please note that this is a critical pre-requisite for your migration from on-premise to Cloud model, as Exotel WhatsApp APIs require Authentication parameters that are available only if you have an account created with us.

If you already have an Exotel account, kindly ignore this step and move on with the article


Now, let’s dive into what each of the above action items is and how to achieve compatibility.


Sending messages through Exotel’s WhatsApp Cloud API


To ensure that you are compatible with the Cloud API offerings, you need to implement the Exotel WhatsApp Cloud APIs. Please find below the Exotel Developer Documentation and the Support Articles for the same


WhatsApp Cloud APIs

WhatsApp Support Articles


There are key differences in how an On-premise API Message request and WhatsApp Cloud API message request is sent. 

Please find the example of a Freeform Text Message payload from on-premise and from Cloud API: 




On-premise API

Cloud API

URL

{{URL}}/v1/messages

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/messages

Body

{

    "to": "9194137xxxxx",

    "type": "text",

    "recipient_type": "individual",

    "text": {

        "body": "This is some company sending you whatsapp message",

        "preview_url": true

    }

}

{

   "custom_data": "Order12",

   "status_callback": "https://webhook.site",

   "whatsapp": {

      "custom_data": "Order12",

      "status_callback": "https://webhook.site",

      "messages": [

       {

          "custom_data": "Order12",

          "status_callback": "https://webhook.site",

          "from": "+919999XXXXXX",

          "to": "++919999XXXXXX",

          "content": {

             "recipient_type": "individual",

              "type": "text",

              "text": {

              "preview_url": false,

              "body": "MESSAGE_CONTENT"

           }

         }

       }

     ]

   }

}


Please find the example of a freeform Image message payload from on-premise and from Cloud API





On-premise API

Cloud API

URL

{{URL}}/v1/messages

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/messages

Body

{

    "to": "919413745250",

    "type": "image",

    "recipient_type": "individual",

    "image": {

        "link": "https://i.ibb.co/HnJScsX/Uber-Logo-Black-RGB.png",

        "caption": "Uber"

    }

}

{

"custom_data": "ORDER126",

   "status_callback": "https://webhook.site/",

   "whatsapp": {

       "messages": [

           {

               "from": "9199XXXXXXXX",

               "to": "9199XXXXXXXX",

               "content": {

                   "type": "image",

                   "image": {

                       "link": "https://image.587.jpg",

                       "caption": "This is image caption"

                   }

               }

           }

       ]

   }

 }



Please find the example of a Template Text message payload from on-premise and from Cloud API




On-premise API

Cloud API

URL

{{URL}}/v1/messages

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/messages

Body


{

    "to": "919413745250",

    "type": "template",

    "template": {

        "name": "exotel_image_1",

        "language": {

            "policy": "deterministic",

            "code": "en"

        },

        "components": [

            {

                "type": "header",

                "parameters": [

                    {

                        "type": "image",

                        "image": {

                            "link": "https://image.shutterstock.com/image-photo/happy-puppy-dog-smiling-on-260nw-1799966587.jpg"

                        }

                    }

                ]

            },

            {

                "type": "body",

                "parameters": [

                    {

                        "type": "text",

                        "text": "Kashish"

                    }

                ]

            }

        ]

    }

}

{

"custom_data": "order12",

   "status_callback": "https://webhook.site",

   "whatsapp": {

       "messages": [

           {

               "from": "9199XXXXXXXX",

               "to": "9199XXXXXXXX",

               "content": {

                   "type": "template",

                   "template": {

                       "name": "candidate_feedback_message",

                       "language": {

                           "policy": "deterministic",

                           "code": "en"

                       },

                       "components": [

                           {

                               "type": "body",

                               "parameters": [

                                   {

                                       "type": "text",

                                       "text": "Good!"

                                   }

                               ]

                           }

                       ]

                   }

               }

           }

       ]

   }

 }


NOTE: Based on your current usage, please identify the features/payloads you are currently using through On-premise API and change the Endpoint and Payload to comply with Exotel’s Cloud APIs for sending messages



Receiving Webhook Responses from Exotel Cloud API system


Please note that there are differences in how Webhook responses(Delivery responses, incoming message responses, etc) are presented in On-premise APIs and in Cloud APIs


In order to continue receiving the Webhook responses from Exotel, please ensure that the server that hosts your Callback URL is compatible with Exotel Cloud API’s response system. Please find the documentation for the Webhook responses for WhatsApp Messages in Cloud API


Receive Incoming WhatsApp Message

Receive WhatsApp Flows Message


To know about the Delivery related responses, visit the Exotel dashboard. Path: messaging.exotel.com -> Webhooks -> WhatsApp API/WhatsApp Business Account


Please find the example of a Recieved(Incoming) Message Webhook response from on-premise and from Cloud setups: 



On-premise API

Cloud API

{

  "contacts": [{

    "profile": {

      "name": "NAME"

    },

    "wa_id": "WHATSAPP_BUSINESS_ACCOUNT_ID"

  }],

  "messages":[{

    "from": "PHONE_NUMBER",

    "id": "wamid.ID",

    "timestamp": "TIMESTAMP",

    "text": {

      "body": "MESSAGE_BODY"

    },

    "type": "text"

  }]

}

{

   "whatsapp": {

     "messages": [

       {

         "callback_type": "incoming_message",

         "from": "1234",

         "profile_name": "John",

         "to": "5698",

         "timestamp": "1235654654",

         "content": {

           "type": "text",

           "text": {

             "body": "This is a text message from Whatsapp"

           }

         }

       }

     ]

   }

 }



Migrating WhatsApp Phone Number from On-premise to Cloud


Once you have taken care of the WhatsApp payload and webhook changes in the above 2 questions, you need to migrate your WhatsApp number from On-premise to Cloud. 


It is recommended to carry this step towards the end as once migrated, the Phone Number will no longer be compatible to be used with the On-premise message payloads. 


In order to migrate your Phone Number to Cloud, you need to raise a request to our support team with the following information: 


Email: hello@exotel.com | cc: <Your Account Manager>


Email Sub: <Your AccountSid> | Request to migration WhatsApp number from On-premise to Cloud


Body: 

Hi team, 


Kindly help us migrate our WhatsApp number from On-premise to Cloud. Following are the required information


WhatsApp Portfolio ID: 

WhatsApp Business ID (WABA ID): 

WhatsApp Phone number: 

AccountSid: 

Setup URL: 


Thank you


Once a request is raised, our support team will co-ordinate with you for further action and confirmation