[will be deprecated] Messaging with On-Premise API
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.
Getting started
Since 360dialog takes care of deploying all the necessary infrastructure, as Partner you just have to start using API. The API is not tied to a specific programming language and and can be adapted to any purpose.
For any outgoing actions (like messages sending), you need to use requests to an appropriate endpoints.
All these actions are available via different request types that use a combination of 360dialog base URL and an endpoint suffix. E.g. it’s needed to use a
POST
request to the resourcehttps://waba.360dialog.io/v1/messages/
to send a message.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.
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)
Base URL
The default base URL for the 360dialog WhatsApp API is https://waba.360dialog.io
If you want to send a message using the /v1/messages
endpoint, you must append the endpoint to your base URL then make the POST
request. Below is an example of a full POST
request to the resource:
https://waba.360dialog.io/v1/messages
Prerequisites & Basic Setup
1. Retrieve API Key
In order to communicate with the 360dialog WhatsApp API, you need your D360-API-KEY
, which is used for authentication. Each registered WhatsApp phone number (channel) has its own D360-API-KEY
.
You can manage the API Key directly via API. Please note that each channel/phone number has its own API key.
See our documentation about Partner Permissions.
For each request you will need the Partner API Authorization Token.
Create a new API key for a specific channel.
POST
https://hub.360dialog.io/api/v2/partners/{partner_id}/channels/{channel_id}/api_keys
Path Parameters
channel_id*
string
partner_id*
string
Request Body
id*
string
address*
string
api_key*
string
app_id*
string
2. 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
POST
request with curlExample using Postman
Extra notes
In order to look up the phone number assigned to a
D360-API-KEY
, use the /phone_number endpoint.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.
3. Set Webhook URL
If you only want to test sending messages, you can skip this step and continue with 4. Send a message
To receive notifications for in and outbound messages, you have to set a webhook URL, that we use as a destination for all notifications belonging to your WhatsApp phone number.
Send & Receive Messages
4. Send a message
If you got a valid wa_id
, you can start sending messages.
Use the messages node/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
node regardless of message type. The content of the JSON message body differs for each type of message (text, image, etc.).
Example to send a text message
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.
5. 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.
You must configure a callback (webhook URL) to receive messages.
Webhooks can be used for:
Inbound Message Notifications: Use it to get a notification you when you have received a message.
Message Status Notifications: Monitor the status of sent messages.
If a webhook event isn't delivered for any reason (e.g., the client is offline) 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.
Webhook Requirements
To deploy a live webhook that can receive webhook events from the WhatsApp Business API, your code must have the following:
HTTPS support
A valid SSL certificate
Set your callback URL
Send a POST
request to the /v1/configs/webhook
endpoint to set the resource.
Callback URL Header Authentication (Optional)
If the callback URL needs to be authorized by user, USER
and PASS
should be provided in the header Authorization
that contains Basic base64(USER:PASS)
.
Request body example for USER=testuser
and PASS=testpass
Blacklisted Endpoints
For security reasons you will not be able to access any of the below endpoints. If you need to access any of the below resources, please create a support ticket and, depending on the nature of the request, we will provide some options for you.
Settings (
v1/settings/*)
except profile info which is allowedCertificates (
/v1/certificates/*
)Registration (
/v1/account
)Stats and metrics (
/v1/stats/*
|/metrics
)Support (
/v1/support
)Users (
/v1/users/*
)
Check if the WABA is connected
Make a GET
call to this node to retrieve the status of a WhatsApp Business On-premise API client.
On-premise Healthcheck
GET
https://waba.360dialog.io/v1/health
This endpoint returns the status of your WhatsApp Business API client.
Headers
D360-API-KEY
string
your API KEY
Please do not call this endpoint more than once every 5 minutes, as the health status is cached and refreshed only every 5 minutes. If your phone number is disconnected
| uninitialized
or unregistered
- create a ticket with our Support Team and we will assist you to get the number reconnected.
Last updated