Web API is used for complex integrations and allows using Dashly at full power.
Each API request should have auth_token
.
You can generate tokens in "Settings > Developers":
Web API is REST style. All methods are described in the methods section. Basic URL: https://api.dashly.app/v1
. We recommend
using API via HTTPS. You can use HTTP in case HTTPS is unavailable,
but we might restrict API to HTTPS in the future.
Arguments can be sent as GET or POST parameters. UTF-8 encoding is used.
All answers are JSON-objects. Special "envelope" is used:
{
"meta": {
"status": 200
},
"data": {
...
}
}
meta
section contains additional information for developers.
Status field duplicates response HTTP-code. Status 200 means a successful request. Any other status means an error. Example of an error-response:
{
"meta": {
"status": 400,
"error_message": "The request could not be understood by the server due to malformed syntax",
"error": "BadRequest"
},
"data": {}
}
status
contains HTTP-code (400) and additional error
(error name)
and error_message
(error description) fields.
Descriptions of possible errors can be found on the corresponding methods pages.
Some methods return a set of objects (conversations, users, events etc.). A convenient method of getting all data sets in several consequent request is provided with the help of cursor-based pagination.
next_after
field is added into met
section in methods supporting pagination.
Get next data page by repeating request with the same parameters,
adding after
parameter, equal to next_after
from previous request.
In case next_after
is NULL
- there is no next page or all data was received.
next_after
is an integer in some methods, in others - a floating-point number.
Thus we recommend saving cursor as a string.
count
parameter sets maximal number of objects being returned after request
(from 1 to 50). Default: 20.
All requests require auth_token
.
Send id_as_string=true
parameter to get carrotquest_uid and conversation_id as string.
Method | URL | Description |
---|---|---|
GET | /apps/{id}/activeusers | Get active users |
GET | /apps/{id}/users | Get users (leads) |
GET | /apps/{id}/conversations | Get app’s conversations |
GET | /apps/{id}/channels | Get app’s channels |
Method | URL | Description |
---|---|---|
GET | /conversations/{id} | Get a conversation with id |
GET | /conversations/{id}/parts | Get conversation parts |
POST | /conversations/{id}/reply | Reply in a conversation |
POST | /conversations/{id}/markread | Mark conversation read (by a visitor to the site) |
POST | /conversations/{id}/settyping | Someone is typing ... |
POST | /conversations/{id}/assign | Assign admin to the conversation |
POST | /conversations/{id}/tag | Add or delete a tag from the conversation |
POST | /conversations/{id}/close | Close conversation |
Method | URL | Description |
---|---|---|
GET | /users/{id} | Get user’s data |
GET | /users/{id}/events | Get user’s events |
GET | /users/{id}/conversations | Get user’s conversations |
POST | /users/{id}/events | Track an event |
POST | /users/{id}/props | Identify user property |
POST | /users/{id}/setpresence | Send heartbeat signal |
POST | /users/{id}/sendmessage | Send manual message |
POST | /users/{id}/startconversation | Start conversation on behalf of a visitor to the site |
Currently requests are at 60 per minute per api-key maximum.
This table contains basic errors that can be returned by any method.
Methods can generate other errors, depending on method. Check meta
response section.
In case of unforeseen situations (in case of the service's failures) other errors may occur.
Error | Code | Description |
---|---|---|
MethodNotAllowed |
405 | Invalid http method |
Error404 |
404 | API method does not exist |
NotAuthenticated |
401 | Invalid (or missing) auth token |
PermissionDeniedError |
403 | No access to requested data (most likely it belongs to another app) |
TooManyRequests |
429 | Request limit quantity exceeded |
ValidationError |
400 | Invalid (or missing) request arguments. Check meta.error_fields and meta.error_message response fields for details |
BadRequest |
400 | Error in request parameters. Check meta.error_message response field for details |
LookupError |
400 | One of provided ids is not found |
Error500 |
500 | Internal service error |