Agent Status Metrics API

Agent Status Metrics API

ZohoVoice REST API


Authorization


HeaderKey

Description

Authorization *

Zoho-oauthtoken<space><ACCESS_TOKEN>

Accept *

Set to application/json.


OAuth Doc


GET AGENT'S ONLINE STATUS AUDIT


This API fetches the status details of an agent during a given time period.

Scope : ZohoVoice.agents.READ

Method : GET

URL : https://voice.zoho.com/rest/json/zv/metrics/statusaudit/list


Params:


Key

Type

Description

from

number

 

from size

size

number

number of logs

fromEpoch*

long

timestamp in epoch millis

toEpoch*

long

timestamp in epoch millis

agentIds*

String

agent ID

sortField

String

status by which to sort - either On Call, Offline, On Break, Available, Busy or Working Time

sortMetric

String

metric by which to sort - either avg, sum, min or max

sortOrder

String

asc, desc

tz*

String

timezone

excludeDays

String

list of weekdays to exclude where 1 denotes Monday, 7 denotes Sunday, without any separator

eg: to exclude weekends, use 67

excludeStatus

String

list of statuses to exclude separated by comma

eg: to exclude Offline & Break, use On Break,Offline



Response :


  1. {
  2.    "code": "200",
  3.    "list": {
  4.        "agentStatus": [
  5.            {
  6.                "previousResult": {
  7.                    "agent_id": "3029000000002015",
  8.                    "previous_action_time": 1728976200110,
  9.                    "agentEmail": "janice@zylker.com",
  10.                    "current_action_time": 1728977814592,
  11.                    "agentName": "Jan",
  12.                    "triggered_by_username": "Jan",
  13.                    "triggered_by": "User",
  14.                    "duration": 1614482,
  15.                    "triggered_by_medium": "Web",
  16.                    "triggered_by_zuid": "67560001",
  17.                    "current_status": "Available",
  18.                    "zsoid": "67560292",
  19.                    "triggered_reason": "",
  20.                    "previous_status": "Offline"
  21.                },
  22.                "agent_id": "3029000000002015",
  23.                "agentEmail": "janice@zylker.com",
  24.                "agentName": "Jan",
  25.                "dates": [
  26.                    {
  27.                        "hits": [
  28.                            {
  29.                                "agent_id": "3029000000002015",
  30.                                "previous_action_time": 1728977814592,
  31.                                "agentEmail": "janice@zylker.com",
  32.                                "triggered_reason_desc": "Automatic Check In",
  33.                                "current_action_time": 1729056300109,
  34.                                "agentName": "Jan",
  35.                                "triggered_by": "Zoho Voice",
  36.                                "duration": 78485517,
  37.                                "triggered_by_medium": "",
  38.                                "triggered_by_zuid": "",
  39.                                "current_status": "Available",
  40.                                "logid": "6prJk5IB_xciauz1XOy0",
  41.                                "zsoid": "67560292",
  42.                                "triggered_reason": "Agent Schedule",
  43.                                "previous_status": "Available"
  44.                            },
  45.                            {
  46.                                "agent_id": "3029000000002015",
  47.                                "previous_action_time": 1729056300109,
  48.                                "agentEmail": "janice@zylker.com",
  49.                                "current_action_time": 1729061808945,
  50.                                "agentName": "Jan",
  51.                                "triggered_by_username": "Jan",
  52.                                "triggered_by": "User",
  53.                                "duration": 5508836,
  54.                                "triggered_by_medium": "Web",
  55.                                "triggered_by_zuid": "67560001",
  56.                                "current_status": "Offline",
  57.                                "logid": "b6MdlJIBm7rVk3YNaz3l",
  58.                                "zsoid": "67560292",
  59.                                "triggered_reason": "",
  60.                                "previous_status": "Available"
  61.                            },
  62.                            ...
  63.                        ],
  64.                        "start_timestamp": 1729036800000,
  65.                        "index": 0
  66.                    },
  67.                    { "hits": [...], "start_timestamp": 1729123200000, "index": 1 },
  68.                    { "hits": [...],"start_timestamp": 1729209600000,"index": 2 },
  69.                    { "hits": [...],"start_timestamp": 1729296000000,"index": 3 },
  70.                    { "hits": [...],"start_timestamp": 1729382400000,"index": 4 },
  71.                    { "hits": [...],"start_timestamp": 1729468800000,"index": 5 },
  72.                    { "hits": [...],"start_timestamp": 1729555200000,"index": 6 }
  73.                ]
  74.            }
  75.        ]
  76.    },
  77.    "status": "SUCCESS"
  78. }


