Qubicle is an application for providing call queues using VirtualPBX. The Qubicle application allows you to configure VirtualPBX users as recipients for inbound calls distributed amongst one or many queues. Queues are independently configured and will distribute calls according to one of several different routing methods to recipients that have been assigned to that queue that are currently available.

Concepts

Queues

A Queue is the primary entity in Qubicle, it represents a queue of sessions that will be distributed according to some routing method to a list of member recipients. The queue process is persistent, and will be running regardless of if there are sessions that are in queue, or if there are recipients logged in.

Recipients

Recipients are the entity responsible for handling sessions in Qubicle. These can be though of as 'agents' in the logical sense. They encapsulate all data and state needed to determine the current availability for a recipient, the information needed to route a session to the recipient (where to send the call) as well as data that is useful for performance metrics about the recipient. The recipient process's lifetime is tied to a given recipients login state. Offline recipients are not represented in the Qubicle system. The recipient process also handles all external API interaction that allows changing of state and handling of sessions.

Sessions

Sessions are the entity in Qubicle that represent something that a recipient handles. In the primary case this is an inbound caller. A session is created when you send a call to the Callflows Qubicle endpoint. Once the session is created it is joined into the configured queue for that endpoint and ownership is passed on to Qubicle. The session manages all data related to the entities time is the Qubicle application, such as which queues it has been a part of and for how long, which recipient handled the call, and other data that may be related to the delivery of the entity.

Events

All entities in Qubicle emit events as they perform the actions needed to route a session to its ultimate destination. Using these events you can obtain real-time information about the state of the system, and the state of these entities.

Session Events

A session will emit events that are relevant from the perspective of an inbound call.

Session Events

Queue Events

A queue will emit events for all actions it takes, such as when a session joins and leaves, as well as when it is delivered to a recipient.

Queue Events

Recipient Events

A recipient will emit events for all sessions that it is handling via a queue, as well as events about the state and availability of the recipient.

Recipient Events

Integration

The Qubicle application integrates with VirtualPBX to provide call routing and delivery. This integration is achieved by using Callflows to route calls into Qubicle and Blackhole to emit events in real time via Websockets from Qubicle.

Callflows Integration

There are two callflow modules for Qubicle that allow VirtualPBX to interact with it. The first and primary module is 'cf_qubicle' which will allow calls to be routed to Qubicle queues. The second is 'cf_qubicle_recipient' which will allow calls to control recipient state. This can be used to route a feature code or extension to a callflow that will allow recipients to log in and out from a device.

Callflows

Qubicle Callflow

The Qubicle callflow module is used to route calls to a queue in Qubicle.

Configuration

Plain Text

    "flow": {
       "data": {
            "queue_id" | "id": {QUEUE_ID},
       },
       "module": "qubicle",
       "children": {
       }
   },

Queue

The queue parameter is the ID of a qubicle Queue that the call is to be routed to, it can be named either 'queue_id', or just 'id'

Qubicle Recipient Callflow

The Qubicle recipient callflow module is used to trigger recipient actions from Callflows.

Configuration

Plain Text

   "flow": {
       "data": {
            "link_method": {LINK_METHOD},
            "action": {ACTION},
            "target_queue": {TARGET_QUEUE},
            "pin_prompt_media": {PIN_PROMPT_MEDIA},
            "success_media": {SUCCESS_MEDIA_ID},
            "failure_media": {FAILURE_MEDIA_ID},
       },
       "module": "qubicle_recipient",
       "children": {
       }
   },

Link Method

The link method parameter will determine how the inbound caller is linked to a Qubicle user in order to determine what user to send the action as. It can be one of the following values:

"device": The Authorizing-ID of the call will be matched against the owner for the device. If the owner is found and Qubicle enabled, the action is emitted for that owner.
"pin": The caller is prompted for a pin code that is checked against the "qubicle.pin" configuration key on the users document, if there is a successful match the action is emitted for that user.
"both" (default): The device is checked first, failing a match the caller is then prompted for a pin.

Action

This will determine the action that is emitted after the call has been linked to a user, the following values are allowed:

