Skip to content

KAZOO Support Channels

This documentation is curated by 2600Hz as part of the KAZOO open source project. Join our community forums here for peer support. Only features in the docs.2600hz.com/supported space are included as part of our 2600Hz Support Services plan.

Qubicle Crossbar Recipient API#

Introduction#

This API provides an API for qubicle recipients that allows a user to control recipient state as well as get information about recipient state.

Actions#

List recipients#

This action will return a list of all configured recipients for an account.

GET /v2/accounts/{ACCOUNT_ID}/qubicle_recipients/

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

{
    "page_size":2,
    "data":[
        {"id":"{RECIPIENT_ID1}","name":"{RECIPIENT_NAME1}"},
        {"id":"{RECIPIENT_ID2}","name":"{RECIPIENT_NAME2}"}
    ],
    "status":"success",
    "revision":"{REVISION}",
    "request_id":"{REQUEST_ID}",
    "auth_token":"{AUTH_TOKEN}"
}

Get recipient configuration#

This action will return the recipient configuration of the specified recipient. NOTE this is actually a users document.

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

The returned document is a Kazoo users document

Get recipient status#

Returns the current status of the recipient.

GET /v2/accounts/{ACCOUNT_ID}/qubicle_recipients/{USER_ID}/status

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

{
    "data":{
        "available": {AVAILABLE},
        "availability_state": {AVAIL_STATE},
        "queue_availability": {QUEUE_AVAILABILITY},
        "offered_call": {OFFERED_CALL_INFO},
        "handling_call": {HANDLING_CALL_INFO},
        "wiretapping_recipient": {WIRETAPPING_RECIPIENT_ID},
        "wiretap_mode": {WIRETAP_MODE},
        "wrapup_time_seconds": {WRAPUP_TIME_SECONDS},
        "stats": {
            "total_calls": {TOTAL_CALLS},
            "missed_calls": {MISSED_CALLS},
            "avg_call_time": {AVG_CALL_TIME},
            "login_time": {LOGIN_TIME},
            "last_action_time": {LAST_ACTION_TIME},
            "last_handled_time": {LAST_HANDLED_TIME}
        },
        "node": {RUNNING_ON_NODE}
    },
    "status":"success",
    "request_id":"{REQUEST_ID}",
    "auth_token":"{AUTH_TOKEN}"
}
  • Available: true or false depending on recipient availability
  • Avg-Call-Time: the average amount of time the recipient has spent on a call (in seconds)
  • Login-Time: the unix timestamp of when the recipient logged in
  • Total-Calls: the total number of calls that the recipient has handled
  • Missed-Calls: the total number of calls that the recipient failed to handle for any reason
  • Availability-State: The state of the recipient ( "Ready" | "Away" | "Wrapup-Time" | "Call-Offer" | "On-A-Call" | "Not-Logged-In" )
  • Away-Reason: Away reason of the recipient
  • Queue-Availability: IF a per-queue availability flag(s) have been set, they will be reported here as a list of queue-id -> boolean values
  • Last-Action-Time: The timestamp of the last time the recipient changed state
  • Last-Handled-Time: The timestamp of the last time the recipient was delivered a call
  • Offered-Call: IF there is a call currently being offered, this will contain the Queue-ID, Session-ID, Caller-ID-Name, Caller-ID-Number, Queue-Enter-Time of the call
  • Handling-Call: IF there is a call currently being handled, this will contain the Queue-ID, Session-ID, Caller-ID-Name, Caller-ID-Number, Queue-Enter-Time of the call
  • Wrapup-Time-Seconds: The time left, in seconds, until the recipient is out of wrapup (0 if they are not on wrap up)
  • Node: The node that the process for this recipient is running on
  • Wiretapping-Recipient: IF the recipient is wiretapping another recipient, this will be the id of the target recipient
  • Wiretap-Mode: IF the recipient is wiretapping another recipient, this will be the mode (whisper, eavesdrop, barge)

