Realtime Queue Statistics API

In Symbee Connect, data about the completion of contact center interactions can be optionally configured to be sent to Amazon Kinesis Streams in your account, which allows you to get a near-real-time historical view of interactions being worked and completed by your contact center agents. See Interaction Event Feeds for further details. However those feeds do not provide a view of work (interactions) currently waiting in-queue, as Interaction Events are only sent to Kinesis upon completion of an Interaction being worked.

This Realtime Queue Statistics API allows you to get a snapshot of the statistics for the Skill Queues configured in your Environment holding the pending interactions still waiting to be worked.

Realtime Queue Stats API Endpoint

Requests to retrieve Queue Statistics are sent as HTTP POST requests, to the following API URL:

https://[global-region.]symbeeconnect.com:9443/symbee-connect-stats-service/svc/rs/RealtimeStatsService/retrieveQueueInfo

Where [global-region.] in the above URL is one of the following, depending on which region your Symbee Connect Environment resides:


API Authentication

All POST requests to the API must have the following additional HTTP Headers present on the requests to succeed:

Details on the 'X-sc-company-api-key' Header value

You will need to obtain your Symbee Connect API Key programmatically from AWS Secrets Manager.

When you sign up for Symbee Connect and decide to use any of the optional features that require running CloudFormations, the very first CloudFormation you run (see here for reference) installs an automatically rotating API Key into the AWS Account associated with the Symbee Connect Environment. This API key establishes a 2-way trust between you and Symbee Connect, and its value is required as a Header on all API requests.

To obtain the API key, use the AWS Secrets Manager API GetSecretValue action, passing in a SecretId of "SYMBEE_CONNECT_API_KEY". Use the value returned in the SecretString property of the response payload as the value to send in the 'X-sc-company-api-key'' header on Queue Statistics API requests.

Note that the SYMBEE_CONNECT_API_KEY value in Secrets Manager is regularly rotated, so it is best to not cache this value for an extended period of time (no longer than an hour).

API Request Payload

The Request POST payload is expected to be a valid JSON formatted payload. The payload is an object with the following parameters/properties:


Request Object properties

tenant

Value is an Object, containing three properties - platformCode, companyCode, and environment - detailed below

tenant.platform

Value is a string. Use the static value of "AWS Connect".

tenant.companyCode

Value is a string. Use your Symbee Connect Company Alias.

tenant.environment

Value is a string. Use your Symbee Connect Environment name.

includeAmazonQueues

Value is a boolean (true or false). A value of false will result in a list of only Symbee Connect delivered Skill Queues being returned. A value of true returns both the Symbee Connect Skill Queues as well as the statistics for all Amazon Connect Queues defined in the Amazon Connect instance associated with the Symbee Connect environment.

queuesInterested

Optional. If provided, a list of objects, each containing the queue identifiers of the queues to return statistics for. If not provided, statistics for all configured queues will be returned.

When provided, the response results are filtered to only return statistics for the queues identified in the list.

Each object in the provided list must have a property named: queueId (String) containing either the Symbee Connect Skill Queue Id (for Symbee Connect queues) or the Amazon Connect Queue AWS ARN (for Amazon Connect queues). See example below.


Request Payload Examples

{
    "tenant" : {
        "platformCode": "AWS Connect",
        "companyCode": "abc-gadgets",
        "environment": "prod"
    },
    "includeAmazonQueues": true
}

Example request with a specified list of interested queues used to filter the response:

{
    "tenant" : {
        "platformCode": "AWS Connect",
        "companyCode": "abc-gadgets",
        "environment": "prod"
    },
    "includeAmazonQueues": false,
    "queuesInterested": [
        { queueId: "email-customer-care" },
        { queueId: "sms-customer-care" }        
    ]
}


API Response Format

Standard HTTP Response Codes are used as responses. Therefore HTTP 4xx and 5xx response codes should be treated as failure.

An HTTP 200 OK response will return a JSON payload containing an array of objects - one for each Queue found - each object having properties describing the statistics for the Queue.

Example Response:

The example below shows a response containing both an Amazon Connect Queue as well as two Symbee Connect Skill Queues, as a result of setting the includeAmazonQueues property to true on the request.

