openapi: 3.2.0
info:
  title: Inbox 2.0 API Reference Real Time Metrics Rest API
  description: Inbox 2.0 API Reference
  version: v1
  x-logo:
    url: static/hootsuite-logo.png
  contact:
    email: dev.support@hootsuite.com
  license:
    name: Hootsuite Developer Terms and API License Agreement
    url: https://hootsuite.com/legal/dev-api-terms
servers:
- url: https://platform.hootsuite.com
  description: Inbox 2.0 production server
security:
- bearer-token: []
tags:
- name: real_time_metrics_rest_api
  x-displayName: REST API
  description: 'When calling the Real-time Metrics API, the client needs to be authenticated.


    The [REST API authentication](#tag/rest-api-authentication) section contains more details on how to authenticate your client.

    '
paths:
  /inbox/v1/reporting/metrics/inbound-message-volume:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Inbound message volume
      operationId: metricsInboundMessageVolume
      description: 'A count of inbound messages based on applied filters.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TotalMessagesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/NumberMetricResponse'
                - $ref: '#/components/schemas/TimeSeriesMetricResponse'
              examples:
                SingleValue:
                  value: 6
                GroupByInterval:
                  value:
                  - timestamp: '2022-03-25T00:00:00.000Z'
                    value: 2
                  - timestamp: '2022-03-26T00:00:00.000Z'
                    value: 4
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
  /inbox/v1/reporting/metrics/outbound-message-volume:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Outbound message volume
      operationId: metricsOutboundMessageVolume
      description: 'A count of outbound messages based on applied filters.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TotalMessagesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/NumberMetricResponse'
                - $ref: '#/components/schemas/TimeSeriesMetricResponse'
              examples:
                SingleValue:
                  value: 6
                GroupByInterval:
                  value:
                  - timestamp: '2022-03-25T00:00:00.000Z'
                    value: 2
                  - timestamp: '2022-03-26T00:00:00.000Z'
                    value: 4
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
  /inbox/v1/reporting/metrics/first-response-time:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Average first response time
      operationId: metricsAverageFirstResponseTime
      description: 'The average time in seconds to the first response to an inbound message.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseTimeRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/NumberMetricResponse'
                - $ref: '#/components/schemas/GroupedMetricResponse'
                - $ref: '#/components/schemas/TimeSeriesMetricResponse'
              examples:
                singleValue:
                  value: 6
                groupByTeam:
                  value:
                    c3144df7-8a04-4b20-b60a-ccfe97723780:
                      value: 4
                    3b48a76e-4289-44b8-ac15-c8b60d21f158:
                      value: 2
                groupByDay:
                  value:
                  - timestamp: '2022-03-25T00:00:00.000Z'
                    value: 2
                  - timestamp: '2022-03-26T00:00:00.000Z'
                    value: 4
                groupByDayAndTeam:
                  value:
                  - timestamp: '2022-03-25T00:00:00.000Z'
                    value:
                      c3144df7-8a04-4b20-b60a-ccfe97723780:
                        value: 4
                      3b48a76e-4289-44b8-ac15-c8b60d21f158:
                        value: 2
                  - timestamp: '2022-03-26T00:00:00.000Z'
                    value: null
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
  /inbox/v1/reporting/metrics/conversation-response-time:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Average conversation response time
      operationId: metricsAverageConversationResponseTime
      description: 'The average time in seconds for a response to an inbound message except the first response.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseTimeRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/NumberMetricResponse'
                - $ref: '#/components/schemas/GroupedMetricResponse'
                - $ref: '#/components/schemas/TimeSeriesMetricResponse'
              examples:
                singleValue:
                  value: 6
                groupByTeam:
                  value:
                    c3144df7-8a04-4b20-b60a-ccfe97723780:
                      value: 4
                    3b48a76e-4289-44b8-ac15-c8b60d21f158:
                      value: 2
                groupByDay:
                  value:
                  - timestamp: '2022-03-25T00:00:00.000Z'
                    value: 2
                  - timestamp: '2022-03-26T00:00:00.000Z'
                    value: 4
                groupByDayAndTeam:
                  value:
                  - timestamp: '2022-03-25T00:00:00.000Z'
                    value:
                      c3144df7-8a04-4b20-b60a-ccfe97723780:
                        value: 4
                      3b48a76e-4289-44b8-ac15-c8b60d21f158:
                        value: 2
                  - timestamp: '2022-03-26T00:00:00.000Z'
                    value: null
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
  /inbox/v1/reporting/metrics/resolved-with-one-reply:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Resolved with reply
      operationId: metricsResolvedWithReply
      description: 'The number of messages that have been resolved with at least one reply.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TotalResolvedConversationsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/NumberMetricResponse'
                - $ref: '#/components/schemas/GroupedMetricResponse'
              examples:
                singleValue:
                  value: 6
                groupByTeam:
                  value:
                    c3144df7-8a04-4b20-b60a-ccfe97723780:
                      value: 4
                    3b48a76e-4289-44b8-ac15-c8b60d21f158:
                      value: 2
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
  /inbox/v1/reporting/metrics/handle-time:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Average handle time
      operationId: metricsAverageHandleTime
      description: 'The average time in seconds that a conversation is handled by an agent, specifically the difference between timestamps

        of conversation open and conversation pend/resolve. For Average Handle Time to be calculated, there must be an outbound

        between open and pend/resolve event.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HandleTimeRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberMetricResponse'
              examples:
                singleValue:
                  value: 6
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
  /inbox/v1/user-presence/metrics/agent-availability:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Agent availability
      operationId: metricsAgentAvailability
      description: 'The number of agents available or away. You can filter by teams.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentAvailabilityRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberMetricResponse'
              example:
                value: 30
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
  /inbox/v1/queue/metrics/contacts-waiting:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Contacts waiting in queue
      operationId: metricsContactsWaitingInQueue
      description: 'The number of contacts waiting in the queue for a response.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/NumberMetricResponse'
                - $ref: '#/components/schemas/GroupedMetricResponse'
              examples:
                singleValue:
                  value: 6
                groupByChannel:
                  value:
                    c3144df7-8a04-4b20-b60a-ccfe97723780:
                      value: 4
                    3b48a76e-4289-44b8-ac15-c8b60d21f158:
                      value: 2
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
  /inbox/v1/queue/metrics/longest-wait-time:
    post:
      tags:
      - real_time_metrics_rest_api
      summary: Longest wait time in queue
      operationId: metricsLongestWaitTimeInQueue
      description: 'The current longest time in seconds that a contact is waiting for a response. If no mediumId filter is provided, the

        messages sent in any connected mediums will be included.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/NumberMetricResponse'
                - $ref: '#/components/schemas/GroupedMetricResponse'
              examples:
                singleValue:
                  value: 131
                groupByChannel:
                  value:
                    c3144df7-8a04-4b20-b60a-ccfe97723780:
                      value: 131
                    3b48a76e-4289-44b8-ac15-c8b60d21f158:
                      value: 155
        '401':
          description: 'Unauthorized: when using an invalid or expired access token.

            '
components:
  schemas:
    GroupByInterval:
      type: string
      enum:
      - MINUTE
      - HOUR
      - DAY
      - MONTH
      - YEAR
      - HOUR_BY_DAY
      description: 'An interval to group results by. No more than 60 intervals can be requested per request. For example, when selecting `minute`, the requested time range cannot be longer than 1 hour

        '
    From:
      type: string
      description: 'An `ISO-8601` date time marking the inclusive start of the result. Must be URL encoded. The `from` filter can be a maximum of 14 days in the past.

        '
    ChannelId:
      type: string
      description: 'Filter by channel identifier (to obtain a list of your channel IDs, contact a Inbox 2.0 representative)

        '
    TotalResolvedConversationsRequest:
      type: object
      required:
      - from
      properties:
        from:
          $ref: '#/components/schemas/From'
        to:
          $ref: '#/components/schemas/To'
        mediumIds:
          type: array
          items:
            $ref: '#/components/schemas/MediumId'
        channelIds:
          type: array
          items:
            $ref: '#/components/schemas/ChannelId'
        teamIds:
          type: array
          items:
            $ref: '#/components/schemas/TeamId'
        groupBy:
          type: string
          enum:
          - TEAM
    Timezone:
      type: string
      description: 'The `timezone` to be used in conjunction with`groupByInterval`, e.g. America/Los_Angeles. Must be URL encoded. If no `timezone` is provided, the default ''UTC'' timezone is used

        '
    AgentAvailabilityRequest:
      type: object
      properties:
        teamIds:
          type: array
          items:
            type: string
          description: 'Filter by teams

            '
        userPresenceStatus:
          type: string
          enum:
          - AWAY
          - AVAILABLE
    TotalMessagesRequest:
      type: object
      required:
      - from
      properties:
        from:
          $ref: '#/components/schemas/From'
        to:
          $ref: '#/components/schemas/To'
        timezone:
          $ref: '#/components/schemas/Timezone'
        mediumIds:
          type: array
          items:
            $ref: '#/components/schemas/MediumId'
        channelIds:
          type: array
          items:
            $ref: '#/components/schemas/ChannelId'
        groupByInterval:
          $ref: '#/components/schemas/GroupByInterval'
    MetricRequest:
      type: object
      required:
      - status
      properties:
        channelIds:
          type: array
          items:
            type: string
        teamIds:
          type: array
          items:
            type: string
        mediumId:
          $ref: '#/components/schemas/MediumId'
        groupBy:
          type: string
          enum:
          - CHANNEL
          - OWNER
          - TOPIC
          - TEAM
        status:
          type: string
          enum:
          - NEW
          - PENDING
    UserId:
      type: string
      description: 'Filter by user identifier

        '
    MediumId:
      type: string
      enum:
      - fb
      - twit
      - instagram
      - rtm
      - whatsapp
      - linkedin
      description: 'Filter by medium identifier

        '
    ResponseTimeRequest:
      type: object
      required:
      - from
      properties:
        from:
          $ref: '#/components/schemas/From'
        to:
          $ref: '#/components/schemas/To'
        timezone:
          $ref: '#/components/schemas/Timezone'
        mediumIds:
          type: array
          items:
            $ref: '#/components/schemas/MediumId'
        channelIds:
          type: array
          items:
            $ref: '#/components/schemas/ChannelId'
        teamIds:
          type: array
          items:
            $ref: '#/components/schemas/TeamId'
        groupByInterval:
          $ref: '#/components/schemas/GroupByInterval'
        groupBy:
          type: string
          enum:
          - TEAM
    TeamId:
      type: string
      description: 'Filter by team identifier

        '
    To:
      type: string
      description: 'An `ISO-8601` date time marking the exclusive end of the result. Must be URL encoded

        '
    TimeSeriesMetricResponse:
      type: object
      properties:
        value:
          type: array
          items:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/TimeSeriesDataPoint'
    TimeSeriesDataPoint:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        value:
          type: object
          oneOf:
          - $ref: '#/components/schemas/GroupedMetricResponse'
          - $ref: '#/components/schemas/NumberMetricResponse'
    HandleTimeRequest:
      type: object
      required:
      - from
      properties:
        from:
          $ref: '#/components/schemas/From'
        to:
          $ref: '#/components/schemas/To'
        mediumIds:
          type: array
          items:
            $ref: '#/components/schemas/MediumId'
        channelIds:
          type: array
          items:
            $ref: '#/components/schemas/ChannelId'
        userIds:
          type: array
          items:
            $ref: '#/components/schemas/UserId'
        handleTimeTypes:
          type: array
          items:
            type: string
            enum:
            - HANDLE_TIME
            - NO_REPLY_TIME
            - CHERRY_PICKING
    GroupedMetricResponse:
      type: object
      properties:
        value:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/NumberMetricResponse'
    NumberMetricResponse:
      type: object
      properties:
        value:
          type: integer
  securitySchemes:
    bearer-token:
      type: http
      scheme: bearer
    basic-auth:
      type: http
      scheme: basic
    Oauth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: TO_BE_CONFIGURED_IN_INBOX_2_0
          scopes:
            some_scope: TO_BE_CONFIGURED_IN_INBOX_2_0
    SharedSecret:
      type: apiKey
      in: header
      name: X-Hootsuite-Signature
x-provenance:
  generated: '2026-08-13'
  method: searched
  source: https://apidocs.hootsuite.com/docs/api/inbox/openapi/openapi.yaml
  note: Verbatim first-party OpenAPI 3.1 for the Hootsuite Inbox 2.0 API (formerly Sparkcentral), linked as service-desc for anchor https://platform.hootsuite.com/inbox/v1/ in Hootsuite's RFC 9727 API catalog at https://www.hootsuite.com/.well-known/api-catalog.
  ownership: servers[] https://platform.hootsuite.com, contact dev.support@hootsuite.com, license "Hootsuite Developer Terms and API License Agreement" - Hootsuite's own contract.
x-tagGroups:
- name: General
  tags:
  - rest-api-authentication
- name: CRM API
  tags:
  - crm_introduction
  - crm_webhooks
  - crm_rest_api
- name: Virtual Agent API
  tags:
  - vai_introduction
  - vai_webhooks
  - vai_rest_api
- name: Real-time metrics API
  tags:
  - real_time_metrics_introduction
  - real_time_metrics_rest_api
- name: User Presence API
  tags:
  - user_presence_introduction
  - user_presence_rest_api
- name: Queue API
  tags:
  - queue_introduction
  - queue_rest_api
- name: Proactive messaging API
  tags:
  - proactive_messaging_introduction
  - proactive_messaging_rest_api
- name: Messenger SDK
  tags:
  - messenger_introduction
  - messenger_web_sdk