Get recipient list status#

Returns the current status of a list of recipients.

POST /v2/accounts/{ACCOUNT_ID}/qubicle_recipients/status

curl -v -X POST -H "X-Auth-Token: {AUTH_TOKEN}" -H "Content-Type: application/json" http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/qubicle_recipients/status -d '{"data":{"recipient_ids":[{RECIP_ID_1},{RECIP_ID_2},{RECIP_ID_3}]}}'

{
    "data":{
        {RECIP_ID_1}: {
            "available": {AVAILABLE},
            "availability_state": {AVAIL_STATE},
            "offered_call": {OFFERED_CALL_INFO},
            "handling_call": {HANDLING_CALL_INFO},
            "wrapup_time_seconds": {WRAPUP_TIME_SECONDS},
            "stats": {
                "total_calls": {TOTAL_CALLS},
                "missed_calls": {MISSED_CALLS},
                "avg_call_time": {AVG_CALL_TIME},
                "login_time": {LOGIN_TIME},
                "last_action_time": {LAST_ACTION_TIME},
                "last_handled_time": {LAST_HANDLED_TIME}
            },
            "node": {RUNNING_ON_NODE}
        },
        {RECIP_ID_2}: {
            "available": {AVAILABLE},
            "availability_state": {AVAIL_STATE},
            "offered_call": {OFFERED_CALL_INFO},
            "handling_call": {HANDLING_CALL_INFO},
            "wrapup_time_seconds": {WRAPUP_TIME_SECONDS},
            "stats": (
                "total_calls": {TOTAL_CALLS},
                "missed_calls": {MISSED_CALLS},
                "avg_call_time": {AVG_CALL_TIME},
                "login_time": {LOGIN_TIME},
                "last_action_time": {LAST_ACTION_TIME},
                "last_handled_time": {LAST_HANDLED_TIME}
            },
            "node": {RUNNING_ON_NODE}
        },
        {RECIP_ID_3}: "not_logged_in"
    },
    "status":"success",
    "request_id":"{REQUEST_ID}",
    "auth_token":"{AUTH_TOKEN}"
}

NOTE This will either return the same object as the /status API for a single recipient, or the value "not_logged_in"

Set recipient list status#

Sets the recipient's status of a list of recipients. It is possible to set the status of multiple recipients globally or per queue as / ready / away. It must contain the flag "set_status" as true. It returns a confirmation of all recipients' status.

POST /v2/accounts/{ACCOUNT_ID}/qubicle_recipients/status

curl -v -X POST -H "X-Auth-Token: {AUTH_TOKEN}" -H "Content-Type: application/json" http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/qubicle_recipients/status -d '{"data":{[{<<"set_status">>,true},{{RECIP_ID_1},{[{<<"global">>,<<"ready">>},{{QUEUE_ID_1},<<"away">>}]}, {{RECIP_ID_2}, {[{<<"global">>,<<"ready">>},{<<"c6564319c5996b0db6f4e53d69db79d8">>,<<"ready">>}]}}}}'

{
    "data":{
        {RECIP_ID_1}: {
            "global": "ok",
            "{QUEUE_ID_1}": "ok",
        },
        {RECIP_ID_2}: {
            "global": "ok",
            "{QUEUE_ID_1}": "error",
        }
    },
    "status":"success",
    "request_id":"{REQUEST_ID}",
    "auth_token":"{AUTH_TOKEN}"
}

Login recipient#

The login action will log a recipient in and start the recipient process.

POST /v2/accounts/{ACCOUNT_ID}/qubicle_recipients/{RECIPIENT_ID}/

curl -v -X POST -H "X-Auth-Token: {AUTH_TOKEN}" -H "Content-Type: application/json" http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/qubicle_recipients/{RECIPIENT_ID} -d '{"data":{"action":"login"}}'

{
    "data":{
        "action":"login"
    },
    "status":"success",
    "request_id":"{REQUEST_ID}",
    "auth_token":"{AUTH_TOKEN}"
}

Logout recipient#

The logout action will terminate the recipient process, and log the recipient out of Qubicle.

POST /v2/accounts/{ACCOUNT_ID}/qubicle_recipients/{RECIPIENT_ID}/

curl -v -X POST -H "X-Auth-Token: {AUTH_TOKEN}" -H "Content-Type: application/json" http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/qubicle_recipients/{RECIPIENT_ID} -d '{"data":{"action":"logout"}}':

{
    "data":{
        "action":"logout"
    },
    "status":"success",
    "request_id":"{REQUEST_ID}",
    "auth_token":"{AUTH_TOKEN}"
}

Set recipient status#

Sets the recipient's status. The possible status values are login / logout / ready / away. The recipient must be logged in (status set to login) prior to being able to set a ready / away status. The "queue_id" argument is OPTIONAL and if present will set the availability for that queue only.

POST /v2/accounts/{ACCOUNT_ID}/qubicle_recipients/{RECIPIENT_ID}/status

curl -v -X POST -H "X-Auth-Token: {AUTH_TOKEN}" -H "Content-Type: application/json" http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/qubicle_recipients/{USER_ID}/status -d '{"data":{"status":"{STATUS}"}}'

{
    "data":{
        "status":"{STATUS}",
        "queue_id":{QUEUE_ID <OPTIONAL>}
    },
    "status":"success",
    "request_id":"{REQUEST_ID}",
    "auth_token":"{AUTH_TOKEN}"
}

Extend Wrap-Up Time#

The wrapup_extend action will reset the recipient's wrap up time to the full amount. The amount varies based on the configuration of the queue the previous call was handled from.

POST /v2/accounts/{ACCOUNT_ID}/qubicle_recipients/{RECIPIENT_ID}/

curl -v -X POST -H "X-Auth-Token: {AUTH_TOKEN}" -H "Content-Type: application/json" http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/qubicle_recipients/{RECIPIENT_ID} -d '{"data":{"action":"wrapup_extend"}}'

{
    "data":{
        "action":"wrapup_extend"
    },
    "status":"success",
    "request_id":"{REQUEST_ID}",
    "auth_token":"{AUTH_TOKEN}"
}

Cancel Wrap-Up Time#

The wrapup_cancel action will end the recipients current wrapup time.

POST /v2/accounts/{ACCOUNT_ID}/qubicle_recipients/{RECIPIENT_ID}/

curl -v -X POST -H "X-Auth-Token: {AUTH_TOKEN}" -H "Content-Type: application/json" http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/qubicle_recipients/{RECIPIENT_ID} -d '{"data":{"action":"wrapup_cancel"}}'

{
    "data":{
        "action":"wrapup_cancel"
    },
    "status":"success",
    "request_id":"{REQUEST_ID}",
    "auth_token":"{AUTH_TOKEN}"
}

Monitor Recipient#

Pro only feature#

The monitor action will eavesdrop another recipient (if the current recipient has the permission enabled, and you are using Callcenter Pro)

The possible mode values are:

  • "eavesdrop": the monitoring recipient can hear both the caller and agent (this is the default mode)
  • "whisper": the monitoring recipient can talk to the agent only, but hear both parties
  • "barge": the monitoring recipient is in a 3 way call with the agent and caller

POST /v2/accounts/{ACCOUNT_ID}/qubicle_recipients/{RECIPIENT_ID}/

curl -v -X POST -H "X-Auth-Token: {AUTH_TOKEN}" -H "Content-Type: application/json" http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/qubicle_recipients/{RECIPIENT_ID} -d '{"data":{"action":"monitor", "target": {TARGET_RECIPIENT_ID}, "mode": {MODE}}'

{
    "data":{
        "action":"monitor"
    },
    "status":"success",
    "request_id":"{REQUEST_ID}",
    "auth_token":"{AUTH_TOKEN}"
}