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. These credentials, your email address and password, are used to authenticate in the Partner Hub and to generate a Bearer token for Partner API requests.

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

API Key Authentication (Recommended)

API Key authentication 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)

During the transition period, Bearer Token authentication will still be supported. 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!

200: OK

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

401: Unauthorized Means your login credentials are wrong

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

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

Bearer Tokens and Partner API Key (via X-API-KEY header) are authentication methods specifically designed to use with the Partner API. It cannot be used in combination with the Messaging API.

For the Messaging API, 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.

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

Filters can be applied to Partner API endpoints by specifying parameters in the request URL, allowing results to be narrowed down.

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

Filtering options

- id
- name
- status
- meta_info.business_vertical
- meta_info.timezone
- meta_info.about
- meta_info.business_description
- meta_info.use_case
- contact_info.webpage_url
- contact_info.email
- contact_info.phone
- contact_info.language
- contact_info.country
- contact_info.street_name
- contact_info.city
- contact_info.zip_code
- contact_user.phone
- contact_user.email
- contact_user.name

Sorting

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
- name
- status
- meta_info.business_vertical
- meta_info.timezone
- meta_info.about
- meta_info.business_description
- meta_info.use_case
- contact_info.webpage_url
- contact_info.email
- contact_info.phone
- contact_info.language
- contact_info.country
- contact_info.street_name
- contact_info.city
- contact_info.zip_code
- contact_user.phone
- contact_user.email
- contact_user.name
- created_at
- modified_at

Filtering Examples

Filter channels by channel property.

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

- 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

How to use sort?

Example:

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

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

- 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

Channel Statuses

The hub_status property indicates the channel status.

hub_status	description
draft	Channel exists in the 360dialog Hub but is not synced with Meta
live	Channel is live
pending_deletion	Channel is pending deletion
unregistered	Channel is unregistered from the WhatsApp API
done OBO WABAs Only	Channel exists in the 360dialog Hub but not on Meta
pending OBO WABAs Only	Channel exists in the 360dialog Hub but is not synced with Meta

Granularity Filtering

You can use the granularity parameter to retrieve metrics about the conversations associated with the WhatsApp Business Account (WABA).

Specifically, you can 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 your 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.