Differences between Cloud API and On-Premise API for Partners
As announced in November 2023, Meta is transitioning to a fully Cloud-hosted WhatsApp Business Platform and will stop supporting On-Premise API in October 2025.
Starting from On-Premise client v2.53, all new feature updates will be exclusively delivered to Cloud API. While the On-Premise API client will receive quarterly releases, they will focus solely on bug fixes and security patches. From May 15, 2024, 360dialog will not allow for new numbers to be onboarded with On-Premise API. We will continue supporting already registered On-Premise API throughout 2024, but we strongly recommend to start changing the hosting type of numbers to Cloud as soon as possible. Learn here how to integrate with Cloud API.
Enabling Cloud hosting in your Partner Hub
To enable the option of Cloud hosting in your Partner Hub, please file a ticket with our support team.
Please note that, if you have Cloud hosting enabled in your Partner Hub:
Cloud hosting automatically becomes the default choice for all new numbers.
Any number that is ported to your Partner Hub will be automatically hosted in the Cloud API.
If you prefer to onboard a number with On-premise hosting, you should include a "hosting_type
" parameter in the client creation request. Read more about integrated onboarding parameters here.
Make sure your team is aware of this information and prepared to receive new numbers under Cloud hosting as migration from Cloud to On-premise hosting is not recommended.
Suggestions for partners implementing code changes to support integration with Cloud API
Start with adjusting a simple text message, so you can test if the whole networking flow of the request works as expected
As a next step work with
/media
endpoint and see if uploads and media_id generation work as expected.Proceed to check if the
media_id
inserted in the simple media type message works as you expect.See Cloud API Error Codes for error references.
Account differences
On a Cloud hosted account you will still need to use the D360-Api-Key
available per channel/phone number to start messaging. See how to retrieve it here.
You can get a channel's Hosting platform type from the Get Channel's request.
Endpoint differences
Root URL
On-premise | CloudAPI |
---|---|
|
|
All Cloud API and On-Premise actions are available via different request types that use a combination of a root base URL and an endpoint suffix. Some endpoints (setting webhook and template configurations) vary in the requirement of v1/
in the URL which could cause your request to fail. Please refer to our documentation to ensure you are using the correct endpoint or reach out to our Support Team for clarification.
While referring to Meta's Documentation, you may encounter requests with the path /PHONE_NUMBER_ID
. Please note that 360dialog already transmits this value to Meta, hence, there is no need to include it in your request, as doing so may result in errors. (e.g. waba-v2.360dialog.io/
PHONE_NUMBER_ID/
business_compliance_info
)
Webhooks (Incoming messages)
See our specific documentation about setting up webhooks to receive outbound and inbound notifications.
Webhook URLs or headers for Cloud API does not support "_
"(underscore)
or ":xxxx
"(port)
in (sub)domain names.
Invalid webhook URL: https://your_webhook.example.com
Valid webhook URL: https://yourwebhook.example.com
Invalid webhook URL:https://subdomain.your_webhook.example.com
:3000
Valid webhook URL: https://subdomain.yourwebhook.example.com
Messaging
Both endpoints (On Premise API and Cloud API) accept message
object. The message
object is built from:
commonly accepted:
audio
,contacts
,document
,image
,interactive
,location
,recipient_type
,status
,sticker
,template
,text
,to
,type
,fields
.On-Premise only:
hsm
,preview_url
Cloud API only:
messaging_product
Send a text message
POST
https://waba-v2.360dialog.io/messages
To send a message, use the request URL and the following body parameters.
In the Cloud API the messages
, messaging_product
and contacts
objects are returned.
Request example
Request Body
Name | Type | Description |
---|---|---|
recipient_type | string | individual |
to* | string | wa_id of the contact you want to message |
type | string | text |
text | object | contains body field |
A successful response includes a messages
object with an ID for the newly created message.
Differences in the description of messages
request:
On Premise API | Cloud API |
---|---|
|
|
|
|
|
|
There are some differences in objects that build the message
object. Those differences appear in:
interactive.action.product_retailer_id
object in documentation for On Premise API has listed limitation"Maximum 100 characters for both Single Product and Multi-Product messages."
Which isn’t specified in CloudAPI docs.media.provider
- Used only for On-Premise API, not in CloudAPI (meaning that authentication for media from sources which require authorization must be done differently)media.caption
- On-Premise documentation specifies limitation to1024 characters
while CloudAPI doesn’t specify any limitation in docs.template.namespace
is not used in CloudAPI, for On-Premise API it’s optional since WABAv2.41
, before that it has been required.template.datetime
In CloudAPI onlyfallback
value is used. In On-Premise API also other data can be provided to try compute the localized value.text.preview_url
- In On-Premise API this value is passed as top lvl field ofmessage
object, in CloudAPI the value is subfield oftext
field.components.button
- Documentation on this is convoluted. From checking out the examples it should work the same, but must be verified, because documentation is refuting itself. (for example On-Premise docs say thatindex
field is not used in components, and few lines later it is used in the example).
You can also use the official Meta docs as a reference, available here.
Media
To send a media message:
Send a media message
POST
https://waba-v2.360dialog.io/message
Request Body
Name | Type | Description |
---|---|---|
recipient_type | string | individual |
to* | string | wa_id of the contact you want to message |
type | string | text |
SPECIFIC PARAMETHERS |
Only relevant object (media ID) is returned.
To upload a media file, the differences are:
File type specified in form parameter
Data passed as form parameter
Requires passing
messaging_product=whatsapp
Upload Media
POST
https://waba-v2.360dialog.io/media
Make a POST request to /media to upload your media.
Request example
Headers
Name | Type | Description |
---|---|---|
D360-API-KEY | string | 360dialog API KEY |
To retrieve a media you need to use an endpoint to retrieve the URL and submit get again with the URL received:
Get Media
GET
https://waba-v2.360dialog.io/{media_id}
You can then retrieve the media from the local volume by referencing the media_id
.
Request example
Path Parameters
Name | Type | Description |
---|---|---|
media_id | string |
|
Headers
Name | Type | Description |
---|---|---|
D360-API-KEY | string | 360dialog API KEY |
Path of URL obtained from previous endpoint needs to be called with waba-v2.360dialog.io
host URL:
curl -X GET 'waba-v2.360dialog.io/PATH -H "D360-API-KEY: <api_key>"
So for the response you obtain, delete the root hostname https://lookaside.fbsbx.com
and a attach the rest /whatsapp_business/attachments/?mid=130345565692730173924&ext=1664537344507&hash=ATtBt0Cdio
to our root url https://waba-v2.360dialog.io
Example
GET response was:
{ "messaging_product": "whatsapp", "url": https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=130345565692730173924&ext=1664537344507&hash=ATtBt0Cdio, "mime_type": "image/jpeg", "sha256": "HASH", "file_size": "SIZE", "id": "ID" }
To download media:
curl -X GET 'waba-v2.360dialog.io/whatsapp_business/attachments/?mid=130345565692730173924&ext=1664537344507&hash=ATtBt0Cdio'
-H 'D360-API-KEY: YOUR_API_KEY' > media_file
Please treat the postfix of this message as secret. This link will be valid for 5 mins.
Depending on your cURL version you may receive a BINARY
response instead of the expected JSON
. In this case please add the --compressed
flag to your cURL query.
In case you receive
308 Permanent Redirect
errors using cURL, please use the--location
option to follow redirects.
Business Profile
The endpoints to get and change the Business Profile information have a few changes.
See here how this works on the On Premise API.
Retrieve Business Profile information
GET
https://waba-v2.360dialog.io/whatsapp_business_profile?fields=address,description,email,profile_picture_url,websites,vertical'
Use this edge to retrieve the information available in the Business Profile: business address, business description, email for business contact, business industry, and business website.
Request example
GET /whatsapp_business_profile?fields=address,description,email,profile_picture_url,websites,vertical'
Request Body
Name | Type | Description |
---|---|---|
vertical | string | Industry of the business. Must be one of these accepted values: UNDEFINED / OTHER / AUTO / BEAUTY / APPAREL / EDU / ENTERTAIN / EVENT_PLAN / FINANCE / GROCERY / GOVT / HOTEL / HEALTH / NONPROFIT / PROF_SERVICES / RETAIL / TRAVEL / RESTAURANT / NOT_A_BIZ The business vertical cannot be set back to an empty value after it is created. |
websites | array of strings | URLs (including http:// or https://) associated with the business (e.g., website, Facebook Page, Instagram). Maximum of 2 websites with a maximum of 256 characters each. |
string | Email address (in valid email format) to contact the business. Maximum of 128 characters. | |
description | string | Description of the business. Maximum of 512 characters. |
address | string | Address of the business. Maximum of 256 characters. |
A successful response includes the profile
object containing the business profile data.
Differences in the response received:
On Premise API | Cloud API |
---|---|
Essential data nested in | Essential data nested in
|
Profile picture is not available here (it is edited through | Existence of |
Description have a maximum of 256 characters | Description have a maximum of 512 characters |
Verticals are:
| Verticals are:
|
Update Business Profile information
POST
https://waba-v2.360dialog.io/whatsapp_business_profile
Use the endpoint to configure the following business profile settings: business address, business description, email for business contact, business industry, and business website.
If you only need to update a couple of fields with new information, you can make a request which changes only the necessary fields. You can use the profile_picture_handle
parameter to update the profile photo.
HANDLE_OF_PROFILE_PICTURE
is url obtained from by the Resumable Upload API.
Request example
curl -X POST
'https://waba-v2.360dialog.io/whatsapp_business_profile'
-H 'D360-API-KEY: YOUR_API_KEY'
-d '{ "messaging_product": "whatsapp", "address": "ADDRESS", "description": "DESCRIPTION", "vertical": "INDUSTRY", "email": "EMAIL", "websites": [ "https://WEBSITE-1", "https://WEBSITE-2" ], "profile_picture_handle": "HANDLE_OF_PROFILE_PICTURE" }'
Request Body
Name | Type | Description |
---|---|---|
vertical | string | Industry of the business. Must be one of these accepted values: UNDEFINED / OTHER / AUTO / BEAUTY / APPAREL / EDU / ENTERTAIN / EVENT_PLAN / FINANCE / GROCERY / GOVT / HOTEL / HEALTH / NONPROFIT / PROF_SERVICES / RETAIL / TRAVEL / RESTAURANT / NOT_A_BIZ The business vertical cannot be set back to an empty value after it is created. |
websites | array of strings | URLs (including http:// or https://) associated with the business (e.g., website, Facebook Page, Instagram). Maximum of 2 websites with a maximum of 256 characters each. |
string | Email address (in valid email format) to contact the business. Maximum of 128 characters. | |
description | string | Description of the business. Maximum of 512 characters. |
address | string | Address of the business. Maximum of 256 characters. |
Migrating a phone number from On-premise to Cloud API
Please refer to this page to migrate a phone number from On-premise to Cloud API.
Last updated