Hellou AI Assignment Settings API

openapi: 3.2.0
info:
  title: HellouOne Assignment Settings 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: Assignment Settings
paths:
  /api/v1/accounts/{account_id}/assignment_settings:
    parameters:
    - $ref: '#/components/parameters/account_id'
    get:
      tags:
      - Assignment Settings
      operationId: getAssignmentSettings
      summary: Get assignment settings
      description: 'Returns how conversations are routed and who agents can see: the agent visibility mode, the

        online-only switch, every inbox and team with its members'' tiers, and the per-inbox overrides

        of team tiers. Members carry their live presence.


        **Administrators only.**'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/assignment_settings'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
    patch:
      tags:
      - Assignment Settings
      operationId: updateAssignmentSettings
      summary: Update assignment settings
      description: 'Changes the agent visibility mode, the online-only switch and any assignment tiers in one atomic

        request. Only the fields sent are changed; within a tier map, only the listed members are changed.


        How auto-assignment uses the tiers: among the eligible agents (only those `online`, when the

        online-only switch is on and anyone is), the lowest tier present wins and its agents share

        conversations round-robin. Inbox auto-assignment uses `inbox_priorities`; assigning a conversation

        to a team uses `team_priorities`, with that inbox''s `inbox_team_priorities` overrides on top.


        **Administrators only.**'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/assignment_settings_update'
      responses:
        '200':
          description: The settings after the update.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/assignment_settings'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          description: An inbox or team ID in a tier map does not exist in this account. Nothing is saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: 'An unknown `visibility_mode`, a tier outside 1–10, or a user who is not a member of the

            inbox or team named. Nothing is saved.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
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'
  parameters:
    account_id:
      in: path
      name: account_id
      required: true
      description: The numeric ID of the account
      schema:
        type: integer
  schemas:
    agent_visibility_mode:
      type: string
      description: 'Which conversations an agent (role `agent`) may see. The modes form a ladder: each rung

        includes everything the one before it allows. Conversations the agent is assigned to or

        participating in are visible at every rung. Administrators always see the whole account.


        - `assigned_only` — only conversations assigned to the agent (or that they participate in).

        - `team` — also conversations assigned to the agent''s teams.

        - `team_unassigned` — also unassigned conversations in inboxes the agent is a member of.

        - `inbox_all` — every conversation in inboxes the agent is a member of.

        - `account_all` — every conversation in the account, in every inbox.


        Accounts that never chose a mode report `team` (or `team_unassigned` if they had enabled

        the older "agents can see unassigned conversations" setting).

        '
      enum:
      - assigned_only
      - team
      - team_unassigned
      - inbox_all
      - account_all
    assignment_settings:
      type: object
      properties:
        visibility_mode:
          $ref: '#/components/schemas/agent_visibility_mode'
        visibility_modes:
          type: array
          description: Every mode, from strictest to widest.
          items:
            $ref: '#/components/schemas/agent_visibility_mode'
        online_only_assignment:
          type: boolean
          description: Whether auto-assignment prefers agents who are online (see the update request).
        courtesy_after_resolve:
          type: boolean
          description: Whether a customer's thank-you after a resolve keeps the conversation resolved (see the update request). On by default.
        courtesy_window_hours:
          type: integer
          minimum: 1
          maximum: 168
          description: How many hours after the resolve a thank-you keeps the conversation resolved.
        courtesy_ai_mode:
          type: string
          enum:
          - 'off'
          - shadow
          - review
          - enforce
          description: Mode of the AI check for longer thank-yous. `review` can only be set by an operator and acts like `shadow`.
        courtesy_ai_available:
          type: boolean
          description: Whether the account's plan includes AI classifications, which the AI check needs.
        decisions_mode:
          type: string
          enum:
          - 'off'
          - shadow
          - review
          - enforce
          description: The platform's ceiling for every AI check; a mode set higher runs at this one.
        inboxes:
          type: array
          description: Every inbox in the account, ordered by name.
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              channel_type:
                type: string
                description: The inbox's channel (for example `Channel::Whatsapp`).
              enable_auto_assignment:
                type:
                - boolean
                - 'null'
                description: Whether the inbox auto-assigns new conversations.
              members:
                type: array
                items:
                  $ref: '#/components/schemas/assignment_member'
            required:
            - id
            - name
            - channel_type
            - enable_auto_assignment
            - members
        inbox_team_priorities:
          type: object
          description: 'Per-inbox overrides of team tiers: `{ "<inbox_id>": { "<team_id>": { "<user_id>": tier } } }`.

            Only configured overrides appear; an empty object when there are none. A missing entry

            means the team''s own tier applies.

            '
          additionalProperties:
            type: object
            additionalProperties:
              type: object
              additionalProperties:
                type: integer
                minimum: 1
                maximum: 10
        teams:
          type: array
          description: Every team in the account, ordered by name.
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              allow_auto_assign:
                type:
                - boolean
                - 'null'
                description: Whether conversations assigned to the team are auto-assigned to one of its members.
              members:
                type: array
                items:
                  $ref: '#/components/schemas/assignment_member'
            required:
            - id
            - name
            - allow_auto_assign
            - members
      required:
      - visibility_mode
      - visibility_modes
      - online_only_assignment
      - courtesy_after_resolve
      - courtesy_window_hours
      - courtesy_ai_mode
      - courtesy_ai_available
      - decisions_mode
      - inboxes
      - inbox_team_priorities
      - teams
    assignment_member:
      type: object
      description: An inbox or team member and their assignment tier there.
      properties:
        id:
          type: integer
          description: User ID.
        name:
          type: string
        email:
          type: string
        thumbnail:
          type: string
          description: Avatar URL; empty string when the user has none.
        role:
          type: string
          enum:
          - agent
          - administrator
          description: Administrators are listed but never receive auto-assigned conversations.
        assignment_priority:
          type: integer
          minimum: 1
          maximum: 10
          description: The member's tier in this inbox or team (lower is offered first).
        availability_status:
          type: string
          enum:
          - online
          - busy
          - offline
          description: Live presence.
      required:
      - id
      - name
      - email
      - thumbnail
      - role
      - assignment_priority
      - availability_status
    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
    assignment_settings_update:
      type: object
      description: 'Every field is optional; omitted fields are left unchanged. The whole update is

        applied atomically: if any part is invalid, nothing is saved.


        Tier maps are keyed by string IDs. A tier is an integer from 1 to 10; lower

        tiers are offered conversations first, agents on the same tier share them

        round-robin, and 1 (the default) everywhere is plain round-robin.

        '
      properties:
        visibility_mode:
          $ref: '#/components/schemas/agent_visibility_mode'
        online_only_assignment:
          type: boolean
          description: 'When true, auto-assignment only picks agents whose presence is `online` (`busy` and

            `offline` count as away). If nobody eligible is online it falls back to every eligible

            agent, so a conversation is never left unassigned by this switch.

            '
        courtesy_after_resolve:
          type: boolean
          description: 'When true (the default), a customer message that is only a thank-you or a goodbye, sent within

            `courtesy_window_hours` of the resolve, stays in the resolved conversation: it does not reopen it,

            does not open a new one and gets no AI agent reply. The message carries

            `content_attributes.courtesy_after_resolve: true`.

            '
        courtesy_window_hours:
          type: integer
          minimum: 1
          maximum: 168
          description: Hours after the resolve during which a thank-you keeps the conversation resolved. Default 24.
        courtesy_ai_mode:
          type: string
          enum:
          - 'off'
          - shadow
          - enforce
          description: 'The AI check for longer thank-yous the built-in word list cannot decide. `shadow` records what it

            would have done and never acts. Anything but `off` needs AI classifications on the plan (403 otherwise).

            '
        inbox_priorities:
          type: object
          description: '`{ "<inbox_id>": { "<user_id>": tier } }` — tiers used when an inbox auto-assigns. Each user must be a member of that inbox.'
          additionalProperties:
            type: object
            additionalProperties:
              type: integer
              minimum: 1
              maximum: 10
          example:
            '12':
              '5': 1
              '9': 2
        team_priorities:
          type: object
          description: '`{ "<team_id>": { "<user_id>": tier } }` — tiers used when a conversation is assigned to a team. Each user must be a member of that team.'
          additionalProperties:
            type: object
            additionalProperties:
              type: integer
              minimum: 1
              maximum: 10
        inbox_team_priorities:
          type: object
          description: '`{ "<inbox_id>": { "<team_id>": { "<user_id>": tier | null } } }` — overrides a team''s tiers

            for conversations in one inbox only (for example, a different lead agent per WhatsApp number).

            The user must be a member of both the team and the inbox. `null` removes the override, so the

            agent falls back to the team''s own tier.

            '
          additionalProperties:
            type: object
            additionalProperties:
              type: object
              additionalProperties:
                type:
                - integer
                - 'null'
                minimum: 1
                maximum: 10
  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