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 > API keys":

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.

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

We might restrict requests per second quantity in the future.