"login"
"logout"
"ready"
"away"
"login_ready" - This will perform BOTH the login and ready actions in one step.
"state_toggle" - This action will log the recipient in and go ready if they are logged out, or log them out if they are logged in.

The "ready" and "away" actions MAY be targeted at a specific queue if the "target_queue" value is configured to the ID of the Qubicle queue.

Target Queue

This will ONLY be used when sending a "ready" or "away" action, and will target the per-queue availability setting for the user.

Pin Prompt Media

This is the ID of a media file that will be played to prompt the caller to enter their pin for linking to a Qubicle recipient enabled user with a configured 'pincode'.

Success Media

This is the ID of a media file that will be played when the action is successfully emitted.

Failure Media

This is the ID of a media file that will be played when the action fails (due to the lack of ability to associated a user with the caller).

APIs

Qubicle Queue API

Introduction

This API is used for configuring queues in Qubicle, as well as altering the membership of recipients in queues.

Schema

Plain Text

{
    "$schema": "<http://json-schema.org/draft-04/schema#>",
    "_id": "qubicle_queue",
    "description": "Defines a queue in Qubicle",
    "name": "Qubicle Call Queue",
    "properties": {
        "agent_wrapup_time": {
            "default": 0,
            "description": "Pre-defined wait period applied after an agent handles a customer call (in seconds)",
            "minimum": 0,
            "name": "Agent Wrapup Time",
            "type": "integer"
        },
        "force_away_on_reject": {
            "default": false,
            "description": "If set to true and a recipient rejects a call, they will be forced to away state",
            "type": "boolean"
        },
        "hold_treatment": {
            "description": "Media ID (or appropriate media URI) of media to play while caller is on hold.",
            "name": "Hold Treatment",
            "type": "string"
        },
        "name": {
            "description": "A friendly name for the queue",
            "maxLength": 128,
            "minLength": 1,
            "name": "Name",
            "type": "string"
        },
        "queue_router": {
            "default": "route_round_robin",
            "description": "The queue router used for routing and delivering calls to recipients",
            "name": "Router",
            "type": "string"
        },
        "queue_type": {
            "default": "queue_basic",
            "description": "The type of queue",
            "enum": [
                "queue_basic"
            ],
            "name": "Type",
            "type": "string"
        },
        "ring_timeout": {
            "default": 20,
            "description": "Amount of time in seconds that qubicle will wait while ringing for the agent to successfully answer a call.",
            "minimum": 1,
            "name": "Agent Connect Timeout",
            "type": "integer"
        },
        "tick_time": {
            "default": 1000,
            "description": "The time between delivery ticks in milliseconds",
            "minimum": 250,
            "name": "Tick Time",
            "type": "integer"
        },
        "timeout": {
            "default": 3600,
            "description": "The maximum amount of time in seconds that a call will wait in queue.",
            "minimum": 10,
            "name": "Queue Timeout",
            "type": "integer"
        },
        "timeout_if_size_exceeds": {
            "default": 0,
            "description": "If set to a non-zero value the queue will immediately time out any call entering the queue over the size",
            "type": "integer"
        },
        "timeout_immediately_if_empty": {
            "default": false,
            "description": "If set to true and a call enters the queue while it has no logged in agents, the call will time out",
            "type": "boolean"
        },
        "timeout_redirect": {
            "description": "The ID of a queue that the call will be sent to in the event of a timeout",
            "type": "string"
        }
    },
    "required": [
        "name"
    ],
    "type": "object"
}

List Queues

This action will list all queues that are configured for the specified account.

GET /v2/accounts/{ACCOUNT_ID}/qubicle_queues

Plain Text

curl -v -X GET -H "X-Auth-Token: {AUTH_TOKEN}" -H "Content-Type: application/json" http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/qubicle_queues

Plain Text

{
    "page_size":{RESULT_COUNT},
    "data":[
        {
            "id": "{QUEUE_ID}",
            "name": "{QUEUE_NAME}"
        }
    ],
    "revision":"{REVISION}",
    "request_id":"{REQUEST_ID}",
    "status":"success",
    "auth_token":"{AUTH_TOKEN}"
}

