Web API

Web API is used for complex integrations and allows using Dashly at full power.

Authorization

Each API request should have auth_token. You can generate tokens in "Settings > Developers":

Auth token

Basics

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.

Pagination

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.

Methods

All requests require auth_token. Send id_as_string=true parameter to get carrotquest_uid and conversation_id as string.

Apps

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

Conversations

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

Users

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

Limits

Currently requests are at 60 per minute per api-key maximum.

Errors

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