Article updated: January 04, 2022
Sparkcentral Real-Time Metrics API
The Real-time Metrics API gives you direct access tor real-time metrics in the Sparkcentral platform via a convenient and secure RESTful API. The API provides Sparkcentral customers a means to integrate with internal contact center dashboards in conjunction with other traditional and/or digital communication channels such as phone, email, live chat, etc.
Real-Time Metrics API uses
If you are building software, you can use the API to engage your customers by:
- Displaying current wait time to customers in a mobile application or website.
If you’re a business, you can use the API to streamline internal business processes by:
- Displaying current backlog and key metrics on digital channels alongside other contact center mediums on real-time dashboards maintained internally.
- Keeping internal stakeholders informed by reporting on hourly trends in volume & backlog statistics across digital channels, to efficiently route agents to another channel if volume spikes.
Supported networks
Sparkcentral is committed to supporting the most messaging networks on the market with the richest set of functionality. Today, you can use Sparkcentral to converse on:
- MessageBird
- In-app messaging
- Twilio
- Mailgun
- Telegram
- Viber
Get started
Access to the Sparkcentral proactive-messaging endpoints requires access keys. Users with admin level access can generate keys in Admin settings by expanding Integration and APIs and selecting Rest API Keys.
Authentication
The Real-Time Metrics API uses the Client Credentials Grant flow of the Oauth 2.0 specification for client authentication and authorization. Clients are provided a client_id and client_secret to authenticate with Sparkcentral’s authorization server and receive an access_token to use for API request authorization. The access_token should be used in an authorization header, but it can optionally be passed as a query string parameter (see request/response details later in this article). When the access_token expires, the API returns a 401 unauthorized. The client can automate this by generating a new access token and replaying the failed request with the fresh access token, as documented in the following section.
Client Credentials Grant
Retrieve an access_token to make authorized API requests. When the access_token expires, use this endpoint to generate a new token.
Request
US Platform:
$ curl -X POST https://public-api.sparkcentral.com/oauth2/token -H 'content-type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID_HERE& client_secret=YOUR_CLIENT_SECRET_HERE&scope=client-read'
EU Platform:
$ curl -X POST https://public-api-eu.sparkcentral.com/oauth2/token -H 'content-type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID_HERE& client_secret=YOUR_CLIENT_SECRET_HERE&scope=client-read'
| Parameter | Status | Description |
|---|---|---|
| grant_type | required | Must be set to client_credentials |
| client_id | required | Sparkcentral provided client identifier |
| client_secret | required | Sparkcentral provided client secret |
| scope | required | Must be set to client-read |
Response
Copy{ “token_type”: “bearer”, “access_token”: “a1b2c3d4e5f6”, “expires_in”: 43200 }
| Parameter | Description |
|---|---|
| token_type | The token type to be used in the authorization header. This will always be bearer for client credentials grant. |
| access_token | The token used to authorize requests. This should be added to requests as an authorization header: Authorization: Bearer a1b2c3d4e5f6. The API will also accept access_tokenas a query string parameter; however, using the authorization header is the preferred method. |
| expires_in | The number of seconds until the token expires (12 hours) |
Data APIs
Inbound Message Volume
A count of inbound messages based on applied filters.
Example URI:
GET /reporting-metrics/inbound-message-volume
URI parameters
| from |
An |
| to |
An |
| mediumId |
Filter by medium identifier. If no |
| channelId |
Filter by channel identifier (to obtain a list of your channel IDs, contact a Sparkcentral representative). If no |
| groupByInterval |
An interval to group results by. If no |
| timezone | string (optional)
The |
Request`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/inbound-message-volume --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T14%3A00%3A00'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/inbound-message-volume --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T14%3A00%3A00'`
Response 200Headers
Content-Type: application/json
Body
{
"dataPoint": {
"value": 2127
}
}
Request`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/inbound-message-volume --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T14%3A00%3A00&timezone=a'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/inbound-message-volume --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T14%3A00%3A00&timezone=a'`
Response 400Headers
Content-Type: application/json
Body
{
"errors": [
"Bad request parameters. java.lang.IllegalArgumentException: The datetime zone id 'a' is not recognized"
],
"errorType": null
}
Request`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/inbound-message-volume --header 'Authorization: Bearer <token>' --data 'from='`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/inbound-message-volume --header 'Authorization: Bearer <token>' --data 'from='`
Response 400Headers
Content-Type: application/json
Body
{
"errors": [
"Bad request parameters. java.lang.IllegalArgumentException: Invalid format: \"\""
],
"errorType": null
}
Request`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/inbound-message-volume --header 'Authorization: Bearer <token>' --data 'groupByInterval=tree'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/inbound-message-volume --header 'Authorization: Bearer <token>' --data 'groupByInterval=tree'`
Response 400Headers
Content-Type: application/json
Body
{
"errors": [
"Bad request parameters. java.lang.IllegalArgumentException: No enum constant com.sparkcentral.models.http.GroupByInterval.TREE"
],
"errorType": null
}
RequestBody
`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/inbound-message-volume --header 'Authorization: Bearer <token>' --data 'mediumId='`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/inbound-message-volume --header 'Authorization: Bearer <token>' --data 'mediumId='`
Response 400Headers
Content-Type: application/json
Body
{
“errors”: [
“Bad request parameters. java.lang.IllegalArgumentException: Not a valid mediumId.”
],
“errorType”: null
}
Outbound Message Volume
A count of outbound messages based on applied filters.
Example URI:
GET /reporting-metrics/outbound-message-volume
URI parameters
| from |
An |
| to |
An |
| mediumId |
Filter by medium identifier. If no |
| channelId |
Filter by channel identifier (to obtain a list of your channel IDs, contact a Sparkcentral representative). If no |
| groupByInterval |
An interval to group results by. If no |
| timezone |
The timezone name to be used in conjunction with |
Request`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/outbound-message-volume --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T14%3A00%3A00'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/outbound-message-volume --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T14%3A00%3A00'`
Response 200Headers
Content-Type: application/json
Body
{
"dataPoint": {
"value": 2127
}
}
Request`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/outbound-message-volume --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T14%3A00%3A00&timezone=a'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/outbound-message-volume --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T14%3A00%3A00&timezone=a'`
Response 400Headers
Content-Type: application/json
Body
{
"errors": [
"Bad request parameters. java.lang.IllegalArgumentException: The datetime zone id 'a' is not recognized"
],
"errorType": null
}
Request`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/outbound-message-volume --header 'Authorization: Bearer a1b2c3d4e5f6' --data 'from='`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/outbound-message-volume --header 'Authorization: Bearer a1b2c3d4e5f6' --data 'from='`
Response 400Headers
Content-Type: application/json
Body
{
"errors": [
"Bad request parameters. java.lang.IllegalArgumentException: Invalid format: \"\""
],
"errorType": null
}
Request
`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/outbound-message-volume --header 'Authorization: Bearer a1b2c3d4e5f6' --data 'groupByInterval=tree'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/outbound-message-volume --header 'Authorization: Bearer a1b2c3d4e5f6' --data 'groupByInterval=tree'`
Response 400Headers
Content-Type: application/json
Body
{
"errors": [
"Bad request parameters. java.lang.IllegalArgumentException: No enum constant com.sparkcentral.models.http.GroupByInterval.TREE"
],
"errorType": null
}
Request`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/outbound-message-volume --header 'Authorization: Bearer a1b2c3d4e5f6' --data 'mediumId='`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/outbound-message-volume --header 'Authorization: Bearer a1b2c3d4e5f6' --data 'mediumId='`
Response 400Headers
Content-Type: application/json
Body
{
“errors”: [
“Bad request parameters. java.lang.IllegalArgumentException: Not a valid mediumId.”
],
“errorType”: null
}
Average First Response Time
The average time in seconds to the first response to an inbound message.
Example URI:
GET /reporting-metrics/first-response-time
URI parameters
| from |
An |
| to |
An |
| mediumId |
Filter by medium identifier. If no |
| channelId |
Filter by channel identifier (to obtain a list of your channel IDs, contact a Sparkcentral representative). If no |
Request
`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/first-response-time --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T14%3A00%3A00'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/first-response-time --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T14%3A00%3A00'`
Response 200Headers
Content-Type: application/json
Body
{
"dataPoint": {
"value": 2127
}
}
Request
`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/first-response-time --header 'Authorization: Bearer <token>' --data 'mediumId='`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/first-response-time --header 'Authorization: Bearer <token>' --data 'mediumId='`
Response 400Headers
Content-Type: application/json
Body
{
“errors”: [
“Bad request parameters. java.lang.IllegalArgumentException: Not a valid mediumId.”
],
“errorType”: null
}
Request
`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/first-response-time --header 'Authorization: Bearer <token>' --data 'from='`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/first-response-time --header 'Authorization: Bearer <token>' --data 'from='`
Response 400Headers
Content-Type: application/json
Body
{
"errors": [
"Bad request parameters. java.lang.IllegalArgumentException: Invalid format: \"\""
],
"errorType": null
}
Resolved With Reply
The number of messages that have been resolved with at least one reply.
Example URI:
GET /reporting-metrics/resolved-with-one-reply
URI parameters
| from |
An |
| to |
An |
| mediumId |
Filter by medium identifier. If no |
| channelId |
Filter by channel identifier (to obtain a list of your channel IDs, contact a Sparkcentral representative). If no |
Request`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/resolved-with-one-reply --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T14%3A00%3A00'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/resolved-with-one-reply --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T14%3A00%3A00'`
Response 200Headers
Content-Type: application/json
Body
{
"dataPoint": {
"value": 2127
}
}
Request
`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/resolved-with-one-reply --header 'Authorization: Bearer <token>' --data 'mediumId='`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/resolved-with-one-reply --header 'Authorization: Bearer <token>' --data 'mediumId='`
Response 400Headers
Content-Type: application/json
Body
{
“errors”: [
“Bad request parameters. java.lang.IllegalArgumentException: Not a valid mediumId.”
],
“errorType”: null
}
Average Handle Time
The average time in seconds that a conversation is handled by an agent, specifically the difference between timestamps of conversation open and conversation pend/resolve. For Average Handle Time to be calculated, there must be an outbound between open and pend/resolve event.
Example URI:
GET /reporting-metrics/handle-time
URI parameters
| from |
An |
| to | string (optional)
An |
| mediumId | string (optional) Filter by medium identifier. If no |
| channelId |
Filter by channel identifier (to obtain a list of your channel IDs, contact a Sparkcentral representative). If no |
Request`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/handle-time --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T14%3A00%3A00'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/handle-time --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T14%3A00%3A00'`
Response 200Headers
Content-Type: application/json
Body
{
"dataPoint": {
"value": 2127
}
}
Request`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/handle-time --header 'Authorization: Bearer <token>' --data 'mediumId='`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/handle-time --header 'Authorization: Bearer <token>' --data 'mediumId='`
Response 400Headers
Content-Type: application/json
Body
{
“errors”: [
“Bad request parameters. java.lang.IllegalArgumentException: Not a valid mediumId.”
],
“errorType”: null
}
Agent Availability
The number of agents available or away.
Example URI:
GET /reporting-metrics/agent-availability
URI parameters
| userPresenceStatus |
Agent status to filter on. It is recommended to always provide |
| channelId |
Filter by channel identifier (to obtain a list of your channel IDs, contact a Sparkcentral representative). If no |
Request`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/agent-availability --header 'Authorization: Bearer <token>' --data 'userPresenceStatus=away'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/agent-availability --header 'Authorization: Bearer <token>' --data 'userPresenceStatus=away'`
Response 200Headers
Content-Type: application/json
Body
{
"dataPoint": {
"value": 2127
}
}
Contacts Waiting in Queue
The number of contacts waiting in the queue for a response.
Example URI:
GET /queue-metrics/contacts-waiting
URI parameters
| status |
Queue status to filter on.
Choices: |
| mediumId |
Filter by medium identifier. If no |
| channelId |
Filter by channel identifier (to obtain a list of your channel IDs, contact a Sparkcentral representative). If no |
Request`$ curl -X GET -G https://public-api.sparkcentral.com/queue-metrics/contacts-waiting --header 'Authorization: Bearer <token>' --data 'status=new'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/queue-metrics/contacts-waiting --header 'Authorization: Bearer <token>' --data 'status=new'`
Response 2001Headers
Content-Type: application/json
Body
{
"dataPoint": {
"value": 2127
}
}
Request`$ curl -X GET -G https://public-api.sparkcentral.com/queue-metrics/contacts-waiting --header 'Authorization: Bearer <token>' --data 'mediumId='`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/queue-metrics/contacts-waiting --header 'Authorization: Bearer <token>' --data 'mediumId='`
Response 200Headers
Content-Type: application/json
Body
{
"dataPoint": {
"value": null
}
}
Request`$ curl -X GET -G https://public-api.sparkcentral.com/queue-metrics/contacts-waiting --header 'Authorization: Bearer <token>' --data 'mediumId=facebook'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/queue-metrics/contacts-waiting --header 'Authorization: Bearer <token>' --data 'mediumId=facebook'`
Response 400Headers
Content-Type: application/json
Body
{
"timestamp": 1505325885724,
"status": 400,
"error": "Bad Request",
"exception": "org.springframework.web.bind.MissingServletRequestParameterException",
"message": "Required String parameter 'status' is not present",
"path": "/contacts-waiting"
}
Longest Wait Time in Queue
The current longest time in seconds that a contact is waiting for a response. If no mediumId filter is provided, the messages sent in any connected mediums will be included.
Example URI:
GET /queue-metrics/longest-wait-time
URI parameters
| status |
Queue status to filter on
Choices: |
| mediumId |
Filter by medium identifier
Choices: |
| channelId |
Filter by channel identifier (to obtain a list of your channel IDs, contact a Sparkcentral representative). If no |
Request`$ curl -X GET -G https://public-api.sparkcentral.com/queue-metrics/longest-wait-time --header 'Authorization: Bearer <token>' --data 'status=new'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/queue-metrics/longest-wait-time --header 'Authorization: Bearer <token>' --data 'status=new'`
Response 200Headers
Content-Type: application/json
Body
{
"dataPoint": {
"value": 2127
}
}
Examples
1. Show me hourly incoming message volume for all mediums
Example URI:
GET /reporting-metrics/inbound-message-volume
RequestBody
`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/inbound-message-volume --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T14%3A00%3A00&groupByInterval=hour'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/inbound-message-volume --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T14%3A00%3A00&groupByInterval=hour'`
2. Show me current average response time for one channel over a rolling 30-minute interval
If current time is : 2017-06-22T14:00:00+01:00; channelId is : ‘efe3ca3a-9872-4ef2-9895-c948cadced29’
Example URI:
GET/reporting-metrics/first-response-time
RequestBody
`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/first-response-time --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T13%3A30%3A00%2B01%3A00&channelId=efe3ca3a-9872-4ef2-9895-c948cadced29'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/first-response-time --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T13%3A30%3A00%2B01%3A00&channelId=efe3ca3a-9872-4ef2-9895-c948cadced29'`
3. Show me total number of contacts resolved with at least one reply for yesterday on Twitter
Example URI:
GET /reporting-metrics/resolved-with-one-reply
RequestBody
`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/resolved-with-one-reply --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T00%3A00%3A00%2B01%3A00&to=2017-06-23T00%3A00%3A00%2B01%3A00&mediumId=twitter'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/resolved-with-one-reply --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T00%3A00%3A00%2B01%3A00&to=2017-06-23T00%3A00%3A00%2B01%3A00&mediumId=twitter'`
4. Show me average handle time for the last hour for one Twitter channel in PST time zone
If current time is : 2017-06-22T14:00:00-07:00; channelId is : ‘efe3ca3a-9872-4ef2-9895-c948cadced29’
Example URI:
GET/reporting-metrics/handle-time
RequestBody
`$ curl -X GET -G https://public-api.sparkcentral.com/reporting-metrics/handle-time --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T13%3A00%3A00-07%3A00&mediumId=twitter&channelId=efe3ca3a-9872-4ef2-9895-c948cadced29'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/reporting-metrics/handle-time --header 'Authorization: Bearer <token>' --data 'from=2017-06-22T13%3A00%3A00-07%3A00&mediumId=twitter&channelId=efe3ca3a-9872-4ef2-9895-c948cadced29'`
5. Show me total number of contacts currently waiting in the new queue for all channels
Example URI:
GET/queue-metrics/contacts-waiting
RequestBody
`$ curl -X GET -G https://public-api.sparkcentral.com/queue-metrics/contacts-waiting --header 'Authorization: Bearer <token>' --data 'status=new'`
or
`$ curl -X GET -G https://public-api-eu.sparkcentral.com/queue-metrics/contacts-waiting --header 'Authorization: Bearer <token>' --data 'status=new'`
Can't find what you're looking for? We're here to help