Conversocial Agent Workspace Customer API

The Conversocial Agent Workspace Customer API is the primary way for clients to access the rich set of data curated by Conversocial.

Authentication

Authentication is performed using HTTP basic authentication. The username field should contain the token name, and the password field should contain the token secret. Tokens can be generated (and their secrets reset) using the Conversocial Agent Workspace web app.

Tokens are associated with a set of "roles" (permission sets) in the same way as users are. Token roles can be customised using the web app. If a token does not possess an appropriate permission to perform an action (including reads) an HTTP 403 response will be returned.

Tokens are subject to usage limits and an HTTP 429 error response will be returned if the limits are exceeded.

Responses are returned as JSON.

Making requests

Responses

The response body is JSON by default. HTTP status codes are used to differentiate successful requests from error conditions.

A successful request will send a HTTP status of 200

{
    "accounts": [{
       "url": "https://api.conversocial.com/v1.3/accounts/14054",
       "id": "14054"
     }],
    "paging": {
           "next_page": null,
           "prev_page": null
    }
}

An unsuccessful request will return a HTTP status code and any error specifics will be returned in the error_code or param properties of the JSON response.

{
    "status": "error",
    "message": "No such author",
    "http_status": "404 Object Not Found"
}

Additional request data

Returning additional information with the fields parameter
On most requests it is possible to filter the returned fields by using the fields query parameter. For example, the query parameter fields=url,first_name,id would exclude all fields returned except for the three specified.

This can be used to include entities information that isn't supplied by default; For example, when searching for a channel you can pull back the channel's name as part of the query. It can also be used to shrink response size by specifying only the required fields for responses which return a list of all fields by default. If an unknown field name is specified then it is skipped without error.

Filter information using the fields parameter
On certain requests it is possible to filter matched entities by a field value. This is done by specifying query arguments. Query arguments can be repeated, in which case entities that match any value are returned - for example, to select channels 6, 9 and 14 the query parameters id=6&id=14&id=9 could be used.

Each resource details its possible fields

Searching

It is possible to search for a range of items between two dates. For instance, requestion the conversations started between the 1st October 2014 and the 14th October 2014 would require oldest_sort_date_gte=2014-10-01&oldest_sort_date_lte=2014-10-14 Inequality searches are used to return a range of data.

Sorting

Responses can be sorted with a sort query parameter. Each endpoint supports a number of fields that can be used for sorting. sort=id will sort entities by the ID field, sort=-date_from will sort items by date_from from youngest to oldest. Sort fields can be stacked, as in sort=-date_from,-date_to will sort reverse by date_from and then by date_to where date_from values are equal.

Entity IDs are strings and are unique only within an entity class - account "2" and channel "2" can both exist and are not the related.

Other operations

Checking if a field is set to a non-null value can be done with _isnull - generated_date_isnull=1 will find reports without a generated_date set, and generated_date_isnull=0 will find reports where a generated_date has been set

Pagination (v1.3+)

Queries can be paginated using the prev_page and next_page object properties returned by a suitable request. The number of items returned can be changed using the URL parameter page_size e.g https://api.conversocial.com/v1.3/conversations?is_priorty=false&page_size=10

Date Formats

All dates and times stated in API responses are given in "Coordinated Universal Time", (UTC). These times can be converted to your local timezone after you receive the response. A time field will be formatted as follows 2013-11-18T11:20:24

Rate Limiting

Rate limiting is performed per token, e.g. the username and password combination will be restricted to a maximum of 30 requests per minute