[
    {
        "queueInfo": {
            "queueId": "arn:aws:connect:us-east-1:xxxxx:instance/xxxx-xxxx-xxx-xxxx-xxxxxxx/queue/xxxxx-xxxx-xxxx-xxxx-xxxxxx",
            "queueName": "Customer Care Inbound",
            "deliveryProvider": "AMAZON",
            "taskType": "AMAZON_ANY"
        },
        "openClosedState": "OPERATING_HOURS_UNKNOWN",
        "agentsStaffed": 26,
        "agentsAvailable": 0,
        "agentsWorking": 11,
        "agentsInWrap": 3,
        "agentsInError": 0,
        "agentsUnavailable": 10,
        "itemsInQueue": 5,
        "itemsScheduled": 0,
        "itemsBeingDelivered": 0,
        "oldestItem": 125
    },
    {
        "queueInfo": {
            "queueId": "email-customer-care",
            "queueName": "Email Customer Care",
            "deliveryProvider": "SYMBEE",
            "taskType": "EMAIL"
        },
        "openClosedState": "OPERATING_HOURS_OPEN",
        "agentsStaffed": 10,
        "agentsAvailable": 0,
        "agentsWorking": 5,
        "agentsInWrap": 2,
        "agentsInError": 0,
        "agentsUnavailable": 3,
        "itemsInQueue": 27,
        "itemsScheduled": 0,
        "itemsBeingDelivered": 0,
        "oldestItem": 0
    },
    {
        "queueInfo": {
            "queueId": "sms-customer-care",
            "queueName": "SMS Customer Care",
            "deliveryProvider": "SYMBEE",
            "taskType": "SMS_PINPOINT"
        },
        "openClosedState": "FORCED_OPEN",
        "agentsStaffed": 6,
        "agentsAvailable": 2,
        "agentsWorking": 1,
        "agentsInWrap": 0,
        "agentsInError": 0,
        "agentsUnavailable": 1,
        "itemsInQueue": 0,
        "itemsScheduled": 0,
        "itemsBeingDelivered": 0,
        "oldestItem": 0
    }   
]

API Response Elements

Each Queue Statistics object in the JSON response contains the following:

queueInfo

An object describing the details of the Queue containing 4 properties - queueId, queueName, deliveryProvider, and taskType - described below.

queueInfo.queueId

Value is a string. For an Amazon Connect Queue (see queueInfo.deliveryProvider) this will be the AWS ARN for the Queue. For a Symbee Connect Skill Queue this is the Skill Queue Id.

queueInfo.queueName

Value is a string. The display name for the Amazon Connect Queue or Symbee Connect Skill Queue.

queueInfo.deliveryProvider

Value is a string. One of:

queueInfo.taskType

Value is a string.

For an Amazon Connect Queue the value will always be AMAZON_ANY (as in Amazon Connect a Queue can technically contain Voice Contacts, Chat Contacts, or Task Contacts)

For a Symbee Connect Skill Queue, the taskType will be one of the following:

openClosedState

Value is a string. One of:

agentsStaffed

Value is a number. The number of agents assigned to this Queue or Skill Queue and logged in. Includes agents assigned to this Queue or Skill Queue that are currently working an interaction in another skill.

agentsAvailable

Value is a number. The number of agents assigned to this Queue or Skill Queue that are currently available for new interactions (agents currently in an Available or Idle state and not currently working any interactions).

agentsWorking

Value is a number. The number of agents actively handling one or more interactions.

agentsInWrap

Value is a number. The number of agents in the After Contact Work (ACW/Wrap) state.

agentsInError

Value is a number. The number of agents in the Error (for example: Missed Call/Task) state.

agentsUnavailable

Value is a number. The total number of agents in a non-productive / unavailable state. (for example: Break, Lunch, etc.).

itemsInQueue

Value is a number. The total number of calls or interactions currently waiting in queue.

itemsScheduled

Value is a number. Only relevant for Amazon Connect Voice-related queues - the total customers that are scheduled for a callback that is waiting to become due.

itemsBeingDelivered

Value is a number. The number interactions currently "in flight" alerting at an agent waiting to be accepted.

oldestItem

Value is a number. The age, in seconds, of the oldest interaction waiting in queue. This value will be zero if no interactions are waiting in queue. Currently, this value will also be 0 for any Queue with a deliveryProvider set to SYMBEE (coming in a future release).