Differences between CloudAPI and On Premise API for partners

You will still need to use the D360-Api-Key available per channel/phone number to start messaging. See how to retrieve it here.

Suggestions for partners implementing code changes to support integration with CloudAPI

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.

4. In case of problems with more complex calls (Interactive messages for example), please check out Reference - WhatsApp Business Platform Cloud API - Documentation - Facebook for Developers for a more detailed description of endpoints.

Account differences

Cloud API accounts will be in separate Partner Hubs then On-premise accounts.

Each WABA with 360dialog can only contain one Cloud API number. If you need multiple numbers from the same WABA in the Cloud you will need to move them to separate ones.

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

Endpoint differences

Root URL

On-premise	CloudAPI
https://waba.360dialog.io	https://waba-v2.360dialog.io

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

Messaging

See On Premise API request.

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

201

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).

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

Media

See On Premise requests.

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		Check Parameters for media messages

201

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

200

{
    "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

200

{
  "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.

Webhooks (Incoming messages)

In the On Premise API, all messaging events are associated to a particular phone number. In the Cloud API, all messaging events are associated to a particular WhatsApp Business Account.

To set up the Webhook, the only change should be base url (waba-v2.360dialog.io instead waba.360dialog.io). Endpoint is expected to work in the same way, however as we progress with development minor changes might be introduced.

After running /v1/config/webhook the application can be unaccessible for few seconds.

See here how to set up the Webhook URL on the On Premise API.

A typical inbound notification looks like the following:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WHATSAPP-BUSINESS-ACCOUNT-ID",
    "changes": [{
      "value": {
         "messaging_product": "whatsapp",
         "metadata": {
           "display_phone_number": "PHONE-NUMBER",
           "phone_number_id": "PHONE-NUMBER-ID"
         },
      # Additional arrays and objects
         "contacts": [{...}]
         "errors": [{...}]
         "messages": [{...}]
         "statuses": [{...}]
      },
      "field": "messages"
    }]
  }]
}

Components (contacts, errors, messages, statuses) are inside entry.changes.value.

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://[base-path]/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.

200

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://[base-path]/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.

HANDLE_OF_PROFILE_PICTURE is url obtained from GET /media/MEDIA_ID

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.

200

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.