Links

Messaging API

The Messaging API allows Partners and Clients to send and receive WhatsApp messages.
It is designed to empower businesses with the tools for sending high-scale messages to customers through WhatsApp. Since our API is designed for easy understanding and use, you can also use Meta’s documentation as a reference.

Getting started

For any outgoing actions in the Messaging API, you need to use requests with appropriate endpoints.
  • All Cloud API actions are available via different request types that use a combination of a root base URL + an endpoint suffix. To ensure that you use the correct endpoints for your API calls, we recommend setting https://waba-v2.360dialog.io/ as a base URL and, for each request suffix, you can refer to our documentation 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)
  • The body of the request to the API will determine what exactly you want to send (text, image, etc.).
  • You need to use an API key received from the Client in authorization purposes.
  • A business cannot send a freely composed message first. If business starts a conversation with a user, it should use a template message. Please do not forget about Opt-In requirements.
  • Tip: we can recommend to use Postman as first step instrument to test WABA opportunities.
  • If you have Cloud hosting enabled in your Partner Hub, Cloud hosting automatically becomes the default choice for all clients onboarded through Integrated Onboarding. If you prefer to onboard a number directly on-premise, you should include a "hosting_type" parameter in the client creation request.
To receive any information that is not a response to your request to the API (e.g. incoming messages from users) you need to set a webhook address.
  • It should be unique for every WABA number
  • It should return an HTTPS 200 OK response immediately (before any other processing begins)
Registration Limits: A phone number is limited to 10 registration requests in a 72 hour (3 days) moving window. This restriction applies to actions like WABA Creation, Display Name Change, Migrating numbers from On-premise to Cloud API and registering Test Numbers. If a business exceeds this limit, the phone number will be rate limited and blocked for the next 72 hours before being restored. In case you have any issues, please reach out to our Support team.

Cloud API Local Storage

Local Storage for Cloud API number allows businesses to choose the location where their message data is stored at rest. For regulated industries like finance, government, or healthcare, storing data in a specific country may align with regulatory or company policies.
Refer to our Architecture and Security documentation for details on Cloud API Local Storage.

How to configure Local Storage

With such settings enabled, Cloud API uses a localized storage in the specified country for persisting message content, instead of using its default storage based in the US. Alternatively, by disabling Local Storage, Cloud API reverts to its default storage based in the US.
If you wish to change the local storage of a WABA, you can use the Partner API. Note that you will need to receive a pin code in the phone number to confirm the change.
post
https://hub.360dialog.io/api/v2
/partners/{partner_id}/clients/{client_id}/channels/{channel_id}/control/enable_local_storage
Enable Local Storage
If you need any assistance, please reach out to our Support Team with the specific location, and we will configure this feature for you. Once enabled, you can see the configured local storage from the 360dialog Hub.

Base URL

The default base URL for the Cloud API is https://waba-v2.360dialog.io followed by the path-specific endpoint.

Prerequisites & Basic Setup

1. Retrieve API Key

In order to communicate with the WhatsApp Business API, you need your D360-API-KEY, which is used for authentication. Each registered WhatsApp phone number (channel) has its own D360-API-KEY.
Only the newest API key is valid, so if you generate another API key, the old one will stop working.
You can manage the API Key directly via API. Please note that each channel/phone number has its own API key.
You will need to get the client's permission to generate an API key. See how you can request permission of new and existent clients here.
For each request you will need the Partner API Authorization Token.
post
https://hub.360dialog.io/api/v2
/partners/{partner_id}/channels/{channel_id}/api_keys
Create a new API key for a specific channel.

Get authorization with the API Key

Each endpoint described later in the docs has to be accessed with HTTP Request +SSL and either with API Key based authorization.
When making POST requests, JSON data specified in the docs has to be sent as POST data payload.
Every request to the needs to be authorized using an API Key authentication. Adding D360-API-KEY in the header with your unique API Key as a value will grant access.

Example for POST request with curl

curl \
-H "D360-API-KEY: {{your-api-key}}" \
-X POST \
https://{{base-url}}/v1/messages \
-H "Accept: application/json"
...

Example using Postman

Extra notes

  • Store and manage your D360-API-KEY securely and use it only for server-2-server authentication.
  • Ensure that you always use the corresponding D360-API-KEY when you deal with multiple configurations. A mismatch could lead to inconsistent data.

2. Set WABA Webhook URL

If you only want to test sending messages, you can skip this step and continue with 3. Send a message.
To receive notifications for in and outbound messages, you have to set a webhook URL. This will serve as the destination for all Messaging Notifications associated with the WhatsApp Business Account (WABA) in Cloud API.
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
See Webhook events and Notifications to find information about the payloads.

Send & Receive Messages

3. Send a message

If you got a valid wa_id, you can start sending messages.
Use/messages to send text messages, media, documents, and message templates to your customers.
You can send messages by making a POST call to the /messages regardless of message type. The content of the JSON message body differs for each type of message (text, image, etc.).
post
https://waba-v2.360dialog.io
/messages
Send a text message

Example payload

POST https://waba-v2.360dialog.io/messages
{
"recipient_type": "individual",
"to": "wa_id",
"messaging_product":"whatsapp",
"type": "text",
"text": {
"body": "Hello, dear customer!"
}
}
If this wa_id did not sent a message to your WhatsApp Business Account within the last 24 hours, you can only reach this number with a template message.
Messages - Cloud API - Documentation - Meta for Developers
Meta for Developers
See the official WhatsApp documentation for information regarding the type of messages you want to send.

4. Receive a message

In case you have set a webhook URL as described in step 2. Set Webhook URL, you will have received a Outbound Message Status Notification for your test message by now.
In this Webhook URL, you will receive:
If a webhook event isn't delivered or if the webhook request returns a HTTP status code other than 200, we retry the webhook delivery. We continue retrying delivery with increasing delays up to a certain timeout (typically 24 hours, though this may vary), or until the delivery succeeds.
See Webhook events and Notifications to find information about the payloads.