8x8 Queue Agent Activity API

openapi: 3.2.0
info:
  title: Work Analytics Queue Agent Activity API
  version: 8-x-8-Latest
  description: "The Work Analytics API provides metrics related to call queues activity as well as agent activity on queues.\n### **Time filtering**\nIf no time filtering is provided, the returned metrics reflect the agent activity in the last 24 hours. \\\nThe reports can be generated for a specific date range, specified using 'startDate' and 'endDate' parameters, in ISO 8601 format. If a specific intra day time range is desired, the 'intraDayStart' and 'intraDayEnd', in ISO 8601 format, must be used.\n### **Examples:**\n\n  - To obtain a full day report from 1st of May to 5th of May, in UTC, use startDate: 2023-05-01T00:00:00Z and endDate: 2023-05-05T00:00:00Z. \n  - To obtain a report from 1st of May to 5th of May, in a specific time zone, starting from 8 AM to 6 PM, use startDate: 2023-05-01T00:00:00-0700 and endDate: 2023-05-05T00:00:00-07000, intraDayStart: 08:00:00-0700, intraDayEnd: 18:00:00-0700."
servers:
- url: https://api.8x8.com/analytics/work/
security:
- 8x8-apikey: []
  bearerAuth: []
tags:
- name: Queue Agent Activity
paths:
  /v2/pbxes/{pbxId}/queue-agent-activity:
    get:
      tags:
      - Queue Agent Activity
      summary: Get Agent Activity Metrics per Queues
      description: This endpoint returns the agent activity metrics for the selected pbx, grouped by queue and agent. The response can be further filtered by a list of queues, sites, agents, user or queue statuses. If no date range is provided, the metrics reflect the agent activity in the last 24 hours.
      operationId: get-agent-queue-activity
      parameters:
      - name: pbxId
        in: path
        description: Id of the PBX.
        required: true
        schema:
          type: string
      - name: siteIds
        in: query
        description: Site ids filtering. Multiple values can be passed separated by comma. If not passed, all sites data for the given pbx will be returned.
        required: false
        schema:
          type: string
        examples:
          Single value:
            description: single valued site id filter
            value: JMwyX0BUTRC9uAnuAz8wfg
          Multiple values:
            description: multivalued site id filter
            value: JMwyX0BUTRC9uAnuAz8wfg,JMwyX0BUTRC9uAnuAz8wfg
      - name: queueIds
        in: query
        description: Call Queue ids filtering. Multiple values can be passed separated by comma. If not passed, all queues data for the given pbx will be returned.
        required: false
        schema:
          type: string
      - name: userIds
        in: query
        description: User ids filtering. Multiple values can be passed separated by comma.
        required: false
        schema:
          type: string
      - name: userStatuses
        in: query
        description: User statuses filtering. Multiple values can be passed separated by comma.
        required: false
        schema:
          type: string
          enum:
          - AVAILABLE
          - BUSY
          - DND
          - AWAY
          - AUTO_AWAY
          - OFFLINE
          - ON_CALL
          - INVISIBLE
      - name: queueStatuses
        in: query
        description: Queue statuses filtering. Multiple values can be passed separated by comma.
        required: false
        schema:
          type: string
          enum:
          - AVAILABLE_IDLE
          - HANDLING
          - ALERTING
          - PAUSE
          - WRAP_UP
          - BUSY_OTHER
          - DND
          - LOGGED_OUT
      - name: startDate
        in: query
        description: Report start date in ISO 8601 standard. If startDate is entered, endDate is required as well.
        required: false
        schema:
          type: string
        examples:
          Start date in U.S. Pacific Time time zone:
            description: 2023-06-14 start date in U.S. Pacific Time time zone
            value: 2023-06-14T00:00:00-0700
          Start date in UTC:
            description: 2023-06-14 start date in UTC
            value: '2023-06-14T00:00:00Z'
      - name: endDate
        in: query
        description: Report end date in ISO 8601 standard. If endDate is entered, startDate is required as well.
        required: false
        schema:
          type: string
        examples:
          End date in U.S. Pacific Time time zone:
            description: 2023-06-15 end date in U.S. Pacific Time time zone
            value: 2023-06-15T00:00:00-0700
          End date in UTC:
            description: 2023-06-15 end date in UTC
            value: '2023-06-15T00:00:00Z'
      - name: intraDayStart
        in: query
        description: Report intra day start time (up to seconds) in ISO 8601 standard. If intraDayStart is entered, intraDayEnd is required as well. Report intraDayStart/intraDayEnd parameters should be passed only when report startDate/endDate are passed as well.
        required: false
        schema:
          type: string
        examples:
          intra day start time in U.S. Pacific Time time zone:
            description: 8 AM in U.S. Pacific Time time zone
            value: 08:00:00-0700
          intra day start time in UTC:
            description: 8 AM in UTC
            value: 08:00:00Z
      - name: intraDayEnd
        in: query
        description: Report intra day end time (up to seconds) in ISO 8601 standard. If intraDayEnd is entered, intraDayStart is required as well. Report intraDayStart/intraDayEnd parameters should be passed only when report startDate/endDate are passed as well.
        required: false
        schema:
          type: string
        examples:
          intra day end time in U.S. Pacific Time time zone:
            description: 6 PM in U.S. Pacific Time time zone
            value: 18:00:00-0700
          intra day end time in UTC:
            description: 6 PM in UTC
            value: 18:00:00Z
      - name: metrics
        in: query
        description: 'Expected metrics in response. Multiple values can be passed separated by comma.

          **Values allowed and their description**

          | Name                                  | Description                                                                                                                                     |

          |---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|

          | missedInteractions                    | The number of interactions that were missed by the user.                                                                                        |

          | rejectedInteractions                  | The number of interactions that were rejected by the user.                                                                                      |

          | ongoingTalkingInteractions            | The number of interactions that are currently in the talking phase.                                                                             |

          | rejectedInteractionsPercentage        | The percentage of interactions that were rejected by the user.                                                                                  |

          | averageOnHoldInteractionsTime         | The average time that interactions were on hold.                                                                                                |

          | ongoingOnHoldInteractions             | The number of interactions that are currently on hold.                                                                                          |

          | userStatusTime                        | The total time the user has been in their current status.                                                                                       |

          | missedInteractionsPercentage          | The percentage of interactions that were missed by the user.                                                                                    |

          | ongoingWrapUpInteractionsTime         | The time spent on interactions that are currently in the wrap-up phase.                                                                         |

          | ongoingAvgTalkingInteractionsTime     | The average time spent on interactions that are currently in the talking phase.                                                                 |

          | enteredInteractions                   | The number of interactions that the user has entered into.                                                                                      |

          | ongoingTotalHandlingInteractionsTime  | The total time spent on interactions that are currently being handled.                                                                          |

          | acceptedInteractionsPercentage        | The percentage of interactions that were accepted by the user.                                                                                  |

          | averageTalkingInteractionsTime        | The average time spent on interactions during the talking phase.                                                                                |

          | totalInteractionTime                  | The total time spent on all interactions.                                                                                                       |

          | ongoingHandlingInteractions           | The number of interactions that are currently being handled by the user.                                                                        |

          | queueStatusTime                       | The total time the user has been in the queue status.                                                                                           |

          | ongoingWrapUpInteractions             | The number of interactions that are currently in the wrap-up phase.                                                                             |

          | ongoingAvgHandlingInteractionsTime    | The average time spent on interactions that are currently being handled.                                                                        |

          | ongoingOnHoldInteractionsTime         | The time spent on interactions that are currently on hold.                                                                                      |

          | ongoingTalkingInteractionsTime        | The time spent on interactions that are currently in the talking phase.                                                                         |

          | averageWrapUpTime                     | The average time spent on interactions during the wrap-up phase.                                                                                |

          | acceptedInteractions                  | The number of interactions that were accepted by the user.                                                                                      |

          | agentAverageTimeToAnswer              | The average time the agent takes to answer interactions in the queue after alerting begins (alerting duration). Returns null when the agent answered no interactions in the selected period. |

          '
        required: false
        schema:
          type: string
      - name: includeSummary
        in: query
        description: If true, the response will contain the summary of agent activity metrics for each queue, otherwise not.
        required: false
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueAgentActivityResponse'
              examples:
                All Metrics:
                  description: example request
                  value:
                    queuesAgentActivity:
                    - pbx: testPbx
                      site: Test Site
                      queueExtension: '6509967'
                      queueId: X10000
                      queueName: Timoth
                      autoLogin: false
                      queueAgentActivity:
                      - userId: user_1
                        agentExtension: '2062112'
                        agentName: John Doe
                        queueStatus: HANDLING
                        userStatus: ON_CALL
                        overflowAgent: false
                        interaction:
                          caller: Caller
                          address: CallerPhone
                        metrics:
                          ongoingHandlingInteractions: 1
                          acceptedInteractions: 0
                          ongoingOnHoldInteractionsTime: 0
                          ongoingTalkingInteractions: 1
                          ongoingWrapUpInteractionsTime: 0
                          rejectedInteractions: 0
                          userStatusTime: 2579000
                          averageWrapUpTime: 0
                          ongoingWrapUpInteractions: 0
                          enteredInteractions: 0
                          ongoingTalkingInteractionsTime: 2594778
                          ongoingHandlingInteractionsTime: 2579000
                          totalInteractionTime: 0
                          ongoingOnHoldInteractions: 0
                          queueStatusTime: 2579000
                      - userId: user_2
                        agentExtension: '5368894'
                        agentName: Jane Doe
                        queueStatus: ALERTING
                        userStatus: AVAILABLE
                        overflowAgent: false
                        interaction:
                          caller: Another Caller
                          address: AnotherCallerPhone
                        metrics:
                          ongoingHandlingInteractions: 1
                          acceptedInteractions: 0
                          ongoingOnHoldInteractionsTime: 2599778
                          ongoingTalkingInteractions: 0
                          ongoingWrapUpInteractionsTime: 0
                          rejectedInteractions: 0
                          userStatusTime: 2615000
                          averageWrapUpTime: 0
                          ongoingWrapUpInteractions: 0
                          enteredInteractions: 0
                          ongoingTalkingInteractionsTime: 0
                          ongoingHandlingInteractionsTime: 2615000
                          totalInteractionTime: 0
                          ongoingOnHoldInteractions: 1
                          queueStatusTime: 2615000
                      metricsSummary:
                        ongoingHandlingInteractions: 2
                        acceptedInteractions: 0
                        ongoingOnHoldInteractionsTime: 2599778
                        ongoingTalkingInteractions: 1
                        ongoingWrapUpInteractionsTime: 0
                        rejectedInteractions: 0
                        averageWrapUpTime: 0
                        ongoingWrapUpInteractions: 0
                        enteredInteractions: 0
                        ongoingTalkingInteractionsTime: 2594778
                        ongoingHandlingInteractionsTime: 5195000
                        totalInteractionTime: 0
                        ongoingOnHoldInteractions: 1
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Invalid metrics passed:
                  description: Invalid metrics passed
                  value:
                    timestamp: 2023-01-05T12:04:59.100+0000
                    status: 400
                    messages:
                    - Invalid Metrics Passed [random,notSupported].
                    path: /analytics/work/v2/pbxes/PBX_ID_VALUE/queue-agent-activity
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                User Not Authorized:
                  description: User Not Authorized
                  value:
                    timestamp: 2023-01-05T12:04:59.100+0000
                    status: 403
                    messages:
                    - user [user_name] does not have access to pbxId [PBX_ID] to make this request.
                    path: /analytics/work/v2/pbxes/PBX_ID_VALUE/queue-agent-activity
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Interaction:
      type: object
      properties:
        caller:
          type: string
        address:
          type: string
    QueueActivity:
      type: object
      properties:
        pbx:
          type: string
          description: The PBX (Private Branch Exchange) identifier associated with the queue.
        site:
          type: string
          description: The site or location where the queue is based.
        queueId:
          type: string
          description: Unique identifier for the queue.
        queueExtension:
          type: string
          description: The phone extension associated with the queue.
        queueName:
          type: string
          description: The name of the queue.
        autoLogin:
          type: boolean
          description: Indicates if agents are automatically logged into the queue.
        queueAgentActivity:
          type: array
          items:
            $ref: '#/components/schemas/QueueAgentActivity'
          description: A list of agent activities within the queue.
        summary:
          type: object
          additionalProperties:
            type: object
          description: A summary of various metrics and statistics related to the queue's performance.
    QueueAgentActivity:
      type: object
      properties:
        userId:
          type: string
          description: Unique identifier for the agent.
        agentExtension:
          type: string
          description: The phone extension associated with the agent.
        agentName:
          type: string
          description: The name of the agent.
        queueStatus:
          type: string
          description: The current status of the agent within the queue (e.g., AVAILABLE_IDLE, BUSY).
        userStatus:
          type: string
          description: The overall status of the agent (e.g., OFFLINE, AVAILABLE).
        overflowAgent:
          type: boolean
          description: Indicates if the agent is an overflow agent for the queue.
        interaction:
          $ref: '#/components/schemas/Interaction'
        metrics:
          type: object
          additionalProperties:
            type: object
          description: A collection of various metrics related to the agent's performance within the queue.
    ErrorResponse:
      type: object
      description: Error response
      properties:
        timestamp:
          type: string
          description: Timestamp of the error
          format: date-time
          example: 2023-01-05T12:04:59.100+0000
        status:
          type: integer
          description: HTTP status of the response
          format: int32
        messages:
          type: array
          description: List of business service error messages
          items:
            type: string
        path:
          type: string
          description: Request path
    QueueAgentActivityResponse:
      type: object
      properties:
        queuesAgentActivity:
          type: array
          items:
            $ref: '#/components/schemas/QueueActivity'
          description: A list of queue activities, including details of each queue and associated agent activities.
    401ErrorResponse:
      type: object
      description: Error response
      properties:
        error:
          type: string
          description: type of  error
          example: invalid_token
        error_description:
          type: string
          description: Description of the error
          example: 'Access token expired: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.'
  securitySchemes:
    8x8-apikey:
      type: apiKey
      in: header
      name: 8x8-apikey
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-readme:
  explorer-enabled: true
  proxy-enabled: true