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

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