Overview

This page describes our Partner API.

The 360dialog Partner API follows REST principles. It uses predictable, resource-oriented URLs, accepts form-encoded request bodies, returns JSON-formatted responses, and relies on standard HTTP methods, authentication mechanisms, and response status codes.

The 360dialog Partner API enables the programmatic management of WhatsApp Business Accounts and phone numbers. It enables Partners to automate workflows and build a seamless onboarding and management experience for their clients.

To get started, you will need:

• Partner ID

• Partner Hub login credentials

Partner ID

The Partner ID is a unique identifier used for most Partner API requests. You can find your Partner ID by logging into the 360dialog Partner Hub in your browser and navigating to the Partner Integration section.

Login Credentials

When a Partner account is created, you will receive an email invitation to activate the account and set a password.

Base URL

The default base URL for the 360dialog Partner API is https://hub.360dialog.io/api/v2

Authentication

The Partner API supports two authentication methods:

• API Key (Recommended)

• Bearer Token

Partner API Key and Bearer Tokens are only intended for API calls to hub.360Dialog.io/* .

For the Messaging API ( https://waba-v2.360dialog.io/* ) the supported authentication method is through the use of D360-API Keys. Adding D360-API-KEY in the header with your Client's unique API Key as a value will grant access to Messaging API. See how to retrieve an API key here.

API Key Authentication (Recommended)

Allows secure access to the Partner API without requiring user credentials. Each request must include a valid API key in the request headers.

How to Obtain an API Key

• Navigate to the API Keys section in the Partner Dashboard

• Generate an API key. Store the key securely, as it grants access to the Partner API. It will only be displayed once

Using the API key

Include the API Key in the request header:

x-api-key: YOUR_API_KEY

Example Request

curl -X GET "https://hub.360Dialog.io/api/v2/partners/<partner-id>" \
  -H "x-api-key: YOUR_API_KEY_HERE"

Best Practices for API Authentication

• API Keys Usage: Use API Keys for service-to-service communication.

• API Keys Rotation: Rotate keys periodically to maintain security.

• Secure Storage: Always store API keys and credentials securely. Avoid exposing them publicly or hardcoding them in client-side code - use environment variables instead.

• Error Handling: Handle authentication errors gracefully. Common errors include:

  • 401 Unauthorized: Invalid or missing authentication credentials.

  • 403 Forbidden: Valid credentials, but insufficient permissions.

Bearer Token Authentication (Deprecated)

Bearer Token authentication is still supported, but it is not recommended for use.

Show instructions

To obtain a Bearer Token, provide your username (email) and password.

Request OAuth token for any Partner API request

POST https://hub.360dialog.io/api/v2/token

Request example

curl --request POST
--url https://hub.360dialog.io/api/v2/token
--header 'Authorization: '
--header 'Content-Type: application/json'
--data '{ "username": "[email protected]", "password": "123StrongPass4Me!" }'

Request Body

Name	Type	Description
username*	string	Example: [email protected]
password*	string	Example: 123StrongPass4Me!

Response:

{  "access_token": "string",   "refresh_token": 
"string",  "token_type": "Bearer",  "expires_in": 86400}

After the token is received, use this access token in the authorization header:

"Authorization": "Bearer <your-access-token>"

Partner Webhook URL

A Webhook URL is required to receive notifications for certain events relating to a Partner Account and connected Client Accounts. You can set a Partner URL in the Partner Hub UI or via API endpoint.

Filtering and sorting the API output

Filtering

Allows results to be narrowed down.

For users running curl in a Bash or Linux environment: Because filtering syntax utilizes special characters like { and }, you must escape these symbols with a backslash (\).

Filtering Examples

Get a specific channel.

GET https://hub.360dialog.io/api/v2/partners/{{partner_id}}/
channels?filters={"id":"{{channel_id}}"}

Get a client by contact email.

GET https://hub.360dialog.io/api/v2/partners/{{partner_id}}/
clients?filters={"contact_info":"[email protected]"}

Filter channels by channel property.

GET  https://hub.360dialog.io/api/v2/partners/{{partner_id}}/
channels?filters={"setup_info.verification_method":"sms"}

Filtering options

- q (this can be used to search in multiple fields at the same time)
- meta_status
- id
- type
- status
- client_id
- version
- is_migrated
- account_mode
- terminated_at
- profile_info.about_text
- profile_info.business_vertical
- profile_info.business_description
- use_case_description
- profile_info.country
- profile_info.street_name
- profile_info.city
- profile_info.contact_email
- profile_info.zip_code
- profile_info.webpage_url
- setup_info.phone_number (you can also use "q" to search in this field)
- setup_info.phone_name (you can also use "q" to search in this field)
- setup_info.was_in_use
- setup_info.ivr
- setup_info.verification_method
- setup_info.default_language
- created_at
- modified_at
- project.id
- project.name
- project.license_model
- project.inbox
- project.api_user_email
- project.status
- project.created_at
- project.modified_at
- client.id
- client.name (you can also use "q" to search in this field)
- client.organisation
- client.status
- client.partner_payload (you can also use "q" to search in this field)
- client.meta_info.business_vertical
- client.meta_info.timezone
- client.meta_info.about
- client.meta_info.business_description
- client.meta_info.use_case
- client.contact_info.webpage_url
- client.contact_info.phone
- client.contact_info.language
- client.contact_info.country
- client.contact_info.street_name
- client.contact_info.city
- client.contact_info.email
- client.contact_info.zip_code
- client.contact_user.phone
- client.contact_user.email
- client.contact_user.name
- client.created_at
- client.modified_at
- integration.id
- integration.app_id
- integration.type
- integration.stack_id
- integration.state
- integration.parameters.default_language
- integration.parameters.verification_method
- integration.parameters.app_name
- integration.parameters.organisation
- integration.parameters.api_user_email
- integration.created_at
- integration.modified_at
- waba_account.id
- waba_account.name
- waba_account.namespace
- waba_account.status
- waba_account.external_id
- waba_account.fb_business_id (you can also use "q" to search in this field)
- waba_account.on_behalf_of_business_info.id
- waba_account.on_behalf_of_business_info.name
- waba_account.on_behalf_of_business_info.status
- waba_account.on_behalf_of_business_info.type
- waba_account.created_at
- waba_account.modified_at
- channel_settings.ctwa_enabled
- channel_settings.settings.tier

Sorting

Allows results to be ordered as needed.

Examples:

• ascending: https://hub.360dialog.io/api/v2/partners/partner-id/clients?sort=id

• descending: https://hub.360dialog.io/api/v2/partners/partner-id/clients?sort=-id

Sorting options

- id
- type
- status
- profile_info.about_text
- profile_info.business_vertical
- profile_info.business_description
- profile_info.use_case_description
- profile_info.country
- profile_info.street_name
- profile_info.city
- profile_info.contact_email
- profile_info.zip_code
- profile_info.webpage_url
- setup_info.phone_number
- setup_info.phone_name
- setup_info.was_in_use
- setup_info.ivr
- setup_info.verification_method
- setup_info.default_language
- created_at
- modified_at
- project.id
- project.name
- project.license_model
- project.inbox
- project.api_user_email
- project.status
- project.created_at
- project.modified_at
- client.id
- client.name
- client.organisation
- client.status
- client.partner_payload
- client.meta_info.business_vertical
- client.meta_info.timezone
- client.meta_info.about
- client.meta_info.business_description
- client.meta_info.use_case
- client.contact_info.webpage_url
- client.contact_info.phone
- client.contact_info.language
- client.contact_info.country
- client.contact_info.street_name
- client.contact_info.city
- client.contact_info.email
- client.contact_info.zip_code
- client.contact_user.phone
- client.contact_user.email
- client.contact_user.name
- client.created_at
- client.modified_at
- integration.id
- integration.app_id
- integration.type
- integration.stack_id
- integration.state
- integration.parameters.default_language
- integration.parameters.verification_method
- integration.parameters.app_name
- integration.parameters.organisation
- integration.parameters.api_user_email
- integration.created_at
- integration.modified_at
- waba_account.id
- waba_account.name
- waba_account.namespace
- waba_account.status
- waba_account.external_id
- waba_account.fb_business_id
- waba_account.on_behalf_of_business_info.id
- waba_account.on_behalf_of_business_info.name
- waba_account.on_behalf_of_business_info.status
- waba_account.on_behalf_of_business_info.type
- waba_account.created_at
- waba_account.modified_at
- channel_settings.ctwa_enabled

Retrieving Conversation and Cost Analytics

This endpoint allows to retrieve metrics about the conversations associated with the WhatsApp Business Account (WABA).

It's possible to get the number of messages sent and delivered as well as conversation and cost information for a given period. This parameter works together with the /balance endpoint in the Partner API. See below how to parse the request.

Query Syntax: GET/info/balance?<FILTERING_PARAMETER>

Example

https://hub.360dialog.io/api/v2/partners/{partner_id}/clients/
{client_id}/info/balance?
start_date=1664582400&end_date=1667260799&granularity=day

Query String Parameters

Placeholder	Description	Example Value
<FILTERING_PARAMATERS>	Required. Metric filtering parameter. Append additional filtering parameters using dots. For possible values, see: Filtering Parameters	start_date=1664582400&end_date=1667260799&granularity=day

When calling the GET request, you can attach the following{filtering-parameters}to retrieve the cost and conversation information for a specific WABA.

Filtering Parameters

Name	Description
start_date type: UNIX Timestamp	Required. The start date in UNIX Timestamp (UTC). Returned data will be equal to or newer than the specified date. Example: 1672531200
end_date type: UNIX Timestamp	Required. The end date in UNIX Timestamp (UTC). Returned data will be equal to or older than the specified date. Example: 1672531200
granularity type: String	Required. The granularity by which you would like to retrieve the analytics. Supported Options: DAY MONTH Defaults with MONTH if no value is provided in the request.
app_id type: array	Available only for Get Client Balance endpoint. An array of app_ids for which you would like to retrieve usage. If not provided, all app ids in the WABA are included.

Usage data is approximate and may differ from what’s shown on invoices due to small variations in data processing.

With granularity parameters, you can filter and break down your results. See the code sample below for examples.

GET info/balance?start_date=1691629200
&end_date=1691758799&granularity=day

A successful response returns the usage object with the data you have requested.

Channel Statuses

The availability_status property indicates the readiness of a channel for manage traffic.

Status	Description
ready	The channel is fully onboarded and configured to handle traffic.
setting_up	The channel is in the final stages of the onboarding or migration process.
error	The channel is in a non-operational state due to a configuration issue or failure that prevents it from being used, and it is not in the process of being set up.