Skip to main content
Skip table of contents

API Guide


Data service

Data service is a REST+GraphQL based microservice following the REST and GraphQL API specifications. A 3rd party application can implement these services to return any kind of real-time and historical data to be displayed on Dashboards and Wallboards. We do not expect the data service to implement any sort of authentication on REST and/or GraphQL APIs for now. 

REST APIs

Each data service must support the following endpoints with the following data:

1. Get available attributes
GET /service-name/attribute
Responses

HTTP Code

Description

Schema

200

List of attributes and filters will be returned on success response.

dataContract

Example HTTP request
Request path
/agent-service/attribute
Example HTTP response
Response 200
{
  "attributes" : [{"name": "aht", description: "Average handling time", "group": "voice", "dataType": "FLOAT", historical: true}], 
"filterAttributes" : ["team", "skillGroup"],
"multipleFilters" : true
}
2. Get filter values
GET /service-name/<name-of-filter>
Responses

HTTP Code

Description

Schema

200

List of the values of the given filter

<filterValues> array

Example HTTP request
Request path
/agent-service/team
Example HTTP response
Response 200
[{
"id" : 1 "name" : "team1"
},
{
"id" : 2 "name" : "team2"
}]
3. Get Service Status
GET /service-name/status
Responses

HTTP Code

Description

Schema

200

Service is up and running

string

Example HTTP request
Request path
/agent-service/status
Example HTTP response
Response 200
{"status": "ok"}
Schema

dataContract


Name

Description

Schema

attributes

List of all the attributes that the data service exposes.

Example : [{"name": "currentState", description: "Current state of the Agent", "group": "voice", "dataType": "FLOAT", historical: true}]

<attribute> array

filterAttributes

List of all the filter attributes. The filterValue API will use these names to create the URL path for getting the filter values.

Example : ["team", "skillGroup"]

< string > array

multipleFilters

Should be true if data service supports multiple filter selection.

Example : true

boolean


attribute

Name

Description

Schema

name

Name of the attribute

Example : "aht"

string

description

Description of the attribute

Example : "Some description"

string

group

Optional – Group of the attribute

Example : "voice"

string
dataTypeMust be one of the STRING, INT, FLOAT, BOOL or PERCENT for corresponding data types of the attribute.string
historical

Whether this attribute has historical data available or not.

Example : true

boolean

filterValues

Name

Description

Schema

name

Name of the attribute

Example : "team1"

string

id

Integer ID of the object. This value will be given in the arguments of the queries where filter values are required. See below for details.

Example : "1"

string

GraphQL schema

Every data service will have to expose the following GraphQL queries. Description of the schema is as follows:

Queries

Real-time data

This query will return a list of given attributes and optionally filter the list based on the provided arguments. Following input arguments must be supported:

  • filterAttributes: A list of attributes on which the data will be filtered. This list would contain the names of the attributes 
  • filterValues: An array of arrays corresponding to the filter values. The array at first index will have values of the first filter and so on.

Sample Query:

getRealTimeData (filterAttributes: {val:["team", “skillGroup”]}, 
filterValues: {val: [[1, 2, 3], [4, 5, 6]]})
{
   agentName
   AHT
   answeredEmails
   ...
}

Result:

[{
   agentName: “SomeAgent”
   AHT: “20”,
   answeredEmails: “50”,
   ...
},
{
   agentName: “SomeOtherAgent”
   AHT: “30”,
   answeredEmails: “60”,
   ...
}]
Aggregated real-time data

Each data service should support SUM and AVERAGE data aggregation of any numerical attribute and Row Count of any numerical/non-numerical attributes.

  • SUM: Sum aggregation will give the sum of the given attribute’s values across all the rows.
  • AVERAGE: Average aggregation will give the average of the given attribute’s values across all the rows.
  • COUNT: Count will return the row count of the number of lines which have the same value for the given attribute.

Following input parameters must be supported:

  1. aggregateType: Must be one of the “SUM”, “AVERAGE” or “COUNT”. This aggregation type will be used to aggregate all the selected attribute/s
  2. attributes: List of selected attributes
  3. filterAttributes: A list of attributes on which the data will be filtered. This list would contain the names of the attributes 
  4. filterValues: An array of arrays corresponding to the filter values. The array at first index will have values of the first filter and so on.

Sample Query:

