> ## 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.

> Search and filter chat sessions with advanced criteria. Use when orchestrating conversations from code — creating sessions, sending messages, or listing history for an external…

# Filter chat sessions



## OpenAPI

````yaml post /chat/sessions/filter
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: https://api.open.cx
    description: Production
security:
  - bearerAuth: []
paths:
  /chat/sessions/filter:
    post:
      summary: Filter chat sessions
      description: >-
        Search and filter chat sessions with advanced criteria. Supports
        filtering by date range, channels, status, sentiment, tags, assignees,
        teams, contacts, language, custom data, and more. Results are paginated
        and sortable.
      operationId: filterChatSessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterSessionsPublicDto'
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterChatSessionsOutput'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    FilterSessionsPublicDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/FilterSessionsPublicDtoInput'
      type: object
      properties:
        filters:
          default: {}
          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))$
            channels:
              description: >-
                Filter by channels (web, email, whatsapp, phone_voice, sms,
                slack, etc.)
              type: array
              items:
                $ref: '#/components/schemas/SessionChannel'
            status:
              description: >-
                Filter by status codes (0 = open, 1 = closed_resolved, 2 =
                closed_unresolved, or custom status IDs)
              type: array
              items:
                type: integer
                minimum: 0
                maximum: 9007199254740991
            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)
              type: array
              items:
                type: number
            team_ids:
              description: Filter by team/group IDs
              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: number
            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
        sort_by:
          description: 'Sort field (default: last_message_at)'
          type: string
          enum:
            - last_message_at
            - created_at
        sort_order:
          description: 'Sort direction (default: desc)'
          type: string
          enum:
            - asc
            - desc
        page:
          default: 1
          description: 'Page number (1-based, default: 1)'
          type: number
        limit:
          default: 25
          description: 'Results per page (1-100, default: 25)'
          type: number
    FilterChatSessionsOutput:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/FilterChatSessionsOutput'
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GetChatSessionOutput'
        page:
          type: number
        limit:
          type: number
        has_next:
          type: boolean
        has_previous:
          type: boolean
      required:
        - data
        - page
        - limit
        - has_next
        - has_previous
      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
    GetChatSessionOutput:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/GetChatSessionOutput'
      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)$
        status:
          type: string
          enum:
            - open
            - closed_resolved
            - closed_unresolved
        ai_closure_type:
          anyOf:
            - type: string
              enum:
                - assumed_resolved
                - handed_off
                - resolved
            - type: 'null'
        sentiment:
          anyOf:
            - type: string
              enum:
                - angry
                - happy
                - neutral
            - type: 'null'
        channel:
          type: object
          properties:
            type:
              $ref: '#/components/schemas/SessionChannel'
          required:
            - type
          additionalProperties: false
        contact:
          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)$
            email:
              anyOf:
                - type: string
                  format: email
                  pattern: >-
                    ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                - type: 'null'
            phone_number:
              anyOf:
                - type: string
                - type: 'null'
            name:
              anyOf:
                - type: string
                - type: 'null'
            custom_data:
              anyOf:
                - type: object
                  propertyNames:
                    type: string
                  additionalProperties:
                    type: string
                - type: 'null'
            created_at:
              type: string
              description: ISO 8601 timestamp of when the contact was created
            updated_at:
              type: string
              description: ISO 8601 timestamp of when the contact was last updated
            non_verified_name:
              anyOf:
                - type: string
                - type: 'null'
            non_verified_email:
              anyOf:
                - type: string
                - type: 'null'
            non_verified_custom_data:
              anyOf:
                - type: object
                  propertyNames:
                    type: string
                  additionalProperties:
                    anyOf:
                      - type: string
                      - type: number
                      - type: boolean
                - type: 'null'
          required:
            - id
            - email
            - phone_number
            - name
            - custom_data
            - created_at
            - updated_at
            - non_verified_name
            - non_verified_email
            - non_verified_custom_data
          additionalProperties: false
        language:
          type: string
        assignee_id:
          anyOf:
            - type: string
            - type: 'null'
        custom_data:
          description: Session-level custom data stored on the chat session.
          type: object
          propertyNames:
            type: string
          additionalProperties:
            anyOf:
              - type: string
              - type: number
              - type: boolean
        team:
          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:
              type: string
          required:
            - id
            - name
          additionalProperties: false
        handoff:
          type: object
          properties:
            sentiment:
              type: string
              enum:
                - angry
                - happy
                - neutral
            summary:
              type: string
          required:
            - summary
          additionalProperties: false
        ticketing_system:
          type: object
          properties:
            name:
              type: string
              enum:
                - dynamics365
                - freshchat
                - freshdesk
                - freshdesk_ticketing
                - front
                - gorgias
                - hubspot
                - infobip
                - intercom
                - open
                - salesforce
                - salesforce_v2
                - twilio_flex
                - zendesk
                - zendesk_v2
            external_id:
              type: string
            id_type:
              type: string
              enum:
                - conversation_id
                - ticket_id
                - case_id
                - conversation_sid
          required:
            - name
            - external_id
            - id_type
          additionalProperties: false
        ticket_number:
          type: number
        assist_mode:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - status
        - ai_closure_type
        - sentiment
        - channel
        - ticket_number
        - assist_mode
        - created_at
        - updated_at
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````