> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

> Save a named, filtered view of the inbox and share it with the organization, named teams, or named users.

# Create a saved inbox view

Use `group_by: "tags"` to group by tags. For `contact_attribute` or
`session_attribute`, also set `group_by_attribute` to the exact key. Grouping
applies to loaded sessions in the inbox. See [grouping saved views](./index#grouping).


## OpenAPI

````yaml post /inbox-views
openapi: 3.1.0
info:
  title: OpenCX API
  description: >

    OpenCX is an AI-powered, all-in-one platform for customer support and
    outbound communications.


    Use this API to manage your OpenCX organization's AI agents, actions,
    conversations, contacts, and more.


    To get started, generate a new API key from the dashboard.


    ## Authentication

    All API endpoints require authentication using a Bearer token. You can
    generate an API key from your OpenCX dashboard.


    ## Rate Limiting

    API requests are rate limited to ensure fair usage. The current limits are:

    - 100 requests per minute for standard endpoints

    - 1000 requests per minute for streaming endpoints


    ## Error Handling

    The API uses standard HTTP status codes and returns detailed error messages
    in the response body.
  version: 1.0-beta
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: http://localhost:8080
    description: Development
  - url: https://api.open.cx
    description: Production
security:
  - bearerAuth: []
paths:
  /inbox-views:
    post:
      summary: Create a saved inbox view
      description: >-
        Create a named, filtered view of the inbox and share it with the
        organization, named teams, or named users. The view is evaluated fresh
        every time it is opened, so `$current_user` assignees and `date.preset`
        windows stay dynamic. Leave both share lists empty to share the view
        with the whole organization. Name users and/or teams to restrict it to
        them, or pass only your own user id to keep it private. Sharing requires
        the `sessions-shared-views:write` permission — without it a created view
        is locked to its creator and the share lists on an update are ignored.
      operationId: createInboxView
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInboxViewDto'
      responses:
        '201':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxViewDto'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    CreateInboxViewDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/CreateInboxViewDtoInput'
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Name shown in the inbox view picker
        filters:
          default: {}
          description: >-
            Filters the view applies, ANDed together. Omit for a view over every
            session. Same vocabulary as POST /chat/sessions/filter, plus the
            saved-view-only `$current_user` assignee token and rolling
            `date.preset`.
          type: object
          properties:
            date:
              description: Date range filter on session creation time
              type: object
              properties:
                from:
                  description: Start date (ISO 8601)
                  type: string
                  format: date-time
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                to:
                  description: End date (ISO 8601)
                  type: string
                  format: date-time
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                preset:
                  description: >-
                    Rolling window resolved every time the view is opened:
                    "today", "last_3_days" or "last_7_days". Mutually exclusive
                    with from/to.
                  type: string
                  enum:
                    - today
                    - last_3_days
                    - last_7_days
            channels:
              description: >-
                Filter by channels (web, email, whatsapp, phone_voice, sms,
                slack, etc.)
              type: array
              items:
                $ref: '#/components/schemas/SessionChannel'
            status:
              description: >-
                Filter by built-in status codes (0 = open, 1 = closed_resolved,
                2 = closed_unresolved)
              type: array
              items:
                type: integer
                minimum: 0
                maximum: 2147483647
            sub_status_ids:
              description: >-
                Filter by custom status ids (sessions whose `sub_status_id` is
                any of these). Ids come from GET /custom-statuses. An empty
                array applies no filter, like the other array filters here.
              type: array
              items:
                type: string
                format: uuid
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            ai_closure:
              description: >-
                Filter by AI closure type (e.g. "handed_off", "resolved",
                "no_resolution")
              type: array
              items:
                type: string
                enum:
                  - assumed_resolved
                  - handed_off
                  - resolved
            sentiment:
              description: Filter by customer sentiment (angry, happy, neutral)
              type: array
              items:
                type: string
                enum:
                  - angry
                  - happy
                  - neutral
            assignees:
              description: >-
                Filter by assignee user IDs (empty array = unassigned). The
                "$current_user" token resolves to whoever opens the view, so one
                shared view can mean "assigned to me" for every teammate.
              type: array
              items:
                anyOf:
                  - type: integer
                    minimum: 0
                    maximum: 2147483647
                  - type: string
                    const: $current_user
            team_ids:
              description: >-
                Filter by assigned team/group IDs. For the inbox Support Team
                filter, use support_team_ids. Use the "$unassigned" token to
                match sessions with no team.
              type: array
              items:
                type: string
            support_team_ids:
              description: >-
                Filter by Support Team IDs (from GET /teams): the support team
                whose inbox contains the session. Distinct from team_ids and
                view-sharing permissions. Use the "$unassigned" token to match
                sessions with no support team.
              type: array
              items:
                type: string
            contact_ids:
              description: Filter by contact IDs
              type: array
              items:
                type: string
            ticket_number:
              description: Filter by exact ticket number
              type: integer
              minimum: 0
              maximum: 2147483647
            language:
              description: Filter by session language codes
              type: array
              items:
                type: string
            tags:
              description: Filter by tag names (sessions must have ALL specified tags)
              type: array
              items:
                type: string
            waiting_on:
              description: Filter by who the session is waiting on
              type: string
              enum:
                - customers
                - human_agents
            custom_data:
              description: >-
                Filter by session custom data (OR between objects, AND within
                each object)
              type: array
              items:
                type: object
                propertyNames:
                  type: string
                additionalProperties:
                  type: string
          additionalProperties: false
        sort_by:
          description: 'Sort field (default: last_message_at)'
          type: string
          enum:
            - last_message_at
            - created_at
            - sla_urgency
            - snoozed_until
        sort_order:
          description: 'Sort direction (default: desc)'
          type: string
          enum:
            - asc
            - desc
        group_by:
          description: Group the session list by this field. Omit for a flat list.
          type: string
          enum:
            - tags
            - contact_attribute
            - session_attribute
            - channel
            - assignee_id
            - status
            - ai_closure_type
            - language
            - inbox_id
        group_by_attribute:
          description: >-
            Exact attribute key for contact_attribute or session_attribute
            grouping. Missing or empty leaves the list ungrouped.
          type: string
        shared_with_user_ids:
          default: []
          type: array
          items:
            type: integer
            minimum: -9007199254740991
            maximum: 9007199254740991
          description: >-
            User ids the view is shared with. Leave both share lists empty to
            share the view with the whole organization. Name users and/or teams
            to restrict it to them, or pass only your own user id to keep it
            private. Sharing requires the `sessions-shared-views:write`
            permission — without it a created view is locked to its creator and
            the share lists on an update are ignored.
        shared_with_team_ids:
          default: []
          type: array
          items:
            type: string
          description: Team ids (from GET /teams) whose members can see the view.
      required:
        - name
    InboxViewDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/InboxViewDto'
      type: object
      properties:
        id:
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        name:
          type: string
          description: Name shown in the inbox view picker
        filters:
          anyOf:
            - type: object
              properties:
                date:
                  description: Date range filter on session creation time
                  type: object
                  properties:
                    from:
                      description: Start date (ISO 8601)
                      type: string
                      format: date-time
                      pattern: >-
                        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    to:
                      description: End date (ISO 8601)
                      type: string
                      format: date-time
                      pattern: >-
                        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    preset:
                      description: >-
                        Rolling window resolved every time the view is opened:
                        "today", "last_3_days" or "last_7_days". Mutually
                        exclusive with from/to.
                      type: string
                      enum:
                        - today
                        - last_3_days
                        - last_7_days
                  additionalProperties: false
                channels:
                  description: >-
                    Filter by channels (web, email, whatsapp, phone_voice, sms,
                    slack, etc.)
                  type: array
                  items:
                    $ref: '#/components/schemas/SessionChannel'
                status:
                  description: >-
                    Filter by built-in status codes (0 = open, 1 =
                    closed_resolved, 2 = closed_unresolved)
                  type: array
                  items:
                    type: integer
                    minimum: 0
                    maximum: 2147483647
                sub_status_ids:
                  description: >-
                    Filter by custom status ids (sessions whose `sub_status_id`
                    is any of these). Ids come from GET /custom-statuses. An
                    empty array applies no filter, like the other array filters
                    here.
                  type: array
                  items:
                    type: string
                    format: uuid
                    pattern: >-
                      ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                ai_closure:
                  description: >-
                    Filter by AI closure type (e.g. "handed_off", "resolved",
                    "no_resolution")
                  type: array
                  items:
                    type: string
                    enum:
                      - assumed_resolved
                      - handed_off
                      - resolved
                sentiment:
                  description: Filter by customer sentiment (angry, happy, neutral)
                  type: array
                  items:
                    type: string
                    enum:
                      - angry
                      - happy
                      - neutral
                assignees:
                  description: >-
                    Filter by assignee user IDs (empty array = unassigned). The
                    "$current_user" token resolves to whoever opens the view, so
                    one shared view can mean "assigned to me" for every
                    teammate.
                  type: array
                  items:
                    anyOf:
                      - type: integer
                        minimum: 0
                        maximum: 2147483647
                      - type: string
                        const: $current_user
                team_ids:
                  description: >-
                    Filter by assigned team/group IDs. For the inbox Support
                    Team filter, use support_team_ids. Use the "$unassigned"
                    token to match sessions with no team.
                  type: array
                  items:
                    type: string
                support_team_ids:
                  description: >-
                    Filter by Support Team IDs (from GET /teams): the support
                    team whose inbox contains the session. Distinct from
                    team_ids and view-sharing permissions. Use the "$unassigned"
                    token to match sessions with no support team.
                  type: array
                  items:
                    type: string
                contact_ids:
                  description: Filter by contact IDs
                  type: array
                  items:
                    type: string
                ticket_number:
                  description: Filter by exact ticket number
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                language:
                  description: Filter by session language codes
                  type: array
                  items:
                    type: string
                tags:
                  description: Filter by tag names (sessions must have ALL specified tags)
                  type: array
                  items:
                    type: string
                waiting_on:
                  description: Filter by who the session is waiting on
                  type: string
                  enum:
                    - customers
                    - human_agents
                custom_data:
                  description: >-
                    Filter by session custom data (OR between objects, AND
                    within each object)
                  type: array
                  items:
                    type: object
                    propertyNames:
                      type: string
                    additionalProperties:
                      type: string
              additionalProperties: false
            - type: 'null'
          description: >-
            The saved filter set. `null` when `advanced` is true — the view uses
            filters this API cannot express.
        advanced:
          type: boolean
          description: >-
            True when the view was built in the dashboard with OR/exclude groups
            or filters outside this API's vocabulary. Its `filters` read back as
            null, and updating `filters` on it REPLACES the whole saved query
            with the simple set you send.
        sort_by:
          anyOf:
            - type: string
              enum:
                - last_message_at
                - created_at
                - sla_urgency
                - snoozed_until
            - type: 'null'
          description: Sort field the view opens with
        sort_order:
          anyOf:
            - type: string
              enum:
                - asc
                - desc
            - type: 'null'
          description: Sort direction the view opens with
        group_by:
          anyOf:
            - type: string
              enum:
                - tags
                - contact_attribute
                - session_attribute
                - channel
                - assignee_id
                - status
                - ai_closure_type
                - language
                - inbox_id
            - type: 'null'
          description: Field sessions are grouped by in the list, when the view groups them
        group_by_attribute:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Exact attribute key for contact or session attribute grouping, or
            null when no key is set.
        shared_with_user_ids:
          type: array
          items:
            type: integer
            minimum: -9007199254740991
            maximum: 9007199254740991
          description: >-
            User ids the view is shared with. Empty (with no teams) means the
            whole org.
        shared_with_team_ids:
          type: array
          items:
            type: string
          description: >-
            Team ids the view is shared with. Empty (with no users) means the
            whole org.
        visibility:
          type: string
          enum:
            - organization
            - personal
            - restricted
        created_by_user_id:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        can_edit:
          type: boolean
          description: Whether the calling user may update this view
        can_delete:
          type: boolean
          description: Whether the calling user may delete this view
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - name
        - filters
        - advanced
        - sort_by
        - sort_order
        - group_by
        - group_by_attribute
        - shared_with_user_ids
        - shared_with_team_ids
        - visibility
        - created_by_user_id
        - can_edit
        - can_delete
        - created_at
        - updated_at
      additionalProperties: false
    ErrorDto:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
    SessionChannel:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/SessionChannel'
      type: string
      enum:
        - web
        - email
        - phone_voice
        - slack
        - sms
        - whatsapp
        - instagram
        - messenger
        - api
        - web_voice
        - twitter
        - twitter_mentions
        - app_review
        - internal
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.