Queue Status

This action will return the status of the queue.

GET /v2/accounts/{ACCOUNT_ID}/qubicle_queues/{QUEUE_ID}/status

Plain Text

curl -v -X GET -H "X-Auth-Token: {AUTH_TOKEN}" -H "Content-Type: application/json" http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/qubicle_queues/{QUEUE_ID}/status

{ "data": { "active_recipient_count": {ACTIVE_RECIPIENT_COUNT}, "available_recipient_count": {AVAILABLE_RECIPIENT_COUNT}, "stats": { "estimated_wait": {EST_WAIT_TIME}, "average_wait": {AVG_WAIT_TIME}, "recipient_count": {RECIPIENT_COUNT}, "active_session_count": {ACTIVE_SESSION_COUNT}, "total_sessions": {TOTAL_SESSION_COUNT}, "missed_sessions": {MISSED_COUNT}, "abandoned_sessions": {ABANDONED_COUNT} }, "node": {RUNNING_ON_NODE} }, "revision":"{REVISION}", "request_id":"{REQUEST_ID}", "status":"success", "auth_token":"{AUTH_TOKEN}" }

Active-Session-Count: Count of currently active sessions in the queue
Recipient-Count: Count of total configured recipients for the queue
Active-Recipient-Count: Count of currently active recipients (logged in)
Available-Recipient-Count: Count of currently available recipients (ready to take a call)
Estimated-Wait: The currently estimated wait time for a session in queue
Average-Wait: The DAILY average wait time for all sessions
Total-Sessions: The DAILY total session count for the queue
Missed-Sessions: The DAILY total count of missed sessions (sessions that timed out without being handled)
Abandoned-Sessions: The DAILY total count of abandoned sessions (session left queue prior to being handled)
Node: The node that the queue process is running on

Queue List Status

This action will return the status for the listed queues

GET /v2/accounts/{ACCOUNT_ID}/qubicle_queues/status

Plain Text

curl -v -X GET -H "X-Auth-Token: {AUTH_TOKEN}" -H "Content-Type: application/json" http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/qubicle_queues/{QUEUE_ID}/status -d '{"data":{"queue_ids":[{QUEUE_ID_1},{QUEUE_ID_2}]}}'

Plain Text

{
    "data":{
        {QUEUE_ID_1}: {
            "active_recipient_count": {ACTIVE_RECIPIENT_COUNT},
            "available_recipient_count": {AVAILABLE_RECIPIENT_COUNT},
            "stats": {
                "estimated_wait": {EST_WAIT_TIME},
                "average_wait": {AVG_WAIT_TIME},
                "recipient_count": {RECIPIENT_COUNT},
                "active_session_count": {ACTIVE_SESSION_COUNT},
                "total_sessions": {TOTAL_SESSION_COUNT},
                "missed_sessions": {MISSED_COUNT},
                "abandoned_sessions": {ABANDONED_COUNT}
            },
            "node": {RUNNING_ON_NODE}
        },
        {QUEUE_ID_2}: {
            "active_recipient_count": {ACTIVE_RECIPIENT_COUNT},
            "available_recipient_count": {AVAILABLE_RECIPIENT_COUNT},
            "stats": {
                "estimated_wait": {EST_WAIT_TIME},
                "average_wait": {AVG_WAIT_TIME},
                "recipient_count": {RECIPIENT_COUNT},
                "active_session_count": {ACTIVE_SESSION_COUNT},
                "total_sessions": {TOTAL_SESSION_COUNT},
                "missed_sessions": {MISSED_COUNT},
                "abandoned_sessions": {ABANDONED_COUNT}
            },
            "node": {RUNNING_ON_NODE}
        }
    },
    "revision":"{REVISION}",
    "request_id":"{REQUEST_ID}",
    "status":"success",
    "auth_token":"{AUTH_TOKEN}"
}

Queue Information

This action will return all configuration data for a specific queue.

GET /v2/accounts/{ACCOUNT_ID}/qubicle_queues/{QUEUE_ID}

Plain Text