LogoLogo
Become a PartnerStatus Page
  • get started
    • Welcome to 360Dialog
    • Quickstarts
      • Register as a Meta Tech Provider
      • Add a WhatsApp Number
      • Set up Integrated Onboarding
      • Create a Message Template
      • Send a Message
      • (temp title) Getting started as a partner
    • Pricing & Billing
      • Payment Methods for BR: Pix & Boleto
      • Month Closing Invoice (MCI)
    • Get API Access
    • Tech Provider Program
      • Understanding the Meta Tech Provider Program
      • Becoming a Meta Tech Provider: A Step-by-Step Guide
  • MM Lite Beta Program
    • Onboarding
    • Sending Messages
    • Expected Errors & Programming Languages
    • MM Lite Sandbox Testing
      • Sending Messages using MM Lite Sandbox
      • Expected Erros & Programming Languages
  • Partner & Account Management
    • Solutions for Partners
      • Benefits for Partners
      • Partner Hub
      • WABA Management
    • Account Setup & Management
      • Prerequisites and best practices for account creation
      • Account Structure
      • Account Creation
  • Integrations & API Development
    • Webhook Events & Setup
      • Webhook Events (Partner & Messaging API)
      • Webhook Configuration & Management
    • Integration Best Practices
      • Architecture and Security
      • Best Practices for Designing Integrations
        • Design a Stable Webhook Receiving Endpoint
      • Sizing Your Environment Based on Expected Throughput
      • Design a Resilient Message Sending Service
      • Integrated Onboarding
        • Basic Integrated Onboarding
        • Custom Integrated Onboarding
        • Host Your Own Embedded Signup
      • API Key Authentication for the Partner API
  • API Reference
    • Messaging API
    • Messaging Health Status
    • Sandbox (Test API Key)
    • Differences Between Cloud API and On-Premise API for Partners
      • [will be deprecated] Messaging with On-Premise API
    • Partner API
  • WABA Management
    • Managing WABA Accounts
      • Using the Partner Hub to manage Clients and Channels
      • Using the Partner API to manage Clients and Channels
      • Partner Permission to Generate API Key
      • Checking Usage & Statistics
    • Phone Number & Hosting
      • Migrating a Phone Number
        • Migrate number from Meta or alternate BSP to 360Dialog
        • Migrate a phone number to a new WABA
        • Migrate a phone number to a new WABA to change messaging Currency
      • WhatsApp Coexistence
        • Coexistence Onboarding
        • Coexistence Webhooks
      • Hosting type Change (On-premise API to Cloud API)
    • WABA Profile & Compliance
      • Display Name Guidelines
      • WABA Profile Info
      • WABA Policy Enforcement
      • Business Account Verification
    • Partner change (between 360Dialog Partners)
    • WhatsApp Flows
    • Accelerated Onboarding
    • Business Account Verification
  • Messaging
    • Sending & Receiving Messages
      • Conversations
      • Receiving messages
      • Before sending a message
    • Message Types
      • Conversational Components
      • Checklist for Message Broadcasts and Campaigns
      • Text messages
      • Interactive messages
        • Single and Multi Product Messages
        • Location Request Messages
        • Address Messages (India and Singapore only)
      • Contacts & Location Messages
    • Template Messages
      • Template Library
      • Template Elements
      • Sending Template Messages
      • Authentication Templates
        • Zero-Tap Authentication Templates
        • One-Tap Autofill Authentication Templates
        • Copy Code Authentication Templates
      • Catalog Templates
      • Product Card Carousel Templates
      • Single-Product Message Templates
      • Coupon Code Templates
      • Limited-Time Offer Templates
      • Multi-Product Templates
    • Media Messages
      • Upload, retrieve or delete media
    • Messaging Health & Troubleshooting
      • Messaging Limits & Quality Rating
      • Errors While Messaging
      • Messages statuses
  • Commerce & Payments
    • Payments (India Only)
      • Receive WhatsApp Payments via Payments Gateway
      • Receive WhatsApp Payments via Payment Links
      • Order Details Template Message
    • Payments (Singapore Only)
      • Receive WhatsApp Payments via Stripe
    • Products and Catalogs
      • India Businesses: Compliance for Commerce
  • Support & Updates
    • Help & Troubleshooting
      • FAQ
      • Error Code Reference
      • User Support Documentation
        • Tutorials
          • Page How to Troubleshoot Login Issues in the 360dialog Hub
          • How to Report an Issue
          • How to Contact Support
        • How-To Guides
          • Raise a support request
          • Requesting a Status Update for Business Verification
        • Reference
          • Troubleshooting Embedded Signup Issues
          • Commerce Policy Checks for WhatsApp API Access
          • Support Availability & SLAs
          • Incident Issue Prioritization
          • Case Types Table
        • Explanation
          • Why Business Verification Takes Time
          • Why Some Issues Are Not Emergencies
          • Understanding the Support Process
      • Support with Meta
    • Imprint & Data Privacy
    • Product Updates & News
      • How to ensure your Template Messages will be received
      • Integrated Onboarding new look and Campaigns Best Practices
