Hellou AI Messages API

openapi: 3.2.0
info:
  title: HellouOne Messages 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: Messages
paths:
  /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages:
    parameters:
    - $ref: '#/components/parameters/account_id'
    - $ref: '#/components/parameters/conversation_id'
    get:
      tags:
      - Messages
      operationId: list-all-messages
      summary: Get messages
      description: List all messages of a conversation
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                description: Array of messages
                items:
                  allOf:
                  - $ref: '#/components/schemas/generic_id'
                  - $ref: '#/components/schemas/message'
        '404':
          description: Conversation not found
        '401':
          description: Unauthorized
    post:
      tags:
      - Messages
      operationId: create-a-new-message-in-a-conversation
      summary: Create New Message
      description: Create a new message in the conversation
      security:
      - userApiKey: []
      - agentBotApiKey: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/generic_id'
                - $ref: '#/components/schemas/message'
        '404':
          description: Conversation not found
        '403':
          description: Access denied
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/conversation_message_create'
  /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{message_id}:
    parameters:
    - $ref: '#/components/parameters/account_id'
    - $ref: '#/components/parameters/conversation_id'
    - $ref: '#/components/parameters/message_id'
    delete:
      tags:
      - Messages
      operationId: delete-a-message
      summary: Delete a message
      description: Delete a message and it's attachments from the conversation.
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
        '404':
          description: The message or conversation does not exist in the account
  /api/v1/accounts/{account_id}/assistant/usage:
    parameters:
    - $ref: '#/components/parameters/account_id'
    get:
      tags:
      - Messages
      operationId: getLiaUsage
      summary: Get LIA allowance and effort options
      description: 'Administrators only. Returns this account''s LIA token usage over two

        windows: a five-hour window that opens with the first message sent while

        none is open, and the current week (Monday 00:00 UTC). A new turn is refused

        once either window''s limit is spent. Each figure sums the four metered

        buckets of this week''s or this window''s replies; cached input can count in

        more than one bucket, and discarded escalation calls may be omitted. These

        are recorded allowance counters, not total provider consumption, unique

        processed tokens, context-window fullness or a price estimate. Also returns

        the accepted effort levels. Private threads are not returned. Requires

        admin_ai_assistant.'
      x-required-feature: admin_ai_assistant
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - tokens
                - warning_ratio
                - configuration
                properties:
                  warning_ratio:
                    type: number
                    minimum: 0
                    maximum: 1
                  tokens:
                    type: object
                    additionalProperties: false
                    required:
                    - five_hour
                    - weekly
                    - breakdown
                    properties:
                      five_hour:
                        description: Null starts_at and resets_at mean no window is open; the next message opens one.
                        type: object
                        additionalProperties: false
                        required:
                        - used
                        - limit
                        - remaining
                        - starts_at
                        - resets_at
                        properties:
                          used:
                            type: integer
                            minimum: 0
                          limit:
                            type: integer
                            minimum: 0
                          remaining:
                            type: integer
                            minimum: 0
                          starts_at:
                            type:
                            - string
                            - 'null'
                            format: date-time
                          resets_at:
                            type:
                            - string
                            - 'null'
                            format: date-time
                      weekly:
                        type: object
                        additionalProperties: false
                        required:
                        - used
                        - limit
                        - remaining
                        - starts_at
                        - resets_at
                        properties:
                          used:
                            type: integer
                            minimum: 0
                          limit:
                            type: integer
                            minimum: 0
                          remaining:
                            type: integer
                            minimum: 0
                          starts_at:
                            type: string
                            format: date-time
                          resets_at:
                            type: string
                            format: date-time
                      breakdown:
                        description: This week's metered tokens by bucket.
                        type: object
                        additionalProperties: false
                        required:
                        - input_tokens
                        - output_tokens
                        - cache_read_input_tokens
                        - cache_creation_input_tokens
                        properties:
                          input_tokens:
                            type: integer
                            minimum: 0
                          output_tokens:
                            type: integer
                            minimum: 0
                          cache_read_input_tokens:
                            type: integer
                            minimum: 0
                          cache_creation_input_tokens:
                            type: integer
                            minimum: 0
                  configuration:
                    type: object
                    additionalProperties: false
                    required:
                    - default_effort
                    - supported_efforts
                    properties:
                      default_effort:
                        description: The level the composer starts on; null when no effort control is offered.
                        type:
                        - string
                        - 'null'
                        enum:
                        - low
                        - medium
                        - high
                        - null
                      supported_efforts:
                        type: array
                        uniqueItems: true
                        items:
                          type: string
                          enum:
                          - low
                          - medium
                          - high
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
  /api/v1/accounts/{account_id}/assistant/threads/{thread_id}/messages:
    parameters:
    - $ref: '#/components/parameters/account_id'
    - name: thread_id
      in: path
      required: true
      schema:
        type: integer
    post:
      tags:
      - Messages
      operationId: createLiaMessage
      summary: Start a LIA turn
      description: 'Administrators only. Starts a turn in a private thread owned by the caller.

        Effort is optional; omit it to preserve each routed model''s slot default.

        An explicit low, medium or high is accepted while getLiaUsage offers effort,

        and each model call is sent the nearest level that model takes. Invalid

        effort is refused before a turn starts.

        Only the requested override is persisted for retries and approval resumes;

        model selection and escalation remain governed by the routing planner.

        A proposed change still requires the administrator''s separate approval.

        Requires admin_ai_assistant. This model-invoking operation is never exposed

        through the MCP gateway, to prevent recursive assistant turns and spend.'
      x-required-feature: admin_ai_assistant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - content
              properties:
                content:
                  type: string
                  minLength: 1
                  maxLength: 4000
                effort:
                  type: string
                  enum:
                  - low
                  - medium
                  - high
      responses:
        '202':
          description: Turn accepted
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - message
                - turn_id
                properties:
                  turn_id:
                    type: string
                  message:
                    type: object
                    additionalProperties: false
                    required:
                    - id
                    - thread_id
                    - role
                    - text
                    - blocks
                    - turn_id
                    - created_at
                    properties:
                      id:
                        type: integer
                      thread_id:
                        type: integer
                      role:
                        type: string
                        enum:
                        - user
                        - assistant
                      text:
                        type: string
                      turn_id:
                        type: string
                      created_at:
                        type: string
                        format: date-time
                      blocks:
                        type: array
                        items:
                          oneOf:
                          - type: object
                            additionalProperties: false
                            required:
                            - type
                            - text
                            properties:
                              type:
                                type: string
                                enum:
                                - text
                              text:
                                type: string
                          - type: object
                            additionalProperties: false
                            required:
                            - type
                            - id
                            - name
                            - label
                            - status
                            properties:
                              type:
                                type: string
                                enum:
                                - tool_use
                              id:
                                type: string
                              name:
                                type: string
                              label:
                                type: string
                              status:
                                type: string
                                enum:
                                - running
                                - done
                                - error
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          description: Thread not found or not owned by the caller
        '409':
          description: A turn is running or a change awaits approval
        '422':
          description: Invalid message or unsupported effort
        '429':
          description: The account spent its five-hour or weekly token limit
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - limit
                - resets_at
                properties:
                  error:
                    type: string
                  limit:
                    type: string
                    enum:
                    - five_hour
                    - weekly
                  resets_at:
                    type: string
                    format: date-time
  /api/v1/accounts/{account_id}/assistant/threads/{thread_id}/stop:
    parameters:
    - $ref: '#/components/parameters/account_id'
    - name: thread_id
      in: path
      required: true
      schema:
        type: integer
    post:
      tags:
      - Messages
      operationId: stopLiaTurn
      summary: Stop the running LIA turn
      description: 'Administrators only. Asks the turn running in a private thread owned by the

        caller to stop. The turn ends at its next check, usually within a second:

        a reply being written is dropped unsaved, and tool calls already running

        finish first. The thread then reports idle like any finished turn, ready for

        the next message. Requires admin_ai_assistant.'
      x-required-feature: admin_ai_assistant
      responses:
        '202':
          description: Stop requested
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - turn_id
                properties:
                  turn_id:
                    type: string
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          description: Thread not found or not owned by the caller
        '409':
          description: No turn is running in this thread