getAggregatedData (aggregateType: "count", 
attributes: {val: ["currentState"]},
filterAttributes: {val:["team", "skillGroup"]},
filterValues: {val: [[1, 2, 3], [4, 5, 6]]})
{
   name
   value
}

Result:

[{
   name: “Ready”,
   value: “20”
},
{
   name: “Not ready”,
   value: “5”
}]


Historical data

This query will give historical stats of the given attribute/s. It should support the following input arguments:

  1. resolution: Will take one of the values from “hourly” and “daily”. Hourly stats will give hour-wise cumulative stats of the selected attribute/s for last 24 hours; daily stats will accumulate all the stats day-wise for last 7 days.
  2. aggregateType: Must be one of the “SUM”, “AVERAGE” or “COUNT”. This aggregation type will be used to aggregate all the selected attribute/s
  3. attributes: List of selected attributes
  4. comparison: This boolean flag would be true for comparison of the same attribute over this and the last week and would be false for comparison of different attributes over the same time period. The time period will depend on the value of resolution. 
  5. filterAttributes: A list of attributes on which the data will be filtered. This list would contain the names of the attributes 
  6. filterValues: An array of arrays corresponding to the filter values. The array at first index will have values of the first filter and so on.
  7. chartType:  Its value is either "Line Chart" or "Bar Chart". if no value is provided (i.e: empty string) then it sends Line Chart by default.


Line Chart Query (Historical)

Sample Query:

getHistoricalData (resolution: "hourly",
aggregateType: "count",
attributes: {val: ["callsAbandoned"]},
comparison: "true",
filterAttributes: {val:["team", "skillGroup"]},
filterValues: {val: [[1, 2, 3], [4, 5, 6]],chartType:"Line Chart"})
{
   name
   series
}

Result:

[
{
name: "Ready"
series: [
      {
        "value": 20,
        "name": "2016-09-17T12:47:17.425Z"
      },
      {
        "value": 30,
        "name": "2016-09-19T17:07:51.824Z"
      },
      {
        "value": 22,
        "name": "2016-09-20T10:30:15.408Z"
      },
      {
        "value": 25,
        "name": "2016-09-13T10:41:32.861Z"
      },
      {
        "value": 28,
        "name": "2016-09-21T18:23:16.441Z"
      }],
},
{
name: "Not Ready"
series: [
      {
        "value": 5,
        "name": "2016-09-17T12:47:17.425Z"
      },
      {
        "value": 10,
        "name": "2016-09-19T17:07:51.824Z"
      },
      {
        "value": 15,
        "name": "2016-09-20T10:30:15.408Z"
      },
      {
        "value": 10,
        "name": "2016-09-13T10:41:32.861Z"
      },
      {
        "value": 8,
        "name": "2016-09-21T18:23:16.441Z"
      }]
}
]


Bar Chart Query (Historical)

Bar Chart also support the same input arguments as of line chart, only its output response is different. The sample query and expected result of bar chart query is as follow:

Sample Query:

getHistoricalData (resolution: "hourly",
aggregateType: "count",
attributes: {val: ["callsAbandoned","callsReceived","callsAnswered"]},
comparison: "true",
filterAttributes: {val:["queue","skillGroup"]},
filterValues: {val: [[1, 2, 3], [4, 5, 6]],chartType:"Bar Chart"})
{
   name
   series
}

Result when comparison is false (i.e comparison of multiple attributes in single week)
Result:
[
{
name: "Mon"
series: [
      {
        "name": "Received",
"value": 490 }, { "name": "Answered",
"value": 490 }, { "name": "Abandoned",
"value": 490 }
]
},
{
    name: "Tue"
series: [
      {
        "name": "Received",
"value": 490 }, { "name": "Answered",
"value": 321 }, { "name": "Abandoned",
"value": 700 }
]
 },
{
    name: "Wed"
series: [
      {
        "name": "Received",
"value": 490 }, { "name": "Answered",
"value": 570 }, { "name": "Abandoned",
"value": 220 }
]
}
]

Result when comparison is true (i.e comparison of same attribute for this and previous week)
Result:

[
{
name: "Mon"
series: [
      {
        "name": "This week",
"value": 490 }, { "name": "Previous Week",
"value": 490 }
]
},
{
    name: "Tue"
series: [
      {
        "name": "This Week",
"value": 490 }, { "name": "Previous Week",
"value": 321 }
]
 }
]
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.