The Wallboard Realtime feed

The Wallboard realtime feed is optimized for using in wallboards like Geomant Wallboard product.

The schema is split into two major categories, the Now KPIs and the Today KPIs. Both present similar data structures but with different aggregation schemes.

The latest feed schema version is v3.

Note

Please note that Today KPIs does not reflect data that is still being processed, for example, the SLA will not update until the current conversation ends.

Now KPIs

Now KPIs are split into 2 groups, Now Summaries and Now Queues.

Now summaries

The Now summaries schema consist of the following structures:

"nowSummary": {
   "availableAgents": 1, // agents available now
   "loggedInAgents": 1 // total logged in agents now
}

"nowVoiceSummary": {
   "longestWaitTime": "00:00:00", // current longest wait time
   "connectedConversations": 0, // current count of conversations connected to an agent
   "waitingConversations": 0 // current count of conversations waiting in voice queues
}

"nowChatSummary": {
   "longestWaitTime": "00:00:00", // current longest wait time
   "connectedConversations": 0, // current count of conversations connected to an agent
   "waitingConversations": 0 // current count of conversations waiting in chat queues
}

Now queues

Listed by their unique ID, the Queue specific Now KPIs are presented here.

"queues": {
   "jQgXH7P5c9RhHXJ4Fh3dE": {
       "queueName": "My queue name", // the name of the queue
       "longestWaitTime": "00:00:00", // longest wait time now
       "connected": 0, // current count of conversations connected to an agent originating from this queue
       "availableAgents": 0, // count of available agents having the attributes required to handle conversations from this queue
       "loggedInAgents": 0, // count of logged in agents having the attributes required to handle conversations from this queue
       "waiting": 0 // Count of conversations waiting in the queue
   }
}

Today KPIs

Similarly to Now KPIs, Today KPIs are also split into Summary and Today Queues.

Today summary

The Today summaries schema contains the following structures:

"todayVoiceSummary": {
   "slaPercentage": 0, // the SLA of all the conversations handled today so far
   "handledWithinSla": 0, // conversations handled within the SLA target set on the queues
   "handledOutOfSla": 0, // conversations handled but not within the SLA target set on the queues
   "abandonedWithinSla": 0, // customer disconnected while within the SLA target set on the queues
   "avgHandlingTime": "00:00:00", // average task handling time. Avg = Sum of all task handle time / count of tasks
   "avgWrapUpTime": "00:00:00", // average task wrap up time. Avg = Sum of all task wrap-up time / count of tasks
   "inboundConversationCount": 0, // count of inbound conversation for today so far
   "outboundConversationCount": 0, // count of outbound conversation for today so far
   "queuedConversationCount": 0, // count of conversation queued for today so far
   "totalAbandonedCount": 0, // count of conversations abandoned today so far
   "totalHandlingTime": "00:00:00" // the summary of the handling times of all conversations for today so far
}

"todayChatSummary": {
   "handledWithinSla": 0, // conversations handled within the SLA target set on the queues
   "handledOutOfSla": 0, // conversations handled but not within the SLA target set on the queues
   "handledOutboundCount": 0, // count of outbound conversation that got handled today so far
   "handledInboundCount": 0, // count of inbound conversation that got handled today so far
   "totalHandlingTime": "00:00:00", // the summary of the handling times of all conversations for today so far
   "inboundConversationCount": 0, // count of inbound conversation for today so far
   "outboundConversationCount": 0 // count of outbound conversation for today so far
}

"todayEmailSummary": {
   "handledWithinSla": 0, // conversations handled within the SLA target set on the queues
   "handledOutOfSla": 0, // conversations handled but not within the SLA target set on the queues
   "handledOutboundCount": 0, // count of outbound conversation that got handled today so far
   "handledInboundCount": 0 // count of inbound conversation that got handled today so far
}

"todayExternalTasks": { // tasks launched in lookup against a customer record, with scripting executed and scripting data stored
   "count": 0, // number of external tasks handled today so far
   "avgHandlingTime": "00:00:00", // average external task handling time for today so far
   "totalHandlingTime": "00:00:00" // the total external task handling time for today so far
}

Today queues

Listed by their unique ID, the queue specific KPIs are presented here.

"queues": {
   "jQgXH7P5c9RhHXJ4Fh3dE": {
       "queueName": "My queue", // the name of the queue
       "slaPercentage": 0, // Calculated service level percentage. Formula: (Number of call answered within the SL threshold set on the queue/number of calls offered) * 100.
       "handledWithinSla": 0, // conversations handled within the SLA target set on the queue
       "handledOutOfSla": 0, // conversations handled but not within the SLA target set on the queue
       "abandonedWithinSla": 0, // customer disconnected while within the SLA target set on the queue
       "totalAbandonedCount": 0, // the count of all abandoned conversations today so far
       "queueTimeoutCount": 0, // the amount of conversations going through the timeout output of a queue.
       "totalAgentActiveTime": 00:00:00, // How long the agents spent talking to customers from this queue
       "averageAgentActiveTime": 00:00:00, //  The average of the time spent by agents talking to customers from this queue
       "longestAgentActiveTime": 00:00:00, // The longest duration for an agent talking to a customer from this queue
       "longestWaitTime": 00:00:00, // The longest duration of a customer waiting in the queue to talk to an agent
       "averageWaitTime": 00:00:00 // the average queue time. Time spent by customers waiting in this queue, on average
   }
}