components:
  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'
  schemas:
    generic_id:
      type: object
      properties:
        id:
          type: number
    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
    message:
      type: object
      properties:
        content:
          type: string
          description: The text content of the message
        content_type:
          type: string
          enum:
          - text
          - input_select
          - cards
          - form
          description: The type of the template message
        content_attributes:
          type: object
          description: The content attributes for each content_type
        message_type:
          type: string
          enum:
          - incoming
          - outgoing
          - activity
          - template
          description: The type of the message
        created_at:
          type: integer
          description: The time at which message was created
        private:
          type: boolean
          description: The flags which shows whether the message is private or not
        attachment:
          type: object
          description: The file object attached to the image
        sender:
          type: object
          description: User/Agent/AgentBot object
        conversation_id:
          type: number
          description: ID of the conversation
    conversation_message_create:
      type: object
      required:
      - content
      properties:
        content:
          type: string
          description: The content of the message
        message_type:
          type: string
          enum:
          - outgoing
          - incoming
        private:
          type: boolean
          description: Flag to identify if it is a private note
        content_type:
          type: string
          enum:
          - text
          - input_email
          - cards
          - input_select
          - form
          - article
          example: cards
          description: if you want to create custom message types
        content_attributes:
          type: object
          description: attributes based on your content type
        template_params:
          type: object
          description: 'Sends an approved WhatsApp template instead of a free-form message (WhatsApp

            inboxes only). This is how to reach a contact outside WhatsApp''s 24-hour

            customer service window. `content` is still stored as the message text the

            agents see. The params are stored on the message under

            `additional_attributes.template_params`. See **List message templates** for

            the names and languages available on an inbox.

            '
          properties:
            name:
              type: string
              description: Name of the template
              example: sample_issue_resolution
            language:
              type: string
              description: Language code of the template translation to send
              example: en_US
            namespace:
              type: string
              description: Template namespace. Only needed for legacy (non-Cloud API) WhatsApp providers.
            category:
              type: string
              description: Category of the template. Informational; not used when sending.
              example: UTILITY
            processed_params:
              type: object
              description: 'Values for the template''s body placeholders, by placeholder name: numeric keys

                (`"1"`) fill positional `{{1}}` placeholders, other keys fill named

                placeholders such as `{{customer_name}}`. Only body text placeholders are

                supported here.

                '
              additionalProperties:
                type: string
              example:
                '1': HellouOne
  parameters:
    account_id:
      in: path
      name: account_id
      required: true
      description: The numeric ID of the account
      schema:
        type: integer
    message_id:
      in: path
      name: message_id
      required: true
      description: The numeric ID of the message
      schema:
        type: integer
    conversation_id:
      in: path
      name: conversation_id
      required: true
      description: The numeric ID of the conversation
      schema:
        type: integer
  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