8x8 Agent Activity API

openapi: 3.2.0
info:
  title: Work Analytics 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: Agent Activity
paths:
  /v2/pbxes/{pbxId}/agent-activity:
    get:
      tags:
      - Agent Activity
      summary: Get Agent Activity Metrics
      description: This endpoint returns the agent activity metrics for the selected pbx, grouped by agent. The response can be further filtered by a list of queues, sites, agents, user statuses. If no date range is provided, the metrics reflect the agent activity in the last 24 hours.
      operationId: get-agent-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: 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.\n\n**Values allowed and their description**\n\n| Metric | Description | \n| -------| ----------- | \n| averageOnHoldInteractionsTime      | The average time an interaction spends on hold. |\n| enteredInteractions                | The number of interactions entered into the queue. |\n| rejectedInteractions               | The number of interactions rejected by the agent. |\n| missedInteractions                 | The number of interactions missed by the agent. |\n| rejectedInteractionsPercentage     | The percentage of interactions rejected by the agent. |\n| acceptedInteractions               | The number of interactions accepted by the agent. |\n| acceptedInteractionsPercentage     | The percentage of interactions accepted by the agent. |\n| ongoingHandlingInteractions        | The number of interactions currently being handled by the agent. |\n| ongoingAvgTalkingInteractionsTime  | The average time of ongoing talking interactions. |\n| ongoingAvgHandlingInteractionsTime | The average time of ongoing handling interactions. |\n| ongoingOnHoldInteractions          | The number of ongoing interactions currently on hold. |\n| ongoingTalkingInteractions         | The number of ongoing talking interactions. |\n| averageWrapUpTime                  | The average time taken to wrap up an interaction. |\n| missedInteractionsPercentage       | The percentage of interactions missed by the agent. |\n| averageTalkingInteractionsTime     | The average time of talking interactions. |\n| totalInteractionTime               | The total time spent on interactions. |\n| ongoingOnHoldInteractionsTime      | The total time of ongoing interactions currently on hold. |\n| ongoingTalkingInteractionsTime     | The total time of ongoing talking interactions. |\n| ongoingTotalHandlingInteractionsTime | The total time of ongoing handling interactions. |\n| userStatusTime                     | The total time the user has spent in their current status. |\n| ongoingWrapUpInteractionsTime      | The total time of ongoing wrap-up interactions. |\n| ongoingWrapUpInteractions          | The number of ongoing wrap-up interactions. |\n| agentAverageTimeToAnswer           | The average time the agent takes to answer interactions after alerting begins (alerting duration). Returns null when the agent answered no interactions in the selected period. |\n"
        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/AgentActivityResponse'
              examples:
                All Metrics:
                  description: metrics param not passed, all call queue metrics will be returned.
                  value:
                    queuesAgentActivity:
                    - pbx: testPbx
                      site: Test Site
                      queueExtension: '6509967'
                      queueName: Timoth
                      autoLogin: false
                      agentActivity:
                      - userId: user_1
                        agentExtension: '2062112'
                        agentName: John Doe
                        loggedInQueues:
                        - '1002'
                        - '2002'
                        userStatus: ON_CALL
                        activityStatus: NEW
                        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
                      - userId: user_2
                        agentExtension: '5368894'
                        agentName: Jane Doe
                        loggedInQueues:
                        - '1002'
                        - '2002'
                        activityStatus: AVAILABLE_IDLE
                        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
                      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/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/agent-activity
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    AgentActivity:
      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.
        userStatus:
          type: string
          description: The overall status of the agent (e.g., OFFLINE, AVAILABLE).
        activityStatus:
          type: string
          description: The current activity status of the agent (e.g., IDLE, BUSY).
        loggedInQueues:
          type: array
          items:
            type: string
          description: A list of queues the agent is logged into.
        interaction:
          $ref: '#/components/schemas/Interaction'
        metrics:
          type: object
          additionalProperties:
            type: object
          description: A collection of various metrics related to the agent's performance.
    Interaction:
      type: object
      properties:
        caller:
          type: string
        address:
          type: string
    AgentActivityResponse:
      type: object
      properties:
        agentActivity:
          type: array
          items:
            $ref: '#/components/schemas/AgentActivity'
          description: A list of agent activities, including details of each agent's status and performance metrics.
        summary:
          type: object
          additionalProperties:
            type: object
          description: A summary of various metrics and statistics related to the agents' activities.
    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
    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