The Basics (Overview)
This document will help you to get started with the basics such as authorization, sending and receiving messages.
360dialog On-Premise API (old) | 360dialog Cloud API (standard) |
|---|---|
https://waba.360dialog.io | https://waba-v2.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/messageshttps://waba-v2.360dialog.io/messages
Currently, there is only 1 method of authorization available, which is the API Key.
When making POST requests, JSON data specified must be sent as POST data payload.
Each request to the needs to be authorized by 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
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.).
Below is a simple example to send a text message with 360dialog On-Premise hosting:POST {{base-url}}/v1/messages
{
"recipient_type": "individual",
"to": "whatsapp-id",
"type": "text",
"text": {
"body": "your-message-content"
}
}
If the WABA is registered in Cloud API, the request is as follows:
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "text",
"text": {
"body": "Hello, dear customer!"
}
}
Please note that the parameters may vary based on the hosting type. We recommend referring to our documentation for detailed information on each hosting type request example. On each page of our documentation, you will find the instructions for Cloud or On-premise hosting. If you require further clarification, don't hesitate to reach out to our Support Team for assistance.
You must configure a callback (webhook URL) to receive messages.
Webhooks are used for:
- Inbound message notifications: Use it to get a notification you when you have received a message + message content
- 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 will 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.
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
Your webhook must respond with status 200 for all incoming requests. It must also respond to requests in less than 80 milliseconds to prevent errors or delayed 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 (WABA).
Whenever you have a first number in a WABA using Cloud, a WABA-based Webhook needs to be set. When a WABA only has On-premise numbers (with different Webhooks set per phone number), when a first number changes hosting type to Cloud, their webhook will be set as webhook for the whole WABA. Even if other numbers from this WABA are change hosting type to Cloud, the first one will continue. The only way to change the WABA webhook after that is to use this endpoint.
Webhook URLs for Cloud API do 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.comIf 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{
"url": "{{your-callback-url}}",
"headers": {
"Authorization": "Basic {{token}}"
}
}
Now, when a message is sent or received, you will receive a message notification to your webhook URL 😀