Powered by GitBook
On this page
  • Enabling Cloud hosting in your Partner Hub
  • Suggestions for partners implementing code changes to support integration with Cloud API
  • Account differences
  • Endpoint differences
  • Root URL
  • Webhooks (Incoming messages)
  • Messaging
  • Send a text message
  • Media
  • Send a media message
  • Upload Media
  • Get Media
  • Business Profile
  • Retrieve Business Profile information
  • Update Business Profile information
  • Migrating a phone number from On-premise to Cloud API

Was this helpful?

  1. API Reference

Differences Between Cloud API and On-Premise API for Partners

PreviousSandbox (Test API Key)Next[will be deprecated] Messaging with On-Premise API

Last updated 11 months ago

Was this helpful?

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.

Enabling Cloud hosting in your Partner Hub

To enable the option of Cloud hosting, go to the Integrations Tab in your Partner Account > Default Hosting Platform Type > and click on the button

Before you proceed, you will be asked if you wish to keep the Cloud API . You can choose the designated option. A pop-up will appear afterwards confirming the changes.

Please note that, if you have Cloud hosting enabled in your Partner Hub:

  1. Cloud hosting automatically becomes the default choice for all new numbers.

  2. Any number that is ported to your Partner Hub will be automatically hosted in the Cloud API.

If you still have any concerns or limitations about your integration with Cloud API, please reach out to us and we will work together to adapt to this new reality.

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

  1. Start with adjusting a simple text message, so you can test if the whole networking flow of the request works as expected

  2. As a next step work with /media endpoint and see if uploads and media_id generation work as expected.

  3. Proceed to check if the media_id inserted in the simple media type message works as you expect.

Account differences

Endpoint differences

Root URL

On-premise
CloudAPI

https://waba.360dialog.io

https://waba-v2.360dialog.io

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)

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

{
    "recipient_type": "individual",
    "to": "wa_id",
    "type": "text",
    "text": {
        "body": "Hello, dear customer!"
    }
}

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.

{
    "messaging_product": "whatsapp",
    "contacts": [
        {
            "input": "16505076520",
            "wa_id": "16505076520"
        }
    ],
    "messages": [
        {
            "id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA"
        }
    ]
}

Differences in the description of messages request:

On Premise API
Cloud API

messaging_product field is not used at all in On-Premise Api

messaging_product is required in every message

hsm is still available for On-Premise API though it was deprecated in WABA v2.39

hsm shouldn't be use at all

preview_url is top lvl message field object in On-Premise API

preview_url is subfield of text object instead of top lvl object

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 to 1024 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 WABA v2.41 , before that it has been required.

  • template.datetime In CloudAPI only fallback 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 of message object, in CloudAPI the value is subfield of text 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 that index field is not used in components, and few lines later it is used in the example).

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.

{
                "id":"ID"
            }

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

