Download OpenAPI specification:Download
get.chat Partner API is an API for 360Dialog Partners building their own solutions on top of the get.chat product.
get.chat Inbox backend architecture provides a single-tenant architecture. For every WhatsApp business phone number deployed on 360Dialog, up to one inbox instance can be deployed, using this API.
That means, every business phone number (360Dialog channel) can have only one inbox deployed, and one inbox cannot have more than one business phone number connected.
See API reference for more information on creating instances, and other available actions.
Since the deployment actions are time-consuming tasks (a single deployment can take up to 5 minutes), Partner integration needs to rely on asynchronous events sent from a Partner API backend.
Asynchronous events are HTTP POST requests that are sent to an endpoint defined by a Partner.
See Asynchronous events reference for more information about all asynchronous events.
There are auth-free endpoints, and there are APIKey-protected endpoints.
The APIKey-protected endpoints are clearly denoted in the API reference.
IMPORTANT: get.chat Partner API Key (APIKey) is different from 360Dialog API Key!
One APIKey authenticates one API user, and is bound to one Partner ID.
Please contact your Account Manager to receive a new API Key.
To authenticate, provide the following headers when making HTTP calls to the API:
IMPORTANT: Do not use your API Key on front end accessible to third parties / end users!
Content-Type: application/json
Authorization: Bearer <YOUR_API_KEY>
For example, use the following key to act as a sandbox user:
Content-Type: application/json
Authorization: Bearer LRoWRCjm1bdwlqDjfdYw
To create new instances, use the Create Instance endpoint.
When there is an inbox instance already deployed for a business phone number, it's not possible to deploy another inbox instance for the same business phone number, using get.chat Partner API. This includes events when an instance was deployed using a 360Dialog API Key, and related Partner decided to invalidate the 360Dialog API Key used, or Partner didn't pay for the subscription, etc.
Such instances persist but cannot be used (360Dialog API Key is not valid).
Possible solutions include:
get.chat Partner API provides a flexible way for defining asynchronous events receivers, or callback receivers.
All asynchronous events (described in Asynchronous events reference) can be considered callbacks to Partner API user requests. It means that the asynchronous events arrive only after a specific Partner API user request or requests.
For example:
"token" event is a callback to the Create Instance call."errors" event is a callback to the Create Instance call.Flexible configuration allows to define a callback URL on every request individually.
For example, "token" and "errors" events will arrive as a callback to the URL specified in the field "configurator.webhook_url" of the Create Instance call. In other words, it's possible to use different callback URLs for each Create Instance call.
To fully integrate with get.chat Partner API, it is important to handle all possible events, to cover all exceptions. Partner's integration needs to handle all events and errors documented either automatically or manually, to assure uninterrupted deployments.
Asynchronous events are HTTP POST requests that are sent to an endpoint defined by a Partner.
"token" event is sent to a Partner-specified endpoint, whenever a new instance is ready for use and configuration.
This event should be expected after making a Create Instance call.
Event object:
"token" (required)stringExample payload of the token event:
{
"token": "YOUR_TOKEN"
}
"errors" event is sent to a Partner-specified endpoint, whenever a new instance creation encountered some problems that require Partner's action or attention.
Event object:
"errors" (required)array of objectobject properties:"code" (required)integer"title" (required)string"details" (required)string"parameters" (optional)objectExample payload of the errors event:
{
"errors": [
{
"code": 701,
"title": "Number already deployed",
"details": "This error is about channel ID 123456.",
"parameters": {
"channel_id": 123456
}
}
]
}
errors property may contain more than one error. Please handle each error either automatically or manually to make sure your deployment works with no interruption.
Partner's integration should assume that the "code" field of the "errors" objects will always tell the type of error.
In other words, receiving the same code twice means an issue of the same nature happened.
This allows the Partner's integration to potentially handle the errors with automated solutions.
It is important to be aware of the "parameters" provided with each error "code".
Partner's integration should assume that the "parameters" of defined error codes are always provided with the names specified below
Partner's integration should assume that the "title" and "details" fields of the "errors" objects are not always the same value, and will differ to the Title column, and the Description column of the table provided below.
"errors" events (error types)| Error code | Title | Description | Parameters |
|---|---|---|---|
| 701 | Number already deployed | 360Dialog API Key provided during instance creation is related to a business phone number that already has an inbox instance deployed. | "channel_id" (string) (required) |
This endpoint is an alias to the same function as / endpoint.
No authorization needed.
{- "status": "healthy"
}Deploys a new instance.
This endpoint will create a new instance containing inbox and integration API. It will allocate new cloud resources and will expose a new API bound to this instance. Note that allocation usually takes about 2-5 minutes until the instance (and API) is ready to use.
You can create a new instance in various ways. Here are the top 3 recommended methods.
Example 2 is the most recommended, and is best suited for automations.
Example 1 is good for a quick start.
If you have no automation set up yet, you can use generate_activation parameter.
When generate_activation is set to true, the admin account activation URL will be pre-generated and returned
in the response to this request.
Pre-generated means the activation URL will be provided to you immediately after processing this request,
but the activation URL is not yet ready to use. You need to await the health_check returned.
For example:
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer LRoWRCjm1bdwlqDjfdYw" \
-X POST \
https://partner-api.getchat.360dialog.io/v1/instances \
--data '{"subdomain": "mycompany-test", "channel_id": "ChAnElCH", "generate_activation": true}'
Above request will create a new instance for channel ChAnElCH, on subdomain mycompany-test, and
a will pre-generate a new activation URL.
The response should look similar to:
{
"id": "167c42d61ed64feb97d3a32508d811a8",
"base_domain": "mycompany-test.inbox.getchat.360dialog.io",
"health_check": "https://mycompany-test.inbox.getchat.360dialog.io/api/v1/status/health",
"channel_id": "sAnDbCH",
"partner_id": "sdBoXPA",
"activation_url": "https://mycompany-test.inbox.getchat.360dialog.io/confirm_account?c=a0a08b0e-f79c-4ec7-bbd4-a1697502bff0"
}
When received, you should await the provided health_check, to get to know when the instance is created,
and ready to use.
When the health check returns 200 status code, you can open the activation_url in web browser, and:
Done! Your password is now ready to use on the inbox admin panel and web frontend!
Additional notes:
Configurator User is an Admin user that should be used for configuring your integration. It is a service account that has several differences with other Admin users:
Configurator user:
Configurator User allows you to create a new instance in a fully automated way.
To do that, provide configurator parameter with all needed sub-params:
user_name (required), webhook_url (required), webhook_headers (optional).
For example:
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer LRoWRCjm1bdwlqDjfdYw" \
-X POST \
https://partner-api.getchat.360dialog.io/v1/instances \
--data '{"subdomain": "mycompany-test", "channel_id": "ChAnElCH", "configurator": {"user_name": "service_account", "webhook_url": "https://example.com/webhook"}}'
Above request will create a new instance for channel ChAnElCH, on subdomain mycompany-test, and
a new Configurator User named service_account.
When instance will be ready to use, a webhook will be sent to https://example.com/webhook URL
with following data:
{"token": "YOUR_TOKEN"}
where YOUR_TOKEN value contains a new Auth Token bound to your new Configurator User of
this specific instance. See
Integration API documentation
for more information about Auth Token.
After receiving the Auth Token, your automation can act as the Configurator User,
by interacting with API endpoints available under https://mycompany-test.inbox.getchat.360dialog.io/api.
For the most convenient approach, you can make use of admin_email.
When provided, an e-mail will be sent to this address as soon as the instance is ready to use. E-mail message contains an activation link. You can activate your inbox admin user (instance admin user) by clicking on activation link.
For example:
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer LRoWRCjm1bdwlqDjfdYw" \
-X POST \
https://partner-api.getchat.360dialog.io/v1/instances \
--data '{"subdomain": "mycompany-test", "channel_id": "ChAnElCH", "admin_email": "example@example.com"}'
Above request will create a new instance for channel ChAnElCH, on subdomain mycompany-test, and
an admin account named "example@example.com".
When instance will be ready to use, an e-mail message will be sent to "example@example.com", with a title:
"WhatsApp Inbox Activation".
In the e-mail message, there will be a sentence with link:
- Click here to activate your inbox and set your password: Activate
Click on the "Activate" link in the e-mail message, and then:
Done! Your password is now ready to use on the inbox admin panel and web frontend!
Additional notes:
We presented a few ways of creating a new instance via Partner API.
Example 1 focuses on providing to you a quick start, but presented workflow is not recommended when managing large volumes of clients.
Example 2 is the most recommended approach, fully utilizing potential of webhooks and your automation.
Example 3 is another convenience feature, that can be potentially useful when creating a new instance on behalf of your client, and when secure isolation of access to messaging is important.
Channel Id (string) or Channel Id (null) (Channel Id) (This parameter is required if 360Dialog channel ID to connect. Our platform will collect a new 360Dialog API Key for this channel ID, ' and will connect a new instance to this channel ID. IMPORTANT: Previous 360Dialog API Key for this channel ID will stop working! | |
D360 Api Key (string) or D360 Api Key (null) (D360 Api Key) (This parameter is required if Existing 360Dialog API Key that you want to use to deploy a new instance | |
Subdomain (string) or Subdomain (null) (Subdomain) Optional sub-domain of a public base domain at which the instance will be available. Leave blank to use auto-generated instance ID. '
For example, Max length is 63, because of RFC 1035: each label in a domain has a limit of 63 characters. If subdomain is already in use, 422 status code is returned from API and following payload:
| |
Admin Email (string) or Admin Email (null) (Admin Email) Optionally provide an e-mail address that will be used as admin user name. When provided, an e-mail will be sent to this address as soon as the instance is ready to use. E-mail message contains an activation link. You can activate your inbox user (instance user) by clicking on activation link, and setting your password. | |
| generate_activation | boolean (Generate Activation) Default: false When set to Pre-generated means the activation URL will be provided to you immediately after processing
this request, but the activation URL is not yet ready to use.
You need to await the When any of those two happens, it means the instance is ready to use, and activation URL can be opened (requested). Note that you don't need to pre-generate the activation URL in following cases:
|
ConfiguratorModel (object) or null (Click "configurator" on the left, for details) Parameters of a new Configurator User that will be created when creating this new instance. Configurator User is an Admin user that should be used for configuring your integration. It is a service account that has several differences with other Admin users. Configurator user:
| |
| max_number_of_seats | integer (Max Number Of Seats) Default: 5 Configures a limit of maximum number of parallel agent seats on this instance. |
{- "channel_id": "sAnDbCH",
- "d360_api_key": "string",
- "subdomain": "sandbox",
- "admin_email": "user@example.com",
- "generate_activation": false,
- "configurator": {
- "user_name": "service_account",
- "webhook_headers": {
- "Authorization": "Webhook 1234567890",
- "Content-Type": "application/json"
}
}, - "max_number_of_seats": 5
}{- "id": "167c42d61ed64feb97d3a32508d811a8",
- "base_domain": "sandbox.inbox.getchat.360dialog.io",
- "channel_id": "sAnDbCH",
- "d360_api_key": "000111aaabbbcccddd222",
- "partner_id": "sdBoXPA",
}