Cloud API WABA Integration

Getting started

The WhatsApp Cloud API allows you to implement WhatsApp Business APIs through Meta's hosting services.

Developer Platformdevelopers.facebook.com

For any outgoing actions (like messages sending), you need to use requests with appropriate endpoints. Please refer to Meta's Official Documentation above for Cloud API.

• All Cloud API actions are available via different request types that use a combination of a root base URL and an endpoint suffix. To ensure that you use the correct endpoints for your API calls, we recommend to set-up 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.

• 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 Cloud API is https://waba-v2.360dialog.i 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.

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.

Get the API key for a specific channel.

GET https://hub.360dialog.io/api/v2/partners/{partner_id}/channels/{channel_id}/api_keys

Path Parameters

Name	Type	Description
channel_id*	string
partner_id*	string

Request Body

Name	Type	Description
api_keys*	array
id*	string
address*	string
api_key*	string

200: OK

{
    // Response
}

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

Name	Type	Description
channel_id*	string
partner_id*	string

Request Body

Name	Type	Description
id*	string
address*	string
api_key*	string
app_id*	string

200: OK

{
    // Response
}

Delete the API key for a specific channel.

DELETE https://hub.360dialog.io/api/v2/partners/{partner_id}/channels/{channel_id}/api_keys

Path Parameters

Name	Type	Description
channel_id*	string
partner_id*	string

200: OK

{
    // Response
}

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

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

2. Set 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, that we use as a destination for all notifications belonging to you WhatsApp phone number.

For Cloud API, use the base-url: https://waba-v2.360dialog.io

▶ Set Webhook URL

Send & Receive Messages

3. Send a message

If you got a valid wa_id, you can start sending messages.

Use the messages node/messagesto 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.).

Send a text message

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

To send a message, use the request URL and the following body parameters.

Request Body

Name	Type	Description
recipient_type	string	individual
to	string	wa_idof the contact you want to message
type	string	text
text	object	contains body field

201: Created

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"
        }
    ]
}

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.

Developer Platformdevelopers.facebook.com

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.

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.

POST /v1/configs/webhook

{
  "url": "{{your-callback-url}}"
}

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

{
  "url": "{{your-callback-url}}",
  "headers": {
    "Authorization": "Basic {{token}}"
  }
}

Developer Platformdevelopers.facebook.com

See the official WhatsApp documentation for information regarding Webhooks

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 allowed

• Certificates (/v1/certificates/*)

• Registration (/v1/account)

• Stats and metrics (/v1/stats/*/metrics)

• Support (/v1/support)

• Users (/v1/users/*)