GET A CALL LOG'S STATUS ACTIVITY


This API fetches the status info of all agents in a queue's call log. This can be used to correlate the agents' availability against missed or answered queue calls.


Note: This api is only available for incoming queue call logs. Status correlation is unavailable for other call types, but can still be fetched using 'statusaudit/list' api if the list of agents, startTime & endTime of the call log are known.


Scope: ZohoVoice.agents.READ

Method : GET

URL : https://voice.zoho.com/rest/json/zv/metrics/statusaudit/list/log


Params:


Key

Type

Description

fromEpoch*

long

timestamp in epoch millis

toEpoch*

long

timestamp in epoch millis

logId*

uuid

uuid of call log

queueIds

String

queueIds of queues involved in the call log

tz*

String

timezone to display the results in



Response:



  1. {
  2.    "code": "200",
  3.    "log": {
  4.        "response": [
  5.            {
  6.                "ringingOrder": [
  7.                    {
  8.                        "agentId": "3029000003904005",
  9.                        "rings": [
  10.                            {
  11.                                "start_time": 1729251588000,
  12.                                "queueName": "All in One",
  13.                                "agent_name": "aravindan.e5",
  14.                                "agent_number": 3029000003904005,
  15.                                "ringing_time": 0,
  16.                                "is_answered": false,
  17.                                "strategy": "ring-all",
  18.                                "hangup_cause": {
  19.                                    "hangup_cause_description": "The user you are trying to reach is not available.",
  20.                                    "hangupcause": "UNALLOCATED_NUMBER",
  21.                                    "hangup_cause_displayname": "User unreachable"
  22.                                }
  23.                            }
  24.                        ]
  25.                    },
  26.                    {
  27.                        "agentId": "3029000004016005",
  28.                        "rings": [..]
  29.                    },
  30.                    {
  31.                        "agentId": "3029000000002015",
  32.                        "rings": [..]
  33.                    }
  34.                ],
  35.                "answeredAgent": {},
  36.                "queueDetails": {
  37.                    "_queueId": 3029000004016033,
  38.                    "ringtime_in_queue": 60,
  39.                    "queueName": "All in One",
  40.                    "customer_entry_time": 1729251587000,
  41.                    "strategy": "ring-all",
  42.                    "customer_exit_time": 1729251647000
  43.                },
  44.                "agentStatus": [
  45.                    {
  46.                        "hits": [..],
  47.                        "agent_id": "3029000003904005",
  48.                        "agentName": "aravindan.e5"
  49.                    },
  50.                    {
  51.                        "hits": [..],
  52.                        "agent_id": "3029000004016005",
  53.                        "agentName": "aravindan.e3"
  54.                    },
  55.                    {
  56.                        "hits": [..],
  57.                        "agent_id": "3029000000002015",
  58.                        "agentName": "AravindaN1"
  59.                    },
  60.                    {
  61.                        "hits": [..],
  62.                        "agent_id": "3029000000003003",
  63.                        "agentName": "aravindan2"
  64.                    },
  65.                    {
  66.                        "hits": [..],
  67.                        "agent_id": "3029000000005013",
  68.                        "agentName": "aravindan.e4"
  69.                    }
  70.                ]
  71.            }
  72.        ]
  73.    },
  74.    "status": "SUCCESS"
  75. }



GET AGENTS' AGGREGATED STATUS METRICS (OVER THE COMPLETE PERIOD)


This API returns aggregated status data for a given set of agents or queues

Scope: ZohoVoice.agents.READ

Method: GET

URL: https://voice.zoho.com/rest/json/zv/metrics/statusaudit/overview


Params:


Key

Type

Description

from

number


from size 

size

number

number of logs

fromEpoch*

long

