Hellou AI Reports API

openapi: 3.2.0
info:
  title: HellouOne Reports API
  version: 1.0.0
  description: 'The HellouOne REST API: everything the dashboard does, available to your

    own systems — CRMs, bots, BI tools and back-office automation.'
  termsOfService: https://hellou.ai/en/legal/terms/
  contact:
    name: HellouOne support
    email: support@hellou.ai
servers:
- url: https://one.hellou.ai
  description: HellouOne cloud
security:
- userApiKey: []
tags:
- name: Reports
paths:
  /api/v2/accounts/{account_id}/reports:
    parameters:
    - $ref: '#/components/parameters/account_id'
    - $ref: '#/components/parameters/report_metric'
    - $ref: '#/components/parameters/report_type'
    - in: query
      name: id
      schema:
        type: string
      description: The Id of specific object in case of agent/inbox/label
    - in: query
      name: since
      schema:
        type: string
      description: The timestamp from where report should start.
    - in: query
      name: until
      schema:
        type: string
      description: The timestamp from where report should stop.
    get:
      tags:
      - Reports
      operationId: list-all-conversation-statistics
      summary: Get Account reports
      description: Get Account reports for a specific type, metric and date range
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                description: Array of date based conversation statistics
                items:
                  type: object
                  properties:
                    value:
                      type: string
                    timestamp:
                      type: number
        '404':
          description: reports not found
        '403':
          description: Access denied
  /api/v2/accounts/{account_id}/reports/summary:
    parameters:
    - $ref: '#/components/parameters/account_id'
    - $ref: '#/components/parameters/report_type'
    - in: query
      name: id
      schema:
        type: string
      description: The Id of specific object in case of agent/inbox/label
    - in: query
      name: since
      schema:
        type: string
      description: The timestamp from where report should start.
    - in: query
      name: until
      schema:
        type: string
      description: The timestamp from where report should stop.
    get:
      tags:
      - Reports
      operationId: list-all-conversation-statistics-summary
      summary: Get Account reports summary
      description: Get Account reports summary for a specific type and date range
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: Object of summary metrics
                $ref: '#/components/schemas/account_summary'
        '404':
          description: reports not found
        '403':
          description: Access denied
  /api/v1/accounts/{account_id}/usage:
    parameters:
    - $ref: '#/components/parameters/account_id'
    get:
      tags:
      - Reports
      operationId: getAccountUsage
      summary: Get the plan usage
      description: 'What the account has used of its plan in the current billing period, against

        what the plan includes: agents, inboxes, conversations, AI agents, AI messages,

        marketing sends and AI phone minutes. A limit the plan does not cap has

        `allowed: null`.


        AI phone minutes are measured to the second and reported as decimal minutes

        rounded to two places. `consumed` is the total, `standard_consumed` and

        `premium_consumed` split it by voice engine. Minutes used beyond those

        included in the plan are billed as overage.


        **Administrators only.**'
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/account_usage'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
  /api/v2/accounts/{account_id}/reports/conversations:
    parameters:
    - $ref: '#/components/parameters/account_id'
    get:
      tags:
      - Reports
      operationId: get-conversation-metrics
      summary: Conversation Metrics
      description: 'Live conversation counts. With `type=account` the response is one object of

        account-wide counts; with `type=agent` it is an array with one entry per agent

        (narrow it to a single agent with `user_id`).'
      parameters:
      - in: query
        name: type
        required: true
        description: Type of report
        schema:
          type: string
          enum:
          - account
          - agent
      - in: query
        name: user_id
        description: The numeric ID of the user (only with `type=agent`)
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  description: Account conversation metrics (`type=account`)
                  properties:
                    open:
                      type: number
                    unattended:
                      type: number
                    unassigned:
                      type: number
                - type: array
                  description: Agent conversation metrics (`type=agent`)
                  items:
                    $ref: '#/components/schemas/agent_conversation_metrics'
        '404':
          description: reports not found
        '403':
          description: Access denied
  /api/v1/accounts/{account_id}/reporting_events:
    parameters:
    - $ref: '#/components/parameters/account_id'
    get:
      tags:
      - Reports
      operationId: listReportingEvents
      summary: List reporting events
      description: 'The raw rows behind the report numbers: first response, reply time, resolution, AI agent and call events.

        Newest first, 25 per page. Without `since` and `until` the last 30 days are returned. `since` and `until`

        filter the moment the event was recorded and take unix seconds or an ISO 8601 date; the range may not exceed

        90 days. An unparseable or inverted range, or an id filter that is not a number (inbox_id, user_id,

        conversation_id), is refused with 422. All time fields in the response are unix seconds.


        `conversation_id` in the response, as in the filter, is the conversation number shown in the dashboard (its

        `display_id`).


        **Administrators only.** Other members get 403.


        **Requires feature:** `reports`'
      x-required-feature: reports
      parameters:
      - $ref: '#/components/parameters/page'
      - in: query
        name: since
        required: false
        schema:
          type: string
        description: Start of the range, unix seconds or ISO 8601. Defaults to 30 days before `until`.
      - in: query
        name: until
        required: false
        schema:
          type: string
        description: End of the range, unix seconds or ISO 8601. Defaults to now. At most 90 days after `since`.
      - in: query
        name: inbox_id
        required: false
        schema:
          type: integer
        description: Only events of this inbox.
      - in: query
        name: user_id
        required: false
        schema:
          type: integer
        description: Only events of this agent.
      - in: query
        name: name
        required: false
        schema:
          type: string
        description: Only events with this name, for example `first_response`.
      - in: query
        name: conversation_id
        required: false
        schema:
          type: integer
        description: Only events of this conversation, by the number shown in the dashboard (`display_id`).
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/reporting_event_list'
        '422':
          $ref: '#/components/responses/unprocessable'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
