Skip to main content

  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:

  • Facebook
  • Twitter
  • Instagram
  • MessageBird
  • In-app messaging
  • WhatsApp
  • Twilio
  • WeChat
  • 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

Copy
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'
Request parameters, status, and descriptions
ParameterStatusDescription
grant_typerequiredMust be set to client_credentials
client_idrequiredSparkcentral provided client identifier
client_secretrequiredSparkcentral provided client secret
scoperequiredMust be set to client-read

Response

Copy
{ “token_type”: “bearer”, “access_token”: “a1b2c3d4e5f6”, “expires_in”: 43200 }
Response parameters and descriptions
ParameterDescription
token_typeThe token type to be used in the authorization header. This will always be bearer for client credentials grant.
access_tokenThe 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_inThe 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

URI parameters
  
from

string (required)

An ISO-8601 date time marking the inclusive start of the result. Must be URL encoded. The from filter can be a maximum of 14 days in the past.

to

string (optional)

An ISO-8601 date time marking the exclusive end of the result. Must be URL encoded. If no to filter is provided, the messages that were sent up until now will be included.

mediumId

string (optional)

Filter by medium identifier. If no mediumId filter is provided, the messages sent from all connected mediums will be included. Choices: fb twit instagram messagebird rtm whatsapp twilio wechat mailgun telegram viber

channelId

string (optional)

Filter by channel identifier (to obtain a list of your channel IDs, contact a Sparkcentral representative). If no channelId filter is provided, the messages sent from all connected channels will be included.

groupByInterval

string (optional)

An interval to group results by. If no groupByInterval is provided, the total count for messages matching given filters will be returned. No more than 60 intervals can be requested per request. For example, when selecting minute, the requested time range cannot be longer than 1 hour. Choices: minutehourday

timezone

string (optional)

The timezone name to be used in conjunction with groupByInterval, e.g. America/Los_Angeles. Must be URL encoded. If no timezone is provided, the default ‘UTC’ timezone is used.

Outbound Message Volume

A count of outbound messages based on applied filters.

Example URI:

GET /reporting-metrics/outbound-message-volume

URI parameters

URI parameters
  
from

string (required)

An ISO-8601 date time marking the inclusive start of the result. Must be URL encoded. The from filter can be a maximum of 14 days in the past.

to

string (optional)

An ISO-8601 date time marking the exclusive end of the result. If no to filter is provided, the messages that were sent up until now will be included.

mediumId

string (optional)

Filter by medium identifier. If no mediumId filter is provided, the messages sent to all connected mediums will be included. Choices: fb twit instagram messagebird rtm whatsapp twilio wechat mailgun telegram viber

channelId

string (optional)

Filter by channel identifier (to obtain a list of your channel IDs, contact a Sparkcentral representative). If no channelId filter is provided, the messages sent from all connected channels will be included.

groupByInterval

string (optional)

An interval to group results by. If no groupByInterval is provided, the total count for messages matching given filters will be returned. No more than 60 intervals can be requested per request. For example, when selecting minute, the requested time range cannot be longer than 1 hour. Choices: minutehour day

timezone

string (optional)

The timezone name to be used in conjunction with groupByInterval. Must be URL encoded. If no timezone is provided, the default ‘UTC’ timezone is used.

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

URI parameters
  
from

string (required)

An ISO-8601 date time marking the inclusive start of the result. Must be URL encoded. The from filter can be a maximum of 14 days in the past.

to

string (optional)

An ISO-8601 date time marking the end of the result. Must be URL encoded. Only inbound messages and responses sent before to date time will be included in average first response time calculation. If no to filter is provided, the messages that were sent up until now will be included.

mediumId

string (optional)

Filter by medium identifier. If no mediumId filter is provided, the messages sent in any connected mediums will be included. Choices: fb twit instagram messagebird rtm whatsapp twilio wechat mailgun telegram viber

channelId

string (optional)

Filter by channel identifier (to obtain a list of your channel IDs, contact a Sparkcentral representative). If no channelId filter is provided, the messages sent from all connected channels will be included.

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

URI parameters
  
from

string (optional)

An ISO-8601 date time marking the inclusive start of the result. Must be URL encoded. Only inbound messages and responses sent after from date time will be included in Resolved with Reply calculation. If no from filter is provided, the messages sent since 5 days ago will be included.

to

string (optional)

An ISO-8601 date time marking the exclusive end of the result. Must be URL encoded. Only inbound messages and responses sent before to date time will be included in Resolved with Reply calculation. If no to filter is provided, the messages that were sent up until now will be included.

mediumId

string (optional)

Filter by medium identifier. If no mediumId filter is provided, the messages sent in any connected mediums will be included. Choices: fb twit instagram messagebird rtm whatsapp twilio wechat mailgun telegram viber

channelId

string (optional)

Filter by channel identifier (to obtain a list of your channel IDs, contact a Sparkcentral representative). If no channelId filter is provided, the messages sent from all connected channels will be included.

 

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

URI parameters
  
from

string (required)

An ISO-8601 date time marking the inclusive start of the result. Must be URL encoded. The from filter can be a maximum of 14 days in the past.

to

string (optional)

An ISO-8601 date time marking the exclusive end of the result

mediumId

string (optional)

Filter by medium identifier. If no mediumId filter is provided, the messages sent in any connected mediums will be included. Choices: fb twit instagram messagebird rtm whatsapp twilio wechat mailgun telegram viber

channelId

string (optional)

Filter by channel identifier (to obtain a list of your channel IDs, contact a Sparkcentral representative). If no channelId filter is provided, the messages sent from all connected channels will be included.

Agent Availability

The number of agents available or away.

Example URI:

GET /reporting-metrics/agent-availability

URI parameters

URI parameters
  
userPresenceStatus

string (optional)

Agent status to filter on. It is recommended to always provide userPresenceStatus; the result will always be 0 otherwise. Choices: awayavailable

channelId

string (optional)

Filter by channel identifier (to obtain a list of your channel IDs, contact a Sparkcentral representative). If no channelId filter is provided, the messages sent from all connected channels will be included.

Contacts Waiting in Queue

The number of contacts waiting in the queue for a response.

Example URI:

GET /queue-metrics/contacts-waiting

URI parameters

URI parameters
  
status

string (required)

Queue status to filter on. Choices: newpending

mediumId

string (optional)

Filter by medium identifier. If no mediumId filter is provided, the messages sent in any connected mediums will be included. Choices: fb twit instagram messagebird rtm whatsapp twilio wechat mailgun telegram viber

channelId

string (optional)

Filter by channel identifier (to obtain a list of your channel IDs, contact a Sparkcentral representative). If no channelId filter is provided, the messages sent from all connected channels will be included.

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

URI parameters
  
status

string (required)

Queue status to filter on Choices: newpending

mediumId

string (optional)

Filter by medium identifier Choices: f b twit instagram messagebird rtm whatsapp twilio wechat mailgun telegram viber

channelId

string (optional)

Filter by channel identifier (to obtain a list of your channel IDs, contact a Sparkcentral representative). If no channelId filter is provided, the messages sent from all connected channels will be included.

Examples

1. Show me hourly incoming message volume for all mediums

Example URI:

GET /reporting-metrics/inbound-message-volume

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

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

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

5. Show me total number of contacts currently waiting in the new queue for all channels

Example URI:

GET/queue-metrics/contacts-waiting

 

Can't find what you're looking for? We're here to help