timestamp in epoch millis

toEpoch*

long

timestamp in epoch millis

agentIds*

String

list of agent IDs separated by comma

queueIds*

String

list of queue IDs separated by comma(When both agentIds and queueIds are given, only queueIds are used to filter results)

sortField

String

status by which to sort - either On Call, Offline, On Break, Available, Busy or Working Time

sortMetric

String

metric by which to sort - either avg, sum, min or max

sortOrder

String

asc, desc

tz*

String

timezone

excludeDays

String

list of weekdays to exclude where 1 denotes Monday, 7 denotes Sunday, without any separator

eg: to exclude weekends, use 67

excludeStatus

String

list of statuses to exclude separated by comma

eg: to exclude Offline & Break, use On Break,Offline



Response:



  1. {
  2.    "overview": {
  3.        "agentmetrics": {
  4.            "overallAggregation": {
  5.                "Working Time": {
  6.                    "avg": 140780500.4,
  7.                    "max": 162421466,
  8.                    "onlineStatus": "Working Time",
  9.                    "sum": 703902502,
  10.                    "daily_peragent_avg": 35195125.1
  11.                },
  12.                "Offline": {..},
  13.                "Available": {..},
  14.                "On Call": {..},
  15.                "agentCount": 4,
  16.                "daysCount": 5
  17.            },
  18.            "maxTimeAgents": {
  19.                "On Break": {
  20.                    "duration": "--",
  21.                    "agentName": "--",
  22.                    "previous_status": "On Break"
  23.                },
  24.                "Busy": {
  25.                    "duration": "--",
  26.                    "agentName": "--",
  27.                    "previous_status": "Busy"
  28.                }
  29.            },
  30.            "individualAggregation": [
  31.                {
  32.                    "agent_id": "600000000039003",
  33.                    "agentEmail": "jacques@zylker.com",
  34.                    "agentName": "Jack",
  35.                    "Working Time": {
  36.                        "avg": 40426688,
  37.                        "max": 161471551,
  38.                        "onlineStatus": "Working Time",
  39.                        "sum": 2.0213344E+8
  40.                    },
  41.                    "On Break": {
  42.                        "avg": "--",
  43.                        "peragent_avg": "--",
  44.                        "max": "--",
  45.                        "onlineStatus": "On Break",
  46.                        "sum": "0",
  47.                        "daily_peragent_avg": "--"
  48.                    },
  49.                    "Busy": {
  50.                        "avg": "--",
  51.                        "peragent_avg": "--",
  52.                        "max": "--",
  53.                        "onlineStatus": "Busy",
  54.                        "sum": "0",
  55.                        "daily_peragent_avg": "--"
  56.                    },
  57.                    "Offline": {
  58.                        "avg": "--",
  59.                        "peragent_avg": "--",
  60.                        "max": "--",
  61.                        "onlineStatus": "Offline",
  62.                        "sum": "0",
  63.                        "daily_peragent_avg": "--"
  64.                    },
  65.                    "Available": {
  66.                        "avg": 40265253.8,
  67.                        "max": 161471551,
  68.                        "onlineStatus": "Available",
  69.                        "sum": 201326269
  70.                    },
  71.                    "On Call": {
  72.                        "avg": 161434.2,
  73.                        "max": 311311,
  74.                        "onlineStatus": "On Call",
  75.                        "sum": 807171
  76.                    }
  77.                },
  78.                {..},
  79.                {..},
  80.                {..}
  81.            ]
  82.        }
  83.    },
  84.    "code": "200",
  85.    "status": "SUCCESS"
  86. }


 

GET AGENTS' AGGREGATED STATUS METRICS(BY DAY)


This API returns aggregated status data for a given set of agents or queues

Scope: ZohoVoice.agents.READ

Method: GET

URL: https://voice.zoho.com/rest/json/zv/metrics/statusaudit/calendarSummary


Params:



Key

Type

Description

from

number

from size 

size

number

number of logs

fromEpoch*

long

timestamp in epoch millis

toEpoch*

long

timestamp in epoch millis

agentIds*

String

list of agent IDs separated by comma

queueIds*

String