components:
  parameters:
    report_type:
      in: query
      name: type
      required: true
      description: Type of report
      schema:
        type: string
        enum:
        - account
        - agent
        - inbox
        - label
        - team
    account_id:
      in: path
      name: account_id
      required: true
      description: The numeric ID of the account
      schema:
        type: integer
    report_metric:
      in: query
      name: metric
      required: true
      description: The type of metric. The `mood_*` counts are sentiment events (one per scored burst of customer messages), written only while sentiment runs in `enforce`.
      schema:
        type: string
        enum:
        - conversations_count
        - incoming_messages_count
        - outgoing_messages_count
        - avg_first_response_time
        - avg_resolution_time
        - resolutions_count
        - mood_scored_count
        - mood_negative_count
        - mood_attention_count
    page:
      in: query
      name: page
      required: false
      description: The page parameter
      schema:
        type: integer
        default: 1
  responses:
    unauthorized:
      description: Missing or invalid `api_access_token`, or a bot token on an endpoint bots cannot use.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_message'
    forbidden:
      description: 'Not allowed: the user''s role does not permit it, the feature is not enabled

        for the account (`reason: feature_disabled`), or the account is read-only.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_message'
    unprocessable:
      description: The request was understood but the data is invalid.
      content:
        application/json:
          schema:
            anyOf:
            - $ref: '#/components/schemas/validation_error'
            - $ref: '#/components/schemas/error_message'
  schemas:
    account_usage:
      type: object
      description: The account's plan usage for the current billing period.
      properties:
        id:
          type: integer
          description: The account id.
        plan:
          type:
          - object
          - 'null'
          description: The plan the account is on, or `null` for an account without one.
          properties:
            name:
              type: string
              description: The plan name.
            price_display:
              type:
              - string
              - 'null'
              description: The plan price as shown on the price list.
        trial:
          type:
          - object
          - 'null'
          description: Present only while the account is on a free trial.
          properties:
            active:
              type: boolean
              description: Always `true` when present.
            days_remaining:
              type: integer
              description: Days left of the trial.
            ends_on:
              type: string
              format: date
              description: The last day of the trial.
        period:
          type:
          - object
          - 'null'
          description: The billing period every per-period meter is counted over. `null` without a plan.
          properties:
            starts_on:
              type: string
              format: date
              description: First day of the period.
            ends_on:
              type: string
              format: date
              description: Last day of the period.
        limits:
          type: object
          description: Each meter as `consumed` against `allowed`. When `allowed` is `null` the plan does not cap it.
          properties:
            agents:
              $ref: '#/components/schemas/account_usage_meter'
            inboxes:
              $ref: '#/components/schemas/account_usage_meter'
            conversations:
              allOf:
              - $ref: '#/components/schemas/account_usage_meter'
              - type: object
                properties:
                  grace_allowed:
                    type:
                    - integer
                    - 'null'
                    description: The conversation count at which new conversations are blocked (the allowance plus the plan's grace).
            ai_agents:
              $ref: '#/components/schemas/account_usage_meter'
            ai_messages:
              $ref: '#/components/schemas/account_usage_meter'
            marketing_sends:
              $ref: '#/components/schemas/account_usage_meter'
            ai_voice_minutes:
              type: object
              description: AI phone minutes this period, measured to the second. Minutes beyond `allowed` are billed as overage until the cap.
              properties:
                consumed:
                  type:
                  - number
                  - 'null'
                  description: Total AI phone minutes, standard plus premium, as decimal minutes rounded to two places. `null` without a billing period.
                allowed:
                  type:
                  - integer
                  - 'null'
                  description: The AI phone minutes included in the plan, or `null` when the plan does not cap them.
                standard_consumed:
                  type:
                  - number
                  - 'null'
                  description: Minutes on the standard voice engine, rounded to two places.
                premium_consumed:
                  type:
                  - number
                  - 'null'
                  description: Minutes on the premium voice engine, rounded to two places.
                cap_percent:
                  type:
                  - integer
                  - 'null'
                  description: Percent past the included minutes at which AI calls stop (see the AI phone minutes cap setting). `null` when the account has no included minutes or no cap.
                cap_minutes:
                  type:
                  - number
                  - 'null'
                  description: The minutes at which AI calls stop being taken and are handed to your team, rounded to two places. `null` without included minutes or without a cap.
                cap_reached:
                  type:
                  - boolean
                  - 'null'
                  description: Whether the cap is reached now. `null` when the account has no included minutes.
        warning_ratio:
          type: number
          description: The share of the conversation allowance at which the dashboard starts warning.
    reporting_event:
      type: object
      description: One raw reporting event, the row behind the report numbers (first response, resolution, reply time and so on).
      properties:
        id:
          type: integer
        name:
          type: string
          description: The event name, for example `first_response`, `reply_time` or `conversation_resolved`.
        value:
          type:
          - number
          - 'null'
          description: The measured duration in seconds, when the event has one.
        value_in_business_hours:
          type:
          - number
          - 'null'
          description: The same duration counted only inside business hours, in seconds, when the event has one.
        event_start_time:
          type:
          - integer
          - 'null'
          description: When the measured span started, unix seconds.
        event_end_time:
          type:
          - integer
          - 'null'
          description: When the measured span ended, unix seconds.
        user_id:
          type:
          - integer
          - 'null'
          description: The agent the event belongs to.
        inbox_id:
          type:
          - integer
          - 'null'
          description: The inbox of the conversation.
        conversation_id:
          type:
          - integer
          - 'null'
          description: The conversation number shown in the dashboard (its `display_id`), not the internal row id. `null` when the event has no conversation.
        created_at:
          type: integer
          description: When the event was recorded, unix seconds.
      required:
      - id
      - name
      - created_at
    validation_error:
      type: object
      description: Validation failure for a record.
      properties:
        message:
          type: string
          description: Every validation message, joined with commas.
        attributes:
          type: array
          description: The attributes that failed validation.
          items:
            type: string
      required:
      - message
    reporting_event_list:
      type: object
      properties:
        payload:
          type: array
          description: The events of the page, newest first.
          items:
            $ref: '#/components/schemas/reporting_event'
        meta:
          type: object
          properties:
            count:
              type: integer
              description: Events matching the filters, across all pages.
            current_page:
              type: integer
            per_page:
              type: integer
              description: Always 25.
          required:
          - count
          - current_page
          - per_page
      required:
      - payload
      - meta
    error_message:
      type: object
      description: An error with a human-readable message.
      properties:
        error:
          type: string
          description: What went wrong.
        reason:
          type: string
          description: Machine-readable cause, when there is one (for example `feature_disabled`).
      required:
      - error
    account_usage_meter:
      type: object
      description: One plan meter.
      properties:
        consumed:
          type:
          - integer
          - 'null'
          description: Used so far. `null` when the meter has no billing period yet.
        allowed:
          type:
          - integer
          - 'null'
          description: What the plan includes, or `null` when the plan does not cap it.
    agent_conversation_metrics:
      type: object
      properties:
        id:
          type: number
        name:
          type: string
        email:
          type: string
        thumbnail:
          type: string
        availability:
          type: string
        metric:
          type: object
          properties:
            open:
              type: number
            unattended:
              type: number
    account_summary:
      type: object
      properties:
        avg_first_response_time:
          type: string
        avg_resolution_time:
          type: string
        conversations_count:
          type: number
        incoming_messages_count:
          type: number
        outgoing_messages_count:
          type: number
        resolutions_count:
          type: number
        previous:
          type: object
          properties:
            avg_first_response_time:
              type: string
            avg_resolution_time:
              type: string
            conversations_count:
              type: number
            incoming_messages_count:
              type: number
            outgoing_messages_count:
              type: number
            resolutions_count:
              type: number
  securitySchemes:
    userApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'A user''s access token, from **Profile settings → Access token** in the dashboard.

        Requests act with that user''s role: administrators reach everything in their

        account, agents only what their role and visibility settings allow.

        '
    agentBotApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'An agent bot''s access token, shown to administrators on the bot''s settings page.

        Bot tokens reach a limited set of conversation and message endpoints.

        '
    platformAppApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'A platform app token, issued by the installation operator. Used to provision

        accounts, users, account memberships and agent bots.

        '
    connectorInvokeToken:
      type: http
      scheme: bearer
      description: 'A connector''s invoke token (`hci_…`), sent as `Authorization: Bearer <token>`.

        Each connector install has its own; it is rotated whenever the connector is

        reconnected or disconnected, so a stale copy stops working.

        '
x-tagGroups:
- name: Guides
  tags:
  - Introduction
  - Authentication
  - Errors
  - Pagination
  - Rate limits
  - Webhook events
- name: Webhook payloads
  tags:
  - Event payloads
- name: Platform
  tags:
  - Accounts
  - Account Users
  - AgentBots
  - Users
- name: Application
  tags:
  - Account AgentBots
  - Agents
  - Automation Rule
  - Campaigns
  - Canned Responses
  - Contacts
  - Contact Labels
  - Conversation Assignment
  - Conversation Labels
  - Conversations
  - Custom Attributes
  - Custom Filters
  - Help Center
  - Inboxes
  - Integrations
  - Macros
  - Messages
  - Profile
  - Reports
  - Security Settings
  - Teams
  - Webhooks
- name: Business tools
  tags:
  - AI Classifications
  - Assignment Settings
  - Calls
  - AI Phone Lines
  - Connectors
  - ElevenLabs Integration
  - Facebook Marketing
  - HellouAI Integration
  - Knowledge Base
  - Marketing Consent
  - Plan Upgrades
  - Voice Campaigns
  - WhatsApp Campaigns
  - WhatsApp Flows
  - WhatsApp Templates
- name: Client
  tags:
  - Inbox API
  - Contacts API
  - Conversations API
  - Messages API
- name: Others
  tags:
  - CSAT Survey Page