Today channels

Listed by their unique ID, the channel specific KPIs are presented here.

    "channels": {
      "1000196": { // the channel ID
        "channelName": "Orange Test 5", // the name of the channel
        "businessUnitId": "55beb0b1fdd5440ab0f614663d9c0c01", // the business unit ID, if any
        "outboundSuccessCount": 0, // count of successful outbound call, success is measured when the customer is reached
        "outboundFailCount": 0, // count of unsuccessful outbound calls, when the customer is not reached
        "outboundConversationCount": 0, //count of outbound conversations initiated
        "outboundTaskCount": 0, // count of outbound tasks initiated
        "averageOutboundTaskHandlingTimeInSeconds": 0, // average handling time of outbound tasks
        "averageOutboundTaskWrapUpTimeInSeconds": 0 // average wrap up time for outbound tasks
      }
    }

Agents

    "agents": [
        {
            "today": { // today Agent related KPIs, reset at midnight
                "id": "6687e6e9bb13c1c59daa2c56", // the unique ID of the agent
                "name": "Daenerys Targaryen", // the neame of the agent
                "voiceTasks": { 
                    "inboundHandledCount": 0, // count of inbound calls handled by the agent, excluding campaigns
                    "inboundMissedCount": 0, // count of calls missed by the agent, missed means RONA timer kicked & the agent did not manage to click accept or reject
                    "inboundRejectedCount": 0, // count of calls the agent explicitly rejected by clicking the red drop button
                    "outboundHandledCount": 0, // count of outbound calls handled by the agent
                    "totalActiveTime": "00:00:00" // total time spent by the agent talking to the customer
                }
            },
            "now": { // now KPIs for the agent
                "id": "6687e6e9bb13c1c59daa2c56", // the unique ID of the agent
                "name": "Daenerys Targaryen", // the name of the agentr
                "currentState": "Break", // the current state of the agent
                "breakName": null, // the name of the break, populated only if the agent is on break status
                "timeSpentInCurrentState": "00:33:11" // the time spent by the agent in the current state
            }
        },
    ]

Transform or extend wallboard data feed using JSONata

The existing KPI list can be extended or transformed through JSONata, a lightweight query and transformation language for JSON data, supported by the Graia CCaaS realtime feed.

This section of the article will guide you through the process of extending the KPI list with a new calculated KPI.

Construct/get the original data stream url that you plan to transform/extend
- Example: https://realtime.buzzeasy.com/wallboard/v2/?tenantId=YOUR_TENANT&key=API_KEY
Construct your jsonata expression that will transform the data
- Grab the json data that is returned by the original url
- Paste into jsonata editor: https://try.jsonata.org/ (this is only needed to help you debug your jsonata)
- Write your jsonata expression using the editor. Results are visible immediately.
- JSONata official docs: https://docs.jsonata.org/overview.html
Construct the transform url
- Add the /transform at the start of your original url
- Provide your jsonata expression via the jsonata query parameter
  - Encode the expression itself before adding to the url: https://www.urlencoder.org/
- Example: https://realtime.buzzeasy.com/transform/wallboard/v2/?tenantId=YOUR_TENANT&key=API_KEY&jsonata=YOUR_JSONATA
Thats it! You can use the constructed transform url directly as your wallboard data feed.

JSONata expression example (using the transform operator)

While JSONata itself has plenty of features (query expressions, operators and functions) to query and manipulate the data, it has one particular solution which is worth to highlight: the Transform operator.

The main benefit of the transform operator is that it can easily extend the data feed without changing anything on the original data itself.

Below are a few practical examples:

Add static property to nowSummary:

$ ~> | now.nowSummary | { "hello": "World!" } |
Add simple calculated column to nowSummary:

$ ~> | now.nowSummary | { "underUtilization": availableAgents / loggedInAgents } |
Add new column to nowSummary with zero division check, rounding and percentage calculation:

$ ~> | now.nowSummary | { "underutilizationPercentage": $boolean(loggedInAgents) ? $round((availableAgents / loggedInAgents) * 100) : 0 } |
Add the same calculated column to all queues (calculation happens for each queue) under the Now section:

$ ~> | now.queues.* | { "underutilizationPercentage": $boolean(loggedInAgents) ? $round((availableAgents / loggedInAgents) * 100) : 0 } |