Desk360 API is a Representational State Transfer (REST) structure that provides operations such as:
Reading
Modifying
Adding data
Deleting data
from your help desk.
Desk360 APIs also support Cross-Origin Resource Sharing (CORS).
HTTP Methods
The list of API commands used by Desk360
Command
Description
GET
Fetches object(s)
POST
Creates an object
PUT
Updates/Modifies an object
DELETE
Deletes an object
All API requests must reach the secure endpoint i.e. HTTPS only
Rate Limit
This rate limit applies are based on IP address.
Plan
Rate Limit/Minute
Business
60
Make sure to apply the rate limit-best practices and it stays within the rate limit.
Make sure to make API calls in a safe layer such as your backend, notfront-end or your mobile application.
Remind that even invalid requests are included in the rate limit.
Check your current rate limit status by looking at the following HTTP headers returned in response to each API request:
The number of requests remaining in the current rate limit window.
X-RateLimit-Reset
The reset time in Unix epoch time format.
Retry-After
The number of seconds you should wait in order to trigger your next API request.
This header is returned only when the rate limit is reached.
If your API request is received after the rate limit is reached, Desk360 will return an error in the response. The Retry-After value in the response header will tell you how long to wait before sending another API request.
Who can access my helpdesk? Can anyone see my data?
Before prioritizing a ticket or responding to a customer or using any of the APIs listed above, you must authenticate or log in as you sign in to your helpdesk web portal.
To authenticate the request, you can use your personal. You can obtain your API token with a request with your username and password.
All Desk360 API endpoints (except login) need this token in order to respond to your request.
Obtain your token with a request.
You can directly use v1/login endpoint in order to create/obtain an API token. This API will return an auto-generate a token and returns it.
To make it secure, the maximum wrong login attempt is fixed to 5 per minute.
Correct attempts do not affect the limits.
Login
POSThttps://public-api.desk360.com/v1/login
Use a valid email and password pair to obtain a token.
The following endpoints are supported with attachments:
Please follow the guidelines listed below:
Only files on a local machine can be added using the API. You can not use links!
Content-Type should always be multi-part/form-data for attached requests.
I received an error. How can I solve it?
API requests that cause errors will return an appropriate HTTP status code to help determine the type of error. You can use the following table to understand what each code means:
HTTP Status Code
Status Code Definition
Description
400
Client or Validation Error
The request body/query string is not in the correct format.
For example, the Send a message API requires the to field to be submitted as part of the request, and if it is missing, this status code is returned.
401
Authentication Failure
This indicates that the Authorization field is either missing or incorrect.
404
Requested Resource not Found
The request contains an invalid ID or invalid parameters in the URL.
For example, an API call to retrieve a integration with an invalid ID will return an HTTP 404 status code to inform you that no such integration exists.
405
Method not allowed
This API request has used the wrong HTTP method.
For example, a DELETE requested on /integrations endpoint will return an HTTP 405 as /integrations allows only GET requests.
406
Unsupported Accept Header
Only application/json and */* are supported. When uploading files multipart/form-data are supported.
415
Unsupported Content-type
Only application/json is supported.
429
Rate Limit Exceeded
500
Unexpected Server Error
Sample error response
In addition to the HTTP status code, most errors also return a response with more information to help you troubleshoot the error. An example error response is shown below. The format of the error response is explained after the example.
"error": {"code":"failed_validation","message":"The to field is required.""doc_url": "https://docs.desk360.com/api" }}
Error Response Fields
Field
Description
code
Custom error code that is machine-parseable.
message
Descriptive error message.
doc_url
A link to guide you if there is a solution on the documentation.
Error Codes
Code
Description
authentication_exception
Authentication failed. The token is missing or invalid. Do not forget to put "Bearer" in the beginning of your token. eg: "Bearer YOUR-API-TOKEN"
method_not_allowed_exception
not_found_exception
You may have made a typo in your request URL.
model_not_found_exception
Requested resource not found, the resource maybe deleted or maybe the resource is not yours.
internal_server_error
insecure_request_exception
HTTP is not allowed. Use HTTPS instead.
too_many_requests_exception
invalid_credentials
You typed your email/password wrong.
too_many_attempts
If you entered your email/password wrong more than 5 times, you should wait for a minute.
not_authorized
You do not have permission to modify the resource.
not_found
Requested resource not found, the resource maybe deleted or maybe the resource is not yours.
failed_validation
This is a validation error, please read the message and apply what it says.
API responses that return a list of objects are paginated, for example, View Integration List. Add the parameter page to the query string to navigate through the pages. The page number starts from 1 and each page is fixed to show 20 objects.
If you are on the last page the link header will not be filled.
Whenever it is possible, please queue API calls on your side. This allows you to buffer recent calls to avoid reaching the rate limit. Once you reach the rate limit, retry API calls after the retry period.
Whenever it is feasible, cache the data that does not change much on your side. For example, the mapping between agent name and ID is extremely unlikely to change, so it is a useful approach to cache this data to avoid the rate limit.
Avoid making API calls directly from a mobile app, instead, send the request to your servers and make API calls from there. This ensures that if an API endpoint is changed, you can make and deploy the change on your server instead of updating your application and forcing your customers to the latest version.
Integrations
Apart from its competitors, Desk360 enables its customers to manage multiple integrations under one account.
In order to find your Integration ID, visit Integrations.
Send active WhatsApp message template to a WhatsApp number. If you send with attachments, use form-data. You can also send other body parameters with form-data as well.
Path Parameters
Name
Type
Description
IntegrationId *
Integer
The ID of your integration
Headers
Name
Type
Description
Authorization *
string
Your API Token
Request Body
Name
Type
Description
template_id *
Integer
The template id of the template to be sent.
language_id *
Integer
The language id of the template to be sent.
destinations[] *
array
Required parameters for the template. The key list received in the template list should be used as a key during submission.
destinations.*.phone *
string
WhatsApp number to be sent. It should start with (+) and a country code.
destinations.*.parameters
object
Required parameters for the template. The key list received in the template list should be used as a key during submission.
attachment
file
Attachment for the message template (only allowed in form-data).
Send active WhatsApp message template to multiple WhatsApp number. If you send with attachments, use form-data. You can also send other body parameters with form-data as well.
Path Parameters
Name
Type
Description
IntegrationId *
Integer
The ID of your integration
Headers
Name
Type
Description
Authorization *
string
Your API Token
Request Body
Name
Type
Description
template_id *
Integer
The template id of the template to be sent.
language_id *
Integer
The language id of the template to be sent.
destinations[]
array
Destinations for the template.
destinations.*.phone
string
WhatsApp number to be sent. It should start with (+) and a country code.
parameters
object
Required parameters for the template. The key list received in the template list should be used as a key during submission.
attachment
file
Attachment for the message template (only allowed in form-data).
destinations_file
file
WhatsApp numbers csv file to be sent. It should start with (+) and a country code.