curl -X POST
'https://waba-v2.360dialo.io/media'
-H 'D360-API-KEY: YOUR_API_KEY'
-F 'file=@/local/path/file.jpg;type=image/jpeg' 
-F '"messaging_product" = "whatsapp"'

Headers

Name
Type
Description

D360-API-KEY

string

360dialog API KEY

{
    "media": [
        {
            "id": "f043afd0-f0ae-4b9c-ab3d-696fb4c8cd68"
        }
    }

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

curl -X GET
'https://waba-v2.360dialog.io/MEDIA_ID'
-H 'D360-API-KEY: YOUR_API_KEY''

Path Parameters

Name
Type
Description

media_id

string

media_id

Headers

Name
Type
Description

D360-API-KEY

string

360dialog API KEY

{
  "messaging_product": "whatsapp",
  "url": "URL",
  "mime_type": "image/jpeg",
  "sha256": "HASH",
  "file_size": "SIZE",
  "id": "ID"
}

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.

Business Profile

The endpoints to get and change the Business Profile information have a few changes.

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.

email

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.

{
  "data": [{
    "messaging_product": "whatsapp",
    "address": "ADDRESS",
    "description": "DESCRIPTION",
    "vertical": "INDUSTRY",
    "email": "EMAIL",
    "websites": [
       "https://WEBSITE-1",
       "https://WEBSITE-2"
     ],
     "profile_picture_url": PROFILE_PICTURE_HANDLE
  }]
}

Differences in the response received:

On Premise API
Cloud API

Essential data nested in settings.business

Essential data nested in data

data object also includes messaging_product

Profile picture is not available here (it is edited through /v1/settings/profile/photo)

Existence of profile_picture_url

Description have a maximum of 256 characters

Description have a maximum of 512 characters

Verticals are:

  • Automotive

  • Beauty

  • Spa and Salon

  • Clothing and Apparel

  • Education

  • Entertainment

  • Event Planning and Service

  • Finance and Banking

  • Food and Grocery

  • Public Service

  • Hotel and Lodging

  • Medical and Health

  • Non-profit

  • Professional Services

  • Shopping and Retail

  • Travel and Transportation

  • Restaurant

  • Other

Verticals are:

  • UNDEFINED

  • OTHER

  • AUTO

  • BEAUTY

  • APPAREL

  • EDU

  • ENTERTAIN

  • EVENT_PLAN

  • FINANCE

  • GROCERY

  • GOVT

  • HOTEL

  • HEALTH

  • NONPROFIT

  • PROF_SERVICES

  • RETAIL

  • TRAVEL

  • RESTAURANT

  • NOT_A_BIZ

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.

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.

email

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

From May 15, 2024, it is not possible to onboard numbers with On-Premise API. This means that you should remove the onpremise parameter from the Integrated Onboarding trigger to register or migrate new numbers.

In case of problems with more complex calls (Interactive messages for example), please check out for a more detailed description of endpoints.

See for error references.

On a Cloud hosted account you will still need to use the D360-Api-Key available per channel/phone number to start messaging.

You can get a channel's Hosting platform type from the request.

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 for clarification.

See our.

You can also use the official Meta docs as a reference, .

Check

In case you receive 308 Permanent Redirect errors using cURL, please use the --location to follow redirects.

.

HANDLE_OF_PROFILE_PICTURE is url obtained from by the .

Learn here how to integrate with Cloud API.
See how to retrieve it here.
Support Team
specific documentation about setting up webhooks to receive outbound and inbound notifications
See On Premise API request.
available here
option
Please refer to this page to migrate a phone number from On-premise to Cloud API.
Parameters for media messages
See differences between On-premise API and Cloud API
Learn how to change hosting type of registered numbers
Enable Cloud API in your Partner Hub to be able to register Cloud API numbers
Reference - WhatsApp Business Platform Cloud API - Documentation - Facebook for Developers
Get Channel's
See On Premise requests.
data storage in the default US setting or set a specific local storage
See here how this works on the On Premise API
Resumable Upload API
Cloud API Error Codes