list of queue IDs separated by comma(When both agentIds and queueIds are given, only queueIds are used to filter results)

tz*

String

timezone

excludeDays

String

list of weekdays to exclude where 1 denotes Monday, 7 denotes Sunday, without any separator

eg: to exclude weekends, use 67

excludeStatus

String

list of statuses to exclude separated by comma

eg: to exclude Offline & Break, use On Break,Offline



  1. {
  2.     "calendarSummary": {
  3.         "histogramAggregation": [
  4.             {
  5.                 "totalRow": {
  6.                     "agent_id": "600000000039003",
  7.                     "agentEmail": "jacques@zylker.com",
  8.                     "agentName": "Jack",
  9.                     "Working Time": {
  10.                         "avg": 40426688,
  11.                         "max": 161471551,
  12.                         "onlineStatus": "Working Time",
  13.                         "sum": 2.0213344E+8
  14.                     },
  15.                     "On Break": {
  16.                         "avg": "--",
  17.                         "peragent_avg": "--",
  18.                         "max": "--",
  19.                         "onlineStatus": "On Break",
  20.                         "sum": "0",
  21.                         "daily_peragent_avg": "--"
  22.                     },
  23.                     "Busy": {..},
  24.                     "Offline": {..},
  25.                     "Available": {..},
  26.                     "On Call": {..}
  27.                 },
  28.                 "intervalsData": {
  29.                     "2024-10-18": {
  30.                         "interval": "2024-10-18",
  31.                         "previous_status": {
  32.                             "Working Time": {
  33.                                 "avg": 5866688,
  34.                                 "max": 2.606828E+7,
  35.                                 "sum": 2.933344E+7,
  36.                                 "previous_status": "Working Time"
  37.                             },
  38.                             "On Break": {
  39.                                 "avg": 0,
  40.                                 "max": 0,
  41.                                 "sum": 0,
  42.                                 "previous_status": "On Break"
  43.                             },
  44.                             "Busy": {
  45.                                 "avg": 0,
  46.                                 "max": 0,
  47.                                 "sum": 0,
  48.                                 "previous_status": "Busy"
  49.                             },
  50.                             "Offline": {
  51.                                 "avg": 0,
  52.                                 "max": 0,
  53.                                 "sum": 0,
  54.                                 "previous_status": "Offline"
  55.                             },
  56.                             "Available": {
  57.                                 "avg": 5732255,
  58.                                 "max": 2.606828E+7,
  59.                                 "sum": 28661275,
  60.                                 "previous_status": "Available"
  61.                             },
  62.                             "On Call": {
  63.                                 "avg": 134433,
  64.                                 "max": 311311,
  65.                                 "sum": 672165,
  66.                                 "previous_status": "On Call"
  67.                             }
  68.                         }
  69.                     },
  70.                     "2024-10-16": {..},
  71.                     "2024-10-17": {..},
  72.                     "2024-10-21": {..},
  73.                     "2024-10-22": {..}
  74.                 },
  75.                 "intervalsList": [
  76.                     "2024-10-16",
  77.                     "2024-10-17",
  78.                     "2024-10-18",
  79.                     "2024-10-21",
  80.                     "2024-10-22"
  81.                 ]
  82.             }
  83.         ],
  84.         "individualAggregation": [
  85.             {
  86.                 "agent_id": "600000000039003",
  87.                 "agentEmail": "jacques@zylker.com",
  88.                 "agentName": "Jack",
  89.                 "Working Time": {
  90.                     "avg": 40426688,
  91.                     "max": 161471551,
  92.                     "onlineStatus": "Working Time",
  93.                     "sum": 2.0213344E+8
  94.                 },
  95.                 "On Break": {
  96.                     "avg": "--",
  97.                     "peragent_avg": "--",
  98.                     "max": "--",
  99.                     "onlineStatus": "On Break",
  100.                     "sum": "0",
  101.                     "daily_peragent_avg": "--"
  102.                 },
  103.                 "Busy": {..},
  104.                 "Offline": {..},
  105.                 "Available": {..},
  106.                 "On Call": {..}
  107.             }
  108.         ]
  109.     },
  110.     "code": "200",
  111.     "status": "SUCCESS"
  112. }