Developer Docs

# Usage Guide

# Encoding

Data is encoded as defined in JSON in RFC4627 (opens new window). The default encoding for APIs is UTF-8.

# Timezones

In order to keep dates consistent the responses returns dates in UTC formatted by ISO8601 (opens new window). Some endpoints may have support parameter timezone to query data correctly, especially some aggregation requests for statistics. Then your dates must not contains timezone information.

Lets see it in action. Following example will fetch data with timezone Europe/Prague.

{
  "timezone": "Europe/Prague",
  "query": [
    {
      "field": "finishedAt",
      "value": [
        "2020-08-08T00:00:00",
        "2020-08-08T23:59:59"
      ]
    }
  ]
}

In this example parameter timezone will be ignored because dates contains trailing Z.

{
  "timezone": "Europe/Prague",
  "query": [
    {
      "field": "finishedAt",
      "value": [
        "2020-08-08T00:00:00Z",
        "2020-08-08T23:59:59Z"
      ]
    }
  ]
}

# Requests

All API requests must be made over HTTPS. Data is sent and received in JSON format. Where possible, Smartsupp API leverages appropriate HTTP verbs for requests.

Verb Description
GET is used to access resources and perform queries.
POST is used to create resources or any other non-idempotent operation.
PUT is used for idempotent operation as collection replacement etc.
PATCH is used for partial updates or operations doing partial updates.
DELETE is used to delete resources.

# Responses

The API returns HTTP responses on each request to indicate the success or otherwise of API requests. The codes listed below are often used, and the API may use others. Note that 4xx and 5xx responses may be returned for any request and clients should cater for them.

Status Description
400 Bad Request. General client error, possibly malformed data.
401 Unauthorized. The API Key was not authorised (or no API Key was found).
403 Forbidden. The request is not allowed.
404 Not Found. The resource was not found.
422 Unprocessable Entity. The data was well-formed but invalid.
429 Too Many Requests. The client has reached or exceeded a rate limit, or the server is overloaded.
500 Server errors. something went wrong with our servers.

# Pagination

The majority of list resources in the API are paginated to allow clients to traverse data over multiple requests. Their responses are likely to contain a after object to paginate through the dataset.

# Initial request

Initial request must contains property sort as list of sorters. Available sort fields are described for every API with supported pagination.

WARNING

If request does't contains property sort then after is always returned as null and you will be unable to get next page.

{
  "size": 50,
  "sort": [
    { "createdAt": "asc" }
  ]
}

As response you get always total num of objects, items as list of requested resources and after.

{
  "total": 10000,
  "items": [
    ...  
  ],
  "after": [
    1591116224364
  ]
}

# Next page request

To retrieve next page use same size and sort options and add option after returned from Initial request. This workflow apply for other following requests until response property after is null. That means you reached the last page.

{
  "size": 50,
  "sort": [
    { "createdAt": "asc" }
  ],
  "after": [
    1591111537146
  ]
}

# Error Codes

Typical error response may look like:

{
  "code": "not_found",
  "message": "Conversation not found"
}

The API may send the following error codes. Other codes may be added in the future.

Code Description
server_error General server error.
client_error General client error.
invalid_arguments Request arguments was not valid. Response contains prop. `errors`.
not_implemented Requested endpoint does not exists.
agent_not_found Agent does not exists.
token_not_provided No authentication token provided.
token_invalid Provided token is malformed (eg: didnt start with Bearer).
token_not_found Provided token does not exists.

← Webhooks →