openapi: 3.0.0
info:
  description: 'Access token should be sent along with every request to SITE_NAME API in authorization header: `Authorization: Bearer <Token>` <br> This token can either be acquired via `auth/login` endpoint or from account settings page on [SITE_NAME website](SITE_URL/account-settings).'
  version: '1.0.0'
  title: SITE_NAME API
security:
  - accessToken: []
tags:
  - name: Auth
  - name: Conversations
  - name: Conversation messages
  - name: Customers
  - name: Groups
  - name: Agents
  - name: Agent invites
  - name: Canned replies
  - name: Views
  - name: Attributes
  - name: Statuses
  - name: Tags
  - name: Search
  - name: Reports
  - name: Triggers
  - name: Envato
  - name: Help center
  - name: Help center articles
  - name: Help center categories
  - name: Help center manager
  - name: Uploads
  - name: Campaigns
paths:
  /helpdesk/agent/conversations:
    get:
      tags:
        - Conversations
      summary: List conversations
      description: Get a paginated list of conversations
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            example: 1
        - name: perPage
          in: query
          description: Number of items per page
          schema:
            type: integer
            example: 15
        - name: viewId
          in: query
          description: Filter by view ID
          schema:
            type: integer
        - name: status
          in: query
          description: Filter by status
          schema:
            type: string
        - name: assigned_to
          in: query
          description: Filter by assigned agent ID
          schema:
            type: integer
        - name: group_id
          in: query
          description: Filter by group ID
          schema:
            type: integer
        - name: orderBy
          in: query
          description: Field to order by
          schema:
            type: string
            default: updated_at
            example: updated_at
        - name: orderDir
          in: query
          description: Order direction
          schema:
            type: string
            enum: [asc, desc]
            default: desc
            example: desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                      last_page:
                        type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConversationListItem'
                  columns:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
    post:
      tags:
        - Conversations
      summary: Create a new conversation
      description: Create a new conversation as an agent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - user_id
                - message
              properties:
                type:
                  type: string
                  enum: [ticket, chat]
                  description: Type of conversation
                user_id:
                  type: integer
                  description: Customer user ID
                subject:
                  type: string
                  minLength: 3
                  maxLength: 180
                  description: Subject (required for tickets)
                message:
                  type: object
                  required:
                    - body
                  properties:
                    body:
                      type: string
                      minLength: 3
                      description: Message body
                    attachments:
                      type: array
                      maxItems: 10
                      description: Array of attachment IDs
                      items:
                        type: integer
                status_id:
                  type: integer
                  description: Conversation status ID
                attributes:
                  type: object
                  description: Custom attributes
      responses:
        '200':
          description: Conversation created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversation:
                    $ref: '#/components/schemas/Conversation'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/agent/conversations/{id}:
    get:
      tags:
        - Conversations
      summary: Get a single conversation
      description: Get full details of a conversation including messages and metadata
      parameters:
        - name: id
          in: path
          required: true
          description: Conversation ID
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FullConversationResponse'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
    put:
      tags:
        - Conversations
      summary: Update a conversation
      description: Update conversation details
      parameters:
        - name: id
          in: path
          required: true
          description: Conversation ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subject:
                  type: string
                  minLength: 3
                  maxLength: 255
                  description: Conversation subject
                user_id:
                  type: integer
                  description: Assign to customer user ID
                attributes:
                  type: object
                  description: Custom attributes
      responses:
        '200':
          description: Conversation updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversation:
                    $ref: '#/components/schemas/Conversation'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/agent/conversations/{ids}:
    delete:
      tags:
        - Conversations
      summary: Delete conversations
      description: Delete one or more conversations by IDs
      parameters:
        - name: ids
          in: path
          required: true
          description: Comma-separated conversation IDs
          schema:
            type: string
            example: '1,2,3'
      responses:
        '204':
          description: Conversations deleted successfully
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /tickets/mail/incoming:
    post:
      tags:
        - Conversations
      summary: Convert raw email or JSON data into ticket or reply
      operationId: incomingEmail
      requestBody:
        required: true
        description: Email data can be in JSON format below or simply raw email data as string in "mime" parameter.
        content:
          application/json:
            schema:
              type: object
              properties:
                headers:
                  type: object
                  example:
                    {'From': 'test@test.com', 'Message-ID': '39123k13jjk2j312'}
                  description: Email headers
                body:
                  type: object
                  example: {'html': '<p>html body</p>', 'plain': 'text body'}
                  description: Email html and plain body
                attachments:
                  type: array
                  example:
                    [
                      {
                        'original_name': 'file1.jpg',
                        'mime_type': 'image/jpeg',
                        'extension': 'jpg',
                        'size': 123,
                        'contents': 'base64 encoded data',
                      },
                    ]
                  description: Email attachments
      responses:
        '200':
          description: Ticket or reply created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/agent/conversations/merge:
    post:
      tags:
        - Conversations
      summary: Merge conversations
      description: Merge multiple conversations into a single conversation. All messages and metadata from the source conversations will be moved to the target conversation. This operation cannot be undone.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - conversationId
                - toMerge
              properties:
                conversationId:
                  type: integer
                  description: Target conversation ID (all other conversations will be merged into this one)
                  example: 1
                toMerge:
                  type: array
                  minItems: 1
                  items:
                    type: integer
                  description: Array of conversation IDs to merge into the target conversation
                  example: [2, 3, 4]
      responses:
        '200':
          description: Conversations merged successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversation:
                    $ref: '#/components/schemas/Conversation'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/agent/conversations/{conversationId}/messages:
    get:
      tags:
        - Conversation messages
      summary: Get conversation messages
      description: Get paginated list of messages for a conversation with cursor-based pagination
      parameters:
        - name: conversationId
          in: path
          required: true
          description: Conversation ID
          schema:
            type: integer
        - name: cursor
          in: query
          description: Cursor for pagination
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ConversationMessage'
                      next_cursor:
                        type: string
                        nullable: true
                        example: 'eyJpZCI6MTAsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
    post:
      tags:
        - Conversation messages
      summary: Create a new message
      description: Create a new message or note in a conversation
      parameters:
        - name: conversationId
          in: path
          required: true
          description: Conversation ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - body
                - type
              properties:
                body:
                  type: string
                  minLength: 1
                  description: Message body content
                  example: 'Thank you for contacting us. We will help you with this issue.'
                type:
                  type: string
                  enum: [note, message]
                  description: Type of message (note is internal, message is sent to customer)
                  example: message
                uuid:
                  type: string
                  description: Optional UUID for client-side tracking
                  example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
                status_id:
                  type: integer
                  nullable: true
                  description: Optional status ID to set on conversation
                  example: 2
                attachments:
                  type: array
                  maxItems: 10
                  items:
                    type: integer
                  description: Array of file entry IDs to attach
                  example: [1, 2, 3]
                tags:
                  type: array
                  items:
                    type: integer
                  description: Array of tag IDs to add to conversation
                  example: [5, 7]
      responses:
        '201':
          description: Message created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    $ref: '#/components/schemas/ConversationMessage'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/agent/messages/{messageId}:
    put:
      tags:
        - Conversation messages
      summary: Update a message
      description: Update the body or attachments of an existing message
      parameters:
        - name: messageId
          in: path
          required: true
          description: Message ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                body:
                  type: string
                  minLength: 1
                  description: Updated message body
                  example: 'Updated message content'
                attachments:
                  type: array
                  maxItems: 5
                  items:
                    type: integer
                  description: Array of file entry IDs (replaces existing attachments)
                  example: [1, 2]
      responses:
        '200':
          description: Message updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    $ref: '#/components/schemas/ConversationMessage'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
    delete:
      tags:
        - Conversation messages
      summary: Delete a message
      description: Delete a message or note from a conversation
      parameters:
        - name: messageId
          in: path
          required: true
          description: Message ID
          schema:
            type: integer
      responses:
        '200':
          description: Message deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /helpdesk/agent/messages/{messageId}/email:
    get:
      tags:
        - Conversation messages
      summary: Get original reply email
      description: Retrieve the original email content (HTML, plain text, and headers) for a message that was received via email
      parameters:
        - name: messageId
          in: path
          required: true
          description: Message ID
          schema:
            type: integer
      responses:
        '200':
          description: Original email retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OriginalReplyEmailResponse'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /helpdesk/agent/messages/{messageId}/email/download:
    get:
      tags:
        - Conversation messages
      summary: Download original reply email
      description: Download the original email as a file (.eml format)
      parameters:
        - name: messageId
          in: path
          required: true
          description: Message ID
          schema:
            type: integer
      responses:
        '200':
          description: Email file download
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /helpdesk/agent/conversations/status/change:
    post:
      tags:
        - Conversations
      summary: Change conversation status
      description: Change the status of one or more conversations using status ID or name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - conversationIds
              properties:
                conversationIds:
                  type: array
                  items:
                    type: integer
                  description: Array of conversation IDs to update
                  example: [1, 2, 3]
                statusId:
                  type: integer
                  description: Status ID to set (use either statusId or statusName)
                  example: 5
                statusName:
                  type: string
                  enum: [open, closed]
                  description: Status name to set (use either statusId or statusName)
                  example: closed
      responses:
        '200':
          description: Status changed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/agent/conversations/assignee/change:
    post:
      tags:
        - Conversations
      summary: Assign conversations to agent
      description: Assign one or more conversations to a specific agent with optional private note and summary generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - conversationIds
                - userId
              properties:
                conversationIds:
                  type: array
                  minItems: 1
                  items:
                    type: integer
                  description: Array of conversation IDs to assign
                  example: [1, 2, 3]
                userId:
                  type: integer
                  description: Agent user ID to assign conversations to
                  example: 5
                privateNote:
                  type: string
                  nullable: true
                  description: Optional private note to add to the conversations
                  example: 'Transferring to specialist for review'
                shouldSummarize:
                  type: boolean
                  nullable: true
                  description: Whether to generate AI summary for the first conversation
                  example: true
      responses:
        '200':
          description: Conversations assigned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/agent/conversations/group/change:
    post:
      tags:
        - Conversations
      summary: Assign conversations to group
      description: Assign one or more conversations to a specific group with optional private note and summary generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - conversationIds
                - groupId
              properties:
                conversationIds:
                  type: array
                  minItems: 1
                  items:
                    type: integer
                  description: Array of conversation IDs to assign
                  example: [1, 2, 3]
                groupId:
                  type: integer
                  description: Group ID to assign conversations to
                  example: 2
                privateNote:
                  type: string
                  nullable: true
                  description: Optional private note to add to the conversations
                  example: 'Transferring to support team'
                shouldSummarize:
                  type: boolean
                  nullable: true
                  description: Whether to generate AI summary for the first conversation
                  example: true
      responses:
        '200':
          description: Conversations assigned to group successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/conversations/{conversationId}/tags:
    get:
      tags:
        - Tags
      summary: Get conversation tags
      description: Get all tags attached to a specific conversation
      parameters:
        - name: conversationId
          in: path
          required: true
          description: Conversation ID
          schema:
            type: integer
      responses:
        '200':
          description: Tags retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  tags:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConversationTag'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /helpdesk/conversations/tags/add:
    post:
      tags:
        - Tags
      summary: Add tag to conversations
      description: Add a tag to one or more conversations. Can either specify an existing tag by ID or create a new tag by name.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - conversationIds
              properties:
                tagId:
                  type: integer
                  description: ID of an existing tag (use either tagId or newTagName)
                  example: 5
                newTagName:
                  type: string
                  maxLength: 100
                  description: Name for a new tag to create (use either tagId or newTagName)
                  example: 'urgent'
                conversationIds:
                  type: array
                  minItems: 1
                  items:
                    type: integer
                  description: Array of conversation IDs to add the tag to
                  example: [1, 2, 3]
      responses:
        '200':
          description: Tag added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/conversations/tags/remove:
    post:
      tags:
        - Tags
      summary: Remove tag from conversations
      description: Remove a tag from one or more conversations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - tagId
                - conversationIds
              properties:
                tagId:
                  type: integer
                  description: ID of the tag to remove
                  example: 5
                conversationIds:
                  type: array
                  minItems: 1
                  items:
                    type: integer
                  description: Array of conversation IDs to remove the tag from
                  example: [1, 2, 3]
      responses:
        '200':
          description: Tag removed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/statuses:
    get:
      tags:
        - Statuses
      summary: List statuses
      description: Get a paginated list of conversation statuses for management purposes
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            example: 1
        - name: perPage
          in: query
          description: Number of items per page
          schema:
            type: integer
            example: 15
        - name: orderBy
          in: query
          description: Field to order by
          schema:
            type: string
            default: updated_at
        - name: orderDir
          in: query
          description: Order direction
          schema:
            type: string
            enum: [asc, desc]
            default: desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                      last_page:
                        type: integer
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ConversationStatus'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
    post:
      tags:
        - Statuses
      summary: Create a new status
      description: Create a new conversation status
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - label
                - category
              properties:
                label:
                  type: string
                  maxLength: 100
                  description: Status label for agents
                  example: 'Awaiting Customer Response'
                user_label:
                  type: string
                  nullable: true
                  maxLength: 100
                  description: Optional custom label shown to customers
                  example: 'Waiting for your reply'
                category:
                  type: integer
                  enum: [3, 4, 5, 6]
                  description: Status category (3=locked, 4=closed, 5=pending, 6=open)
                  example: 5
                active:
                  type: boolean
                  default: true
                  description: Whether the status is active
                  example: true
      responses:
        '200':
          description: Status created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/ConversationStatus'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/statuses/{id}:
    put:
      tags:
        - Statuses
      summary: Update a status
      description: Update an existing conversation status
      parameters:
        - name: id
          in: path
          required: true
          description: Status ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: string
                  maxLength: 100
                  description: Status label for agents
                  example: 'Awaiting Customer Response'
                user_label:
                  type: string
                  nullable: true
                  maxLength: 100
                  description: Optional custom label shown to customers
                  example: 'Waiting for your reply'
                category:
                  type: integer
                  enum: [3, 4, 5, 6]
                  description: Status category (3=locked, 4=closed, 5=pending, 6=open)
                  example: 5
                active:
                  type: boolean
                  description: Whether the status is active
                  example: true
      responses:
        '200':
          description: Status updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/ConversationStatus'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/statuses/{ids}:
    delete:
      tags:
        - Statuses
      summary: Delete statuses
      description: Delete one or more conversation statuses by IDs
      parameters:
        - name: ids
          in: path
          required: true
          description: Comma-separated status IDs
          schema:
            type: string
            example: '1,2,3'
      responses:
        '200':
          description: Statuses deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /helpdesk/statuses/list:
    get:
      tags:
        - Statuses
      summary: Get dropdown list of statuses
      description: Get a simplified list of active statuses for dropdown/select components
      parameters:
        - name: label
          in: query
          description: Whether to return agent or user-facing labels
          required: true
          schema:
            type: string
            enum: [agent, user]
            example: agent
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  statuses:
                    type: array
                    items:
                      $ref: '#/components/schemas/CompactConversationStatus'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /helpdesk/views:
    get:
      tags:
        - Views
      summary: List views
      description: Get a paginated list of conversation views
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            example: 1
        - name: perPage
          in: query
          description: Number of items per page
          schema:
            type: integer
            example: 15
        - name: orderBy
          in: query
          description: Field to order by
          schema:
            type: string
            default: order
            example: order
        - name: orderDir
          in: query
          description: Order direction
          schema:
            type: string
            enum: [asc, desc]
            default: asc
            example: asc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                      last_page:
                        type: integer
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/View'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
    post:
      tags:
        - Views
      summary: Create a new view
      description: Create a new conversation view with filters and display settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - access
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: View name
                  example: 'High Priority Tickets'
                icon:
                  type: string
                  maxLength: 60
                  nullable: true
                  description: Icon identifier
                  example: 'urgent'
                access:
                  type: string
                  enum: [anyone, owner, group]
                  description: Who can access this view
                  example: 'anyone'
                pinned:
                  type: boolean
                  description: Whether the view is pinned to sidebar
                  example: true
                description:
                  type: string
                  maxLength: 255
                  nullable: true
                  description: View description
                  example: 'All high priority support tickets'
                group_id:
                  type: integer
                  nullable: true
                  description: Group ID if access is 'group'
                  example: 2
                conditions:
                  type: array
                  description: Filter conditions for the view
                  items:
                    $ref: '#/components/schemas/ViewCondition'
                columns:
                  type: array
                  description: Columns to display in the view
                  items:
                    type: string
                  example: ['subject', 'status', 'assigned_to', 'updated_at']
                order_by:
                  type: string
                  maxLength: 100
                  description: Field to order results by
                  example: 'updated_at'
                order_dir:
                  type: string
                  enum: [asc, desc]
                  description: Order direction
                  example: 'desc'
      responses:
        '200':
          description: View created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  view:
                    $ref: '#/components/schemas/View'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/views/{id}:
    get:
      tags:
        - Views
      summary: Get a single view
      description: Get full details of a conversation view including filters and settings
      parameters:
        - name: id
          in: path
          required: true
          description: View ID
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  view:
                    $ref: '#/components/schemas/View'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
    put:
      tags:
        - Views
      summary: Update a view
      description: Update an existing conversation view
      parameters:
        - name: id
          in: path
          required: true
          description: View ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: View name
                  example: 'High Priority Tickets'
                icon:
                  type: string
                  maxLength: 60
                  nullable: true
                  description: Icon identifier
                  example: 'urgent'
                access:
                  type: string
                  enum: [anyone, owner, group]
                  description: Who can access this view (not allowed for internal views)
                  example: 'anyone'
                pinned:
                  type: boolean
                  description: Whether the view is pinned to sidebar
                  example: true
                description:
                  type: string
                  maxLength: 255
                  nullable: true
                  description: View description
                  example: 'All high priority support tickets'
                group_id:
                  type: integer
                  nullable: true
                  description: Group ID if access is 'group'
                  example: 2
                conditions:
                  type: array
                  description: Filter conditions for the view (not allowed for internal views)
                  items:
                    $ref: '#/components/schemas/ViewCondition'
                columns:
                  type: array
                  nullable: true
                  description: Columns to display in the view
                  items:
                    type: string
                  example: ['subject', 'status', 'assigned_to', 'updated_at']
                order_by:
                  type: string
                  maxLength: 100
                  description: Field to order results by
                  example: 'updated_at'
                order_dir:
                  type: string
                  enum: [asc, desc]
                  description: Order direction
                  example: 'desc'
                active:
                  type: boolean
                  description: Whether the view is active (not allowed for internal views)
                  example: true
      responses:
        '200':
          description: View updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  view:
                    $ref: '#/components/schemas/View'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
    delete:
      tags:
        - Views
      summary: Delete a view
      description: Delete a conversation view (system/internal views cannot be deleted)
      parameters:
        - name: id
          in: path
          required: true
          description: View ID
          schema:
            type: integer
      responses:
        '200':
          description: View deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '400':
          description: Cannot delete system views
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'System views can not be deleted'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /helpdesk/views/reorder:
    post:
      tags:
        - Views
      summary: Reorder views
      description: Update the display order of conversation views
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - viewIds
              properties:
                viewIds:
                  type: array
                  minItems: 1
                  items:
                    type: integer
                  description: Array of view IDs in the desired order
                  example: [3, 1, 5, 2, 4]
      responses:
        '200':
          description: Views reordered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/attributes/list:
    get:
      tags:
        - Attributes
      summary: Get simplified list of attributes
      description: Get a list of attributes for dropdowns/selects with simplified structure
      parameters:
        - name: for
          in: query
          description: Who the attributes are being fetched for (affects which labels are returned)
          schema:
            type: string
            enum: [customer, agent]
            default: customer
            example: customer
        - name: attributeIds
          in: query
          description: Comma-separated attribute IDs to fetch specific attributes
          schema:
            type: string
            example: '1,2,3'
        - name: type
          in: query
          description: Filter by attribute type
          schema:
            type: string
            enum: [conversation, user, aiAgentSession]
            example: conversation
        - name: permission
          in: query
          description: Filter by permission level
          schema:
            type: string
            enum: [userCanEdit, userCanView, agentCanEdit]
            example: userCanEdit
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  attributes:
                    type: array
                    items:
                      $ref: '#/components/schemas/CompactAttribute'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /helpdesk/attributes:
    get:
      tags:
        - Attributes
      summary: List attributes
      description: Get a paginated list of custom attributes for management purposes
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            example: 1
        - name: perPage
          in: query
          description: Number of items per page
          schema:
            type: integer
            example: 15
        - name: orderBy
          in: query
          description: Field to order by
          schema:
            type: string
            default: updated_at
            example: updated_at
        - name: orderDir
          in: query
          description: Order direction
          schema:
            type: string
            enum: [asc, desc]
            default: desc
            example: desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                      last_page:
                        type: integer
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Attribute'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
    post:
      tags:
        - Attributes
      summary: Create a new attribute
      description: Create a new custom attribute
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - type
                - format
                - permission
              properties:
                name:
                  type: string
                  maxLength: 60
                  description: Internal attribute name
                  example: 'Priority Level'
                customer_name:
                  type: string
                  maxLength: 60
                  nullable: true
                  description: Customer-facing attribute name
                  example: 'Priority'
                type:
                  type: string
                  enum: [conversation, user, aiAgentSession]
                  description: Type of entity this attribute applies to
                  example: conversation
                format:
                  type: string
                  enum:
                    [
                      text,
                      multiLineText,
                      email,
                      url,
                      switch,
                      number,
                      phone,
                      date,
                      radioGroup,
                      checkboxGroup,
                      dropdown,
                      rating,
                    ]
                  description: Input format/control type
                  example: dropdown
                description:
                  type: string
                  maxLength: 600
                  nullable: true
                  description: Internal description for agents
                  example: 'Priority level for ticket routing'
                customer_description:
                  type: string
                  maxLength: 300
                  nullable: true
                  description: Description shown to customers
                  example: 'Select the priority of your issue'
                permission:
                  type: string
                  enum: [userCanEdit, userCanView, agentCanEdit]
                  description: Who can edit this attribute
                  example: agentCanEdit
                required:
                  type: boolean
                  default: false
                  description: Whether the attribute is required
                  example: true
                config:
                  type: object
                  nullable: true
                  description: Additional configuration (e.g., options for dropdown)
                  properties:
                    options:
                      type: array
                      items:
                        type: object
                        properties:
                          label:
                            type: string
                          value:
                            type: string
                      example:
                        - label: 'Low'
                          value: 'low'
                        - label: 'Medium'
                          value: 'medium'
                        - label: 'High'
                          value: 'high'
      responses:
        '200':
          description: Attribute created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  attribute:
                    $ref: '#/components/schemas/Attribute'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/attributes/{id}:
    get:
      tags:
        - Attributes
      summary: Get a single attribute
      description: Get full details of a custom attribute
      parameters:
        - name: id
          in: path
          required: true
          description: Attribute ID
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  attribute:
                    $ref: '#/components/schemas/Attribute'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
    put:
      tags:
        - Attributes
      summary: Update an attribute
      description: Update an existing custom attribute
      parameters:
        - name: id
          in: path
          required: true
          description: Attribute ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 60
                  description: Internal attribute name
                  example: 'Priority Level'
                customer_name:
                  type: string
                  maxLength: 60
                  nullable: true
                  description: Customer-facing attribute name
                  example: 'Priority'
                type:
                  type: string
                  enum: [conversation, user, aiAgentSession]
                  description: Type of entity this attribute applies to
                  example: conversation
                format:
                  type: string
                  enum:
                    [
                      text,
                      multiLineText,
                      email,
                      url,
                      switch,
                      number,
                      phone,
                      date,
                      radioGroup,
                      checkboxGroup,
                      dropdown,
                      rating,
                    ]
                  description: Input format/control type
                  example: dropdown
                description:
                  type: string
                  maxLength: 600
                  nullable: true
                  description: Internal description for agents
                  example: 'Priority level for ticket routing'
                customer_description:
                  type: string
                  maxLength: 300
                  nullable: true
                  description: Description shown to customers
                  example: 'Select the priority of your issue'
                permission:
                  type: string
                  enum: [userCanEdit, userCanView, agentCanEdit]
                  description: Who can edit this attribute
                  example: agentCanEdit
                required:
                  type: boolean
                  description: Whether the attribute is required
                  example: true
                active:
                  type: boolean
                  description: Whether the attribute is active (only editable for non-internal attributes)
                  example: true
                config:
                  type: object
                  nullable: true
                  description: Additional configuration (e.g., options for dropdown)
                  properties:
                    options:
                      type: array
                      items:
                        type: object
                        properties:
                          label:
                            type: string
                          value:
                            type: string
                      example:
                        - label: 'Low'
                          value: 'low'
                        - label: 'Medium'
                          value: 'medium'
                        - label: 'High'
                          value: 'high'
      responses:
        '200':
          description: Attribute updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  attribute:
                    $ref: '#/components/schemas/Attribute'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
    delete:
      tags:
        - Attributes
      summary: Delete an attribute
      description: Delete a custom attribute (internal system attributes cannot be deleted)
      parameters:
        - name: id
          in: path
          required: true
          description: Attribute ID
          schema:
            type: integer
      responses:
        '200':
          description: Attribute deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /helpdesk/groups:
    get:
      tags:
        - Groups
      summary: List groups
      description: Get a paginated list of agent groups
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            example: 1
        - name: perPage
          in: query
          description: Number of items per page
          schema:
            type: integer
            example: 15
        - name: query
          in: query
          description: Search query
          schema:
            type: string
        - name: orderBy
          in: query
          description: Field to order by
          schema:
            type: string
            default: updated_at
            example: updated_at
        - name: orderDir
          in: query
          description: Order direction
          schema:
            type: string
            enum: [asc, desc]
            default: desc
            example: desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                      last_page:
                        type: integer
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/GroupTableItem'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
    post:
      tags:
        - Groups
      summary: Create a new group
      description: Create a new agent group
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - assignment_mode
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: Group name
                  example: 'Support Team'
                assignment_mode:
                  type: string
                  enum: [auto, manual]
                  description: How conversations are assigned to this group
                  example: 'auto'
                users:
                  type: array
                  description: Array of user objects with priority settings
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                        description: User ID
                        example: 5
                      conversation_priority:
                        type: string
                        enum: [primary, backup]
                        description: Agent's priority in this group
                        example: 'primary'
      responses:
        '200':
          description: Group created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  group:
                    $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/groups/{groupId}:
    get:
      tags:
        - Groups
      summary: Get a single group
      description: Get full details of an agent group including members
      parameters:
        - name: groupId
          in: path
          required: true
          description: Group ID
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  group:
                    $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
    put:
      tags:
        - Groups
      summary: Update a group
      description: Update an existing agent group
      parameters:
        - name: groupId
          in: path
          required: true
          description: Group ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: Group name
                  example: 'Support Team'
                assignment_mode:
                  type: string
                  enum: [auto, manual]
                  description: How conversations are assigned to this group
                  example: 'auto'
                users:
                  type: array
                  description: Array of user objects with priority settings
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                        description: User ID
                        example: 5
                      conversation_priority:
                        type: string
                        enum: [primary, backup]
                        description: Agent's priority in this group
                        example: 'primary'
      responses:
        '200':
          description: Group updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  group:
                    $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
    delete:
      tags:
        - Groups
      summary: Delete a group
      description: Delete an agent group
      parameters:
        - name: groupId
          in: path
          required: true
          description: Group ID
          schema:
            type: integer
      responses:
        '200':
          description: Group deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /helpdesk/agents:
    get:
      tags:
        - Agents
      summary: List agents
      description: Get a paginated list of agents
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            example: 1
        - name: perPage
          in: query
          description: Number of items per page
          schema:
            type: integer
            example: 15
        - name: query
          in: query
          description: Search query
          schema:
            type: string
        - name: orderBy
          in: query
          description: Field to order by
          schema:
            type: string
            default: updated_at
            example: updated_at
        - name: orderDir
          in: query
          description: Order direction
          schema:
            type: string
            enum: [asc, desc]
            default: desc
            example: desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                      last_page:
                        type: integer
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/AgentTableItem'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /helpdesk/agents/{agentId}:
    get:
      tags:
        - Agents
      summary: Get a single agent
      description: Get full details of an agent including settings and groups
      parameters:
        - name: agentId
          in: path
          required: true
          description: Agent ID
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    $ref: '#/components/schemas/Agent'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
    put:
      tags:
        - Agents
      summary: Update an agent
      description: Update agent settings, groups, and roles
      parameters:
        - name: agentId
          in: path
          required: true
          description: Agent ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: Agent name
                  example: 'John Doe'
                image:
                  type: string
                  description: Avatar image URL
                  example: 'https://example.com/avatar.jpg'
                agent_settings:
                  type: object
                  description: Agent-specific settings
                  properties:
                    assignment_limit:
                      type: integer
                      description: Maximum number of concurrent conversations
                      example: 10
                    accepts_conversations:
                      type: string
                      enum: [yes, no, workingHours]
                      description: When agent accepts new conversations
                      example: 'workingHours'
                    working_hours:
                      type: object
                      nullable: true
                      description: Working hours by day (null if not set)
                      additionalProperties:
                        type: object
                        properties:
                          from:
                            type: string
                            description: Start time (HH:mm format)
                            example: '09:00'
                          to:
                            type: string
                            description: End time (HH:mm format)
                            example: '17:00'
                      example:
                        monday:
                          from: '09:00'
                          to: '17:00'
                        tuesday:
                          from: '09:00'
                          to: '17:00'
                groups:
                  type: array
                  items:
                    type: integer
                  description: Array of group IDs
                  example: [1, 2, 3]
                roles:
                  type: array
                  items:
                    type: integer
                  description: Array of role IDs
                  example: [2]
                permissions:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
                  description: Array of permission objects
      responses:
        '200':
          description: Agent updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    $ref: '#/components/schemas/Agent'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
    delete:
      tags:
        - Agents
      summary: Delete an agent
      description: Delete an agent from the system
      parameters:
        - name: agentId
          in: path
          required: true
          description: Agent ID
          schema:
            type: integer
      responses:
        '200':
          description: Agent deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /helpdesk/compact-agents:
    get:
      tags:
        - Agents
      summary: Get compact agents list
      description: Get a simplified list of all agents with online status and assignment info. This endpoint is frequently polled for real-time updates.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  agents:
                    type: array
                    items:
                      $ref: '#/components/schemas/CompactAgent'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /helpdesk/agents/invites:
    get:
      tags:
        - Agent invites
      summary: List agent invites
      description: Get a paginated list of pending agent invitations
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            example: 1
        - name: perPage
          in: query
          description: Number of items per page
          schema:
            type: integer
            example: 15
        - name: query
          in: query
          description: Search query
          schema:
            type: string
        - name: orderBy
          in: query
          description: Field to order by
          schema:
            type: string
            default: created_at
            example: created_at
        - name: orderDir
          in: query
          description: Order direction
          schema:
            type: string
            enum: [asc, desc]
            default: desc
            example: desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                      last_page:
                        type: integer
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/AgentInvite'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /helpdesk/agents/invite:
    post:
      tags:
        - Agent invites
      summary: Invite agents
      description: Send invitations to one or more email addresses to join as agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - emails
                - role_id
                - group_id
              properties:
                emails:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    format: email
                  description: Array of email addresses to invite
                  example: ['agent1@example.com', 'agent2@example.com']
                role_id:
                  type: integer
                  description: Role ID to assign to invited agents
                  example: 2
                group_id:
                  type: integer
                  description: Group ID to assign invited agents to
                  example: 1
      responses:
        '200':
          description: Invitations sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/agents/invite/{inviteId}:
    delete:
      tags:
        - Agent invites
      summary: Revoke an agent invite
      description: Revoke/cancel a pending agent invitation
      parameters:
        - name: inviteId
          in: path
          required: true
          description: Invite ID
          schema:
            type: integer
      responses:
        '200':
          description: Invite revoked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /helpdesk/agents/invite/{inviteId}/resend:
    post:
      tags:
        - Agent invites
      summary: Resend an agent invite
      description: Resend the invitation email for a pending invite
      parameters:
        - name: inviteId
          in: path
          required: true
          description: Invite ID
          schema:
            type: integer
      responses:
        '200':
          description: Invite resent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /helpdesk/customers:
    get:
      tags:
        - Customers
      summary: List customers
      description: Get a paginated list of customers with optional filtering
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            example: 1
        - name: perPage
          in: query
          description: Number of items per page
          schema:
            type: integer
            example: 15
        - name: query
          in: query
          description: Search query
          schema:
            type: string
        - name: orderBy
          in: query
          description: Field to order by
          schema:
            type: string
            default: updated_at
            example: updated_at
        - name: orderDir
          in: query
          description: Order direction
          schema:
            type: string
            enum: [asc, desc]
            default: desc
            example: desc
        - name: filters
          in: query
          description: JSON-encoded filters for advanced filtering
          schema:
            type: string
        - name: type
          in: query
          description: Filter by user type
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                      last_page:
                        type: integer
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /helpdesk/customers/{id}:
    get:
      tags:
        - Customers
      summary: Get a single customer
      description: Get full details of a customer profile including session, tags, and attributes
      parameters:
        - name: id
          in: path
          required: true
          description: Customer ID
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/CustomerProfile'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
    put:
      tags:
        - Customers
      summary: Update a customer
      description: Update customer profile information, tags, and custom attributes
      parameters:
        - name: id
          in: path
          required: true
          description: Customer ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: Customer name
                  example: 'John Customer'
                timezone:
                  type: string
                  nullable: true
                  description: Customer timezone
                  example: 'America/New_York'
                country:
                  type: string
                  nullable: true
                  maxLength: 2
                  description: ISO country code
                  example: 'US'
                language:
                  type: string
                  nullable: true
                  description: Language code
                  example: 'en'
                tags:
                  type: array
                  items:
                    type: string
                  description: Array of tag names
                  example: ['vip', 'premium']
                notes:
                  type: string
                  nullable: true
                  description: Internal notes about the customer
                  example: 'Important client, needs priority support'
                emails:
                  type: array
                  items:
                    type: string
                    format: email
                  description: Array of additional email addresses
                  example: ['john@example.com', 'john.doe@company.com']
                attributes:
                  type: object
                  description: Custom attribute values
                  additionalProperties: true
      responses:
        '200':
          description: Customer updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
    delete:
      tags:
        - Customers
      summary: Delete a customer
      description: Permanently delete a customer account. This action cannot be undone.
      parameters:
        - name: id
          in: path
          required: true
          description: Customer ID
          schema:
            type: integer
      responses:
        '200':
          description: Customer deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /helpdesk/customers/{id}/conversations:
    get:
      tags:
        - Customers
      summary: Get customer conversations
      description: Get a paginated list of conversations for a specific customer
      parameters:
        - name: id
          in: path
          required: true
          description: Customer ID
          schema:
            type: integer
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            example: 1
        - name: perPage
          in: query
          description: Number of items per page
          schema:
            type: integer
            example: 15
        - name: orderBy
          in: query
          description: Field to order by
          schema:
            type: string
            example: updated_at
        - name: orderDir
          in: query
          description: Order direction
          schema:
            type: string
            enum: [asc, desc]
            example: desc
        - name: statusId
          in: query
          description: Filter by status ID
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ConversationListItem'
                      next_page_url:
                        type: string
                        nullable: true
                        example: 'https://example.com/api/v1/helpdesk/customers/1/conversations?page=2'
                      prev_page_url:
                        type: string
                        nullable: true
                        example: null
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /helpdesk/customers/merge:
    post:
      tags:
        - Customers
      summary: Merge customers
      description: Merge two customer accounts. All data from the mergee (source) will be transferred to the target user, and the mergee account will be deleted. This operation cannot be undone.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
                - mergee_id
              properties:
                user_id:
                  type: integer
                  description: Target customer ID (data will be merged into this user)
                  example: 10
                mergee_id:
                  type: integer
                  description: Source customer ID (this user will be deleted after merge)
                  example: 25
      responses:
        '200':
          description: Customers merged successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /hc:
    get:
      tags:
        - Help center
      summary: Get help center landing page data
      description: Get all categories, sections and articles for the help center homepage
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HcLandingPageData'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /hc/categories/{categoryId}:
    get:
      tags:
        - Help center categories
      summary: Get a single category or section
      description: Get full details of a help center category or section including related articles
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Category or section ID
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HcCategoryPageData'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
    put:
      tags:
        - Help center categories
      summary: Update a category or section
      description: Update an existing help center category or section
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Category or section ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: Category or section name
                  example: 'Getting Started'
                description:
                  type: string
                  nullable: true
                  description: Category description
                  example: 'Learn the basics'
                image:
                  type: string
                  nullable: true
                  description: Category image URL or identifier
                  example: 'images/category.svg'
                parent_id:
                  type: integer
                  nullable: true
                  description: Parent category ID (for sections)
                  example: 1
                visible_to_role:
                  type: integer
                  nullable: true
                  description: Role ID required to view this category
                  example: 2
                managed_by_role:
                  type: integer
                  nullable: true
                  description: Role ID required to manage this category
                  example: 3
                hide_from_structure:
                  type: boolean
                  description: Whether to hide from navigation structure
                  example: false
      responses:
        '200':
          description: Category updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  category:
                    $ref: '#/components/schemas/HcCategory'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
    delete:
      tags:
        - Help center categories
      summary: Delete a category or section
      description: Delete a help center category or section
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Category or section ID
          schema:
            type: integer
      responses:
        '200':
          description: Category deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /hc/categories:
    post:
      tags:
        - Help center categories
      summary: Create a new category or section
      description: Create a new help center category or section
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: Category or section name
                  example: 'Getting Started'
                description:
                  type: string
                  nullable: true
                  description: Category description
                  example: 'Learn the basics'
                image:
                  type: string
                  nullable: true
                  description: Category image URL or identifier
                  example: 'images/category.svg'
                parent_id:
                  type: integer
                  nullable: true
                  description: Parent category ID (for sections only)
                  example: 1
                visible_to_role:
                  type: integer
                  nullable: true
                  description: Role ID required to view this category
                  example: 2
                managed_by_role:
                  type: integer
                  nullable: true
                  description: Role ID required to manage this category
                  example: 3
                hide_from_structure:
                  type: boolean
                  description: Whether to hide from navigation structure
                  example: false
      responses:
        '200':
          description: Category created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  category:
                    $ref: '#/components/schemas/HcCategory'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /hc/manager/categories:
    get:
      tags:
        - Help center manager
      summary: Get root categories for manager
      description: Get list of root categories for help center management interface
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HcManagerCategoriesResponse'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /hc/manager/categories/{categoryId}/sections:
    get:
      tags:
        - Help center manager
      summary: Get sections for a category
      description: Get list of sections within a specific category for management interface
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Parent category ID
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HcManagerCategoriesResponse'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /hc/manager/sections/{sectionId}/articles:
    get:
      tags:
        - Help center manager
      summary: Get articles in a section
      description: Get list of articles within a specific section for management interface
      parameters:
        - name: sectionId
          in: path
          required: true
          description: Section ID
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HcManagerArticlesResponse'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /hc/manager/categories/reorder:
    post:
      tags:
        - Help center manager
      summary: Reorder categories or sections
      description: Update the display order of categories or sections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ids
              properties:
                ids:
                  type: array
                  items:
                    type: integer
                  description: Array of category/section IDs in the desired order
                  example: [3, 1, 5, 2, 4]
                parentId:
                  type: integer
                  nullable: true
                  description: Parent category ID (null for root categories)
                  example: 1
      responses:
        '200':
          description: Categories reordered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /hc/manager/sections/{sectionId}/articles/reorder:
    post:
      tags:
        - Help center manager
      summary: Reorder articles in a section
      description: Update the display order of articles within a section
      parameters:
        - name: sectionId
          in: path
          required: true
          description: Section ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ids
              properties:
                ids:
                  type: array
                  items:
                    type: integer
                  description: Array of article IDs in the desired order
                  example: [10, 12, 11, 13]
      responses:
        '200':
          description: Articles reordered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /hc/articles:
    get:
      tags:
        - Help center articles
      summary: List articles
      description: Get a paginated list of help center articles with optional filtering
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            example: 1
        - name: perPage
          in: query
          description: Number of items per page
          schema:
            type: integer
            example: 15
        - name: orderBy
          in: query
          description: Field to order by
          schema:
            type: string
            default: updated_at
            example: updated_at
        - name: orderDir
          in: query
          description: Order direction
          schema:
            type: string
            enum: [asc, desc]
            default: desc
            example: desc
        - name: draft
          in: query
          description: Filter by draft status
          schema:
            type: boolean
        - name: author_id
          in: query
          description: Filter by author ID
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                      last_page:
                        type: integer
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/HcArticleDatatableItem'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
    post:
      tags:
        - Help center articles
      summary: Create a new article
      description: Create a new help center article
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
                - body
              properties:
                title:
                  type: string
                  maxLength: 255
                  description: Article title
                  example: 'How to reset your password'
                body:
                  type: string
                  description: Article content (HTML)
                  example: '<p>Step 1: Click on forgot password...</p>'
                slug:
                  type: string
                  nullable: true
                  description: URL slug (auto-generated if not provided)
                  example: 'how-to-reset-password'
                draft:
                  type: boolean
                  default: false
                  description: Whether article is a draft
                  example: false
                visibility:
                  type: string
                  enum: [public, private]
                  default: public
                  description: Article visibility
                  example: public
                visible_to_role:
                  type: integer
                  nullable: true
                  description: Role ID required to view (if visibility is private)
                  example: 2
                author_id:
                  type: integer
                  nullable: true
                  description: Author user ID
                  example: 5
                managed_by_role:
                  type: integer
                  nullable: true
                  description: Role ID required to manage this article
                  example: 3
                description:
                  type: string
                  nullable: true
                  maxLength: 500
                  description: Article meta description
                  example: 'Learn how to reset your password'
                sections:
                  type: array
                  items:
                    type: integer
                  description: Array of section IDs this article belongs to
                  example: [1, 5]
                tags:
                  type: array
                  items:
                    type: string
                  description: Array of tag names
                  example: ['password', 'account']
                attachments:
                  type: array
                  maxItems: 10
                  items:
                    type: integer
                  description: Array of attachment file entry IDs
                  example: [10, 11]
      responses:
        '200':
          description: Article created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  article:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 42
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /hc/articles/{articleId}:
    get:
      tags:
        - Help center articles
      summary: Get a single article
      description: Get full details of a help center article
      parameters:
        - name: articleId
          in: path
          required: true
          description: Article ID
          schema:
            type: integer
        - name: loader
          in: query
          description: Type of data to load (articlePage for viewing, updateArticle for editing)
          schema:
            type: string
            enum: [articlePage, updateArticle]
            example: articlePage
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/HcArticlePageData'
                  - $ref: '#/components/schemas/HcUpdateArticlePageData'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
    put:
      tags:
        - Help center articles
      summary: Update an article
      description: Update an existing help center article
      parameters:
        - name: articleId
          in: path
          required: true
          description: Article ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  maxLength: 255
                  description: Article title
                  example: 'How to reset your password'
                body:
                  type: string
                  description: Article content (HTML)
                  example: '<p>Updated steps...</p>'
                slug:
                  type: string
                  nullable: true
                  description: URL slug
                  example: 'how-to-reset-password'
                draft:
                  type: boolean
                  description: Whether article is a draft
                  example: false
                visibility:
                  type: string
                  enum: [public, private]
                  description: Article visibility
                  example: public
                visible_to_role:
                  type: integer
                  nullable: true
                  description: Role ID required to view
                  example: 2
                author_id:
                  type: integer
                  nullable: true
                  description: Author user ID
                  example: 5
                managed_by_role:
                  type: integer
                  nullable: true
                  description: Role ID required to manage this article
                  example: 3
                description:
                  type: string
                  nullable: true
                  maxLength: 500
                  description: Article meta description
                  example: 'Learn how to reset your password'
                sections:
                  type: array
                  items:
                    type: integer
                  description: Array of section IDs
                  example: [1, 5]
                tags:
                  type: array
                  items:
                    type: string
                  description: Array of tag names
                  example: ['password', 'account']
                attachments:
                  type: array
                  maxItems: 10
                  items:
                    type: integer
                  description: Array of attachment file entry IDs
                  example: [10, 11]
      responses:
        '200':
          description: Article updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  article:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 42
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
    delete:
      tags:
        - Help center articles
      summary: Delete articles
      description: Delete one or more articles by IDs
      parameters:
        - name: articleId
          in: path
          required: true
          description: Comma-separated article IDs
          schema:
            type: string
            example: '1,2,3'
      responses:
        '200':
          description: Articles deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /hc/articles/{categoryId}/{sectionId}/{articleId}:
    get:
      tags:
        - Help center articles
      summary: Get article with full path
      description: Get article details using full category/section/article path
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Category ID
          schema:
            type: integer
        - name: sectionId
          in: path
          required: true
          description: Section ID
          schema:
            type: integer
        - name: articleId
          in: path
          required: true
          description: Article ID
          schema:
            type: integer
        - name: loader
          in: query
          description: Type of data to load
          schema:
            type: string
            enum: [articlePage, updateArticle]
            example: articlePage
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/HcArticlePageData'
                  - $ref: '#/components/schemas/HcUpdateArticlePageData'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /hc/articles/{articleId}/feedback:
    post:
      tags:
        - Help center articles
      summary: Submit article feedback
      description: Submit whether an article was helpful or not
      parameters:
        - name: articleId
          in: path
          required: true
          description: Article ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - wasHelpful
              properties:
                wasHelpful:
                  type: boolean
                  description: Whether the article was helpful
                  example: true
                comment:
                  type: string
                  nullable: true
                  maxLength: 500
                  description: Optional feedback comment
                  example: 'Very clear instructions'
      responses:
        '200':
          description: Feedback submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /hc/articles/{article}/download/{hashes}:
    get:
      tags:
        - Help center articles
      summary: Download article attachment
      description: Download a file attachment from an article
      parameters:
        - name: article
          in: path
          required: true
          description: Article ID
          schema:
            type: integer
        - name: hashes
          in: path
          required: true
          description: Comma-separated file hashes
          schema:
            type: string
            example: 'abc123,def456'
      responses:
        '200':
          description: File download
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /hc/articles/batch-action:
    post:
      tags:
        - Help center articles
      summary: Perform batch action on articles
      description: Perform actions on multiple articles at once (change status, visibility, etc.)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - action
                - articleIds
              properties:
                action:
                  type: string
                  enum: [changeArticleStatus, changeVisibility]
                  description: Action to perform
                  example: changeArticleStatus
                articleIds:
                  type: array
                  minItems: 1
                  items:
                    type: integer
                  description: Array of article IDs
                  example: [1, 2, 3]
                data:
                  type: object
                  description: Action-specific data
                  properties:
                    status:
                      type: string
                      enum: [draft, published]
                      description: New status (for changeArticleStatus action)
                      example: published
                    roleId:
                      type: integer
                      description: Role ID (for changeVisibility action)
                      example: 2
      responses:
        '200':
          description: Batch action completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /search/conversations:
    get:
      tags:
        - Search
      summary: Search conversations
      description: Search conversations across all views using full-text search and advanced filters. Unlike the main conversations endpoint, this provides global search capabilities without being limited to a specific view.
      parameters:
        - name: query
          in: query
          description: Full-text search query to search across conversation subjects and messages
          schema:
            type: string
            example: 'password reset issue'
        - name: filters
          in: query
          description: JSON-encoded advanced filters (same format as view conditions)
          schema:
            type: string
            example: '{"status":{"value":"open","operator":"="}}'
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            example: 1
        - name: orderBy
          in: query
          description: Field to order by
          schema:
            type: string
            example: updated_at
        - name: orderDir
          in: query
          description: Order direction
          schema:
            type: string
            enum: [asc, desc]
            example: desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                      last_page:
                        type: integer
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ConversationListItem'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /search/articles:
    get:
      tags:
        - Search
      summary: Search articles
      description: Search help center articles by query with optional category filtering
      parameters:
        - name: query
          in: query
          required: true
          description: Search query string
          schema:
            type: string
            example: 'password reset'
        - name: categoryIds
          in: query
          description: Comma-separated category IDs to filter by
          schema:
            type: string
            example: '1,2'
        - name: perPage
          in: query
          description: Number of results per page
          schema:
            type: integer
            example: 20
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchArticlesResponse'
        '401':
          $ref: '#/components/schemas/401-Response'
  /helpdesk/canned-replies:
    get:
      tags:
        - Canned replies
      summary: List canned replies
      description: Get a paginated list of saved reply templates with optional filtering
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            example: 1
        - name: perPage
          in: query
          description: Number of items per page
          schema:
            type: integer
            example: 30
            default: 30
        - name: query
          in: query
          description: Search query to filter replies
          schema:
            type: string
        - name: forCurrentUser
          in: query
          description: Filter to show only replies owned by current user or their groups
          schema:
            type: boolean
        - name: orderBy
          in: query
          description: Field to order by
          schema:
            type: string
            default: updated_at
            example: updated_at
        - name: orderDir
          in: query
          description: Order direction
          schema:
            type: string
            enum: [asc, desc]
            default: desc
            example: desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                      last_page:
                        type: integer
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/CannedReply'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
    post:
      tags:
        - Canned replies
      summary: Create a new canned reply
      description: Create a new saved reply template
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - body
                - shared
              properties:
                name:
                  type: string
                  minLength: 3
                  maxLength: 255
                  description: Name of the reply template
                  example: 'Welcome message'
                body:
                  type: string
                  minLength: 3
                  description: Content of the reply (HTML supported)
                  example: '<p>Thank you for contacting us. How can we help you today?</p>'
                shared:
                  type: boolean
                  description: Whether the reply is shared with the group
                  example: true
                groupId:
                  type: integer
                  nullable: true
                  description: Group ID if shared with specific group
                  example: 1
                attachments:
                  type: array
                  maxItems: 5
                  items:
                    type: integer
                  description: Array of file entry IDs to attach
                  example: [1, 2]
                tags:
                  type: array
                  maxItems: 10
                  items:
                    type: string
                  description: Array of tag names
                  example: ['greeting', 'general']
      responses:
        '201':
          description: Canned reply created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  cannedReply:
                    $ref: '#/components/schemas/CannedReply'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /helpdesk/canned-replies/{id}:
    get:
      tags:
        - Canned replies
      summary: Get a single canned reply
      description: Get full details of a saved reply template
      parameters:
        - name: id
          in: path
          required: true
          description: Canned reply ID
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply:
                    $ref: '#/components/schemas/CannedReply'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
    put:
      tags:
        - Canned replies
      summary: Update a canned reply
      description: Update an existing saved reply template
      parameters:
        - name: id
          in: path
          required: true
          description: Canned reply ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - body
              properties:
                name:
                  type: string
                  minLength: 3
                  maxLength: 255
                  description: Name of the reply template
                  example: 'Welcome message'
                body:
                  type: string
                  minLength: 3
                  description: Content of the reply (HTML supported)
                  example: '<p>Thank you for contacting us. How can we help you today?</p>'
                shared:
                  type: boolean
                  description: Whether the reply is shared with the group
                  example: true
                groupId:
                  type: integer
                  nullable: true
                  description: Group ID if shared with specific group
                  example: 1
                attachments:
                  type: array
                  maxItems: 5
                  items:
                    type: integer
                  description: Array of file entry IDs to attach (replaces existing attachments)
                  example: [1, 2]
                tags:
                  type: array
                  maxItems: 10
                  items:
                    type: string
                  description: Array of tag names (replaces existing tags)
                  example: ['greeting', 'general']
      responses:
        '200':
          description: Canned reply updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  cannedReply:
                    $ref: '#/components/schemas/CannedReply'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
    delete:
      tags:
        - Canned replies
      summary: Delete canned replies
      description: Delete one or more saved reply templates by IDs
      parameters:
        - name: id
          in: path
          required: true
          description: Comma-separated canned reply IDs
          schema:
            type: string
            example: '1,2,3'
      responses:
        '200':
          description: Canned replies deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /helpdesk/normalized-models/article-authors:
    get:
      tags:
        - Help center
      summary: Get article authors list
      description: Get a list of users who have authored articles (for autocomplete/dropdowns)
      parameters:
        - name: query
          in: query
          description: Search query to filter authors
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  authors:
                    type: array
                    items:
                      $ref: '#/components/schemas/HcArticleAuthor'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /helpdesk/normalized-models/article-authors/{userId}:
    get:
      tags:
        - Help center
      summary: Get a single article author
      description: Get details of a specific article author
      parameters:
        - name: userId
          in: path
          required: true
          description: User ID
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  author:
                    $ref: '#/components/schemas/HcArticleAuthor'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
  /helpdesk/normalized-models/hc-categories:
    get:
      tags:
        - Help center
      summary: Get normalized categories list
      description: Get a simplified list of categories and sections for dropdowns and filters
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  categories:
                    type: array
                    items:
                      $ref: '#/components/schemas/HcNormalizedCategory'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /hc/actions/import:
    post:
      tags:
        - Help center
      summary: Import help center data
      description: Import help center articles and categories from a ZIP file. This will erase all existing help center data.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: ZIP file containing help center data
      responses:
        '200':
          description: Data imported successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /hc/actions/export:
    get:
      tags:
        - Help center
      summary: Export help center data
      description: Export all help center articles and categories as a ZIP file
      responses:
        '200':
          description: ZIP file download
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /triggers:
    get:
      tags:
        - Triggers
      summary: List triggers
      description: Get a paginated list of automation triggers with optional filtering and sorting
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            example: 1
        - name: perPage
          in: query
          description: Number of items per page
          schema:
            type: integer
            example: 15
        - name: query
          in: query
          description: Search query to filter triggers
          schema:
            type: string
        - name: orderBy
          in: query
          description: Field to order by
          schema:
            type: string
            default: updated_at
            example: updated_at
        - name: orderDir
          in: query
          description: Order direction
          schema:
            type: string
            enum: [asc, desc]
            default: desc
            example: desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                      last_page:
                        type: integer
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Trigger'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
    post:
      tags:
        - Triggers
      summary: Create a new trigger
      description: Create a new automation trigger with conditions and actions that will execute when those conditions are met
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - conditions
                - actions
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 250
                  description: Name of the trigger
                  example: 'Auto-assign to support team'
                description:
                  type: string
                  maxLength: 250
                  nullable: true
                  description: Optional description of what this trigger does
                  example: 'Automatically assigns new tickets from premium customers to support team'
                conditions:
                  type: array
                  minItems: 1
                  description: Array of conditions that must be met for this trigger to fire
                  items:
                    $ref: '#/components/schemas/TriggerCondition'
                actions:
                  type: array
                  minItems: 1
                  description: Array of actions to perform when conditions are met
                  items:
                    $ref: '#/components/schemas/TriggerAction'
      responses:
        '200':
          description: Trigger created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  trigger:
                    $ref: '#/components/schemas/Trigger'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /triggers/config:
    get:
      tags:
        - Triggers
      summary: Get trigger configuration
      description: Get available conditions, actions, operators and their configuration options for building triggers
      responses:
        '200':
          description: Successful response with trigger configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerConfig'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /triggers/{trigger}:
    get:
      tags:
        - Triggers
      summary: Get a single trigger
      description: Get full details of a specific automation trigger including its conditions and actions
      parameters:
        - name: trigger
          in: path
          required: true
          description: Trigger ID
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  trigger:
                    $ref: '#/components/schemas/Trigger'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
    put:
      tags:
        - Triggers
      summary: Update a trigger
      description: Update an existing automation trigger's name, description, conditions, or actions
      parameters:
        - name: trigger
          in: path
          required: true
          description: Trigger ID
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - conditions
                - actions
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 250
                  description: Name of the trigger
                  example: 'Auto-assign to support team'
                description:
                  type: string
                  maxLength: 250
                  nullable: true
                  description: Optional description of what this trigger does
                  example: 'Automatically assigns new tickets from premium customers to support team'
                conditions:
                  type: array
                  minItems: 1
                  description: Array of conditions that must be met for this trigger to fire
                  items:
                    $ref: '#/components/schemas/TriggerCondition'
                actions:
                  type: array
                  minItems: 1
                  description: Array of actions to perform when conditions are met
                  items:
                    $ref: '#/components/schemas/TriggerAction'
      responses:
        '200':
          description: Trigger updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  trigger:
                    $ref: '#/components/schemas/Trigger'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
        '422':
          $ref: '#/components/schemas/422-Response'
  /triggers/{ids}:
    delete:
      tags:
        - Triggers
      summary: Delete triggers
      description: Delete one or more automation triggers by IDs
      parameters:
        - name: ids
          in: path
          required: true
          description: Comma-separated trigger IDs
          schema:
            type: string
            example: '1,2,3'
      responses:
        '204':
          description: Triggers deleted successfully
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /reports/conversations/{type}:
    get:
      tags:
        - Reports
      summary: Get conversations report
      description: Get analytics and metrics for conversations (tickets or chats) including new conversations, response times, tags, and agent performance
      parameters:
        - name: type
          in: path
          required: true
          description: Type of conversations to report on
          schema:
            type: string
            enum: [ticket, chat]
            example: ticket
        - name: startDate
          in: query
          required: true
          description: Start date of the report period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2024-01-01T00:00:00Z'
        - name: endDate
          in: query
          required: true
          description: End date of the report period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2024-01-31T23:59:59Z'
        - name: timezone
          in: query
          required: true
          description: Timezone for the report
          schema:
            type: string
            example: 'America/New_York'
        - name: compareStartDate
          in: query
          description: Start date for comparison period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2023-12-01T00:00:00Z'
        - name: compareEndDate
          in: query
          description: End date for comparison period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2023-12-31T23:59:59Z'
      responses:
        '200':
          description: Report data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationsReport'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /reports/agents:
    get:
      tags:
        - Reports
      summary: Get agents performance report
      description: Get detailed analytics and performance metrics for all agents including conversations handled, response times, and satisfaction ratings
      parameters:
        - name: startDate
          in: query
          required: true
          description: Start date of the report period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2024-01-01T00:00:00Z'
        - name: endDate
          in: query
          required: true
          description: End date of the report period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2024-01-31T23:59:59Z'
        - name: timezone
          in: query
          required: true
          description: Timezone for the report
          schema:
            type: string
            example: 'America/New_York'
        - name: compareStartDate
          in: query
          description: Start date for comparison period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2023-12-01T00:00:00Z'
        - name: compareEndDate
          in: query
          description: End date for comparison period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2023-12-31T23:59:59Z'
      responses:
        '200':
          description: Report data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentsPerformanceReport'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /reports/tags:
    get:
      tags:
        - Reports
      summary: Get tags usage report
      description: Get analytics on tag usage across conversations including most used tags and percentage of tagged conversations
      parameters:
        - name: startDate
          in: query
          required: true
          description: Start date of the report period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2024-01-01T00:00:00Z'
        - name: endDate
          in: query
          required: true
          description: End date of the report period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2024-01-31T23:59:59Z'
        - name: timezone
          in: query
          required: true
          description: Timezone for the report
          schema:
            type: string
            example: 'America/New_York'
        - name: compareStartDate
          in: query
          description: Start date for comparison period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2023-12-01T00:00:00Z'
        - name: compareEndDate
          in: query
          description: End date for comparison period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2023-12-31T23:59:59Z'
      responses:
        '200':
          description: Report data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagsReport'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /reports/search/{type}:
    get:
      tags:
        - Reports
      summary: Get help center search report
      description: Get analytics on help center searches including popular search terms, failed searches, click-through rates, and searches that resulted in tickets
      parameters:
        - name: type
          in: path
          required: true
          description: Type of search report
          schema:
            type: string
            enum: [popular, failed]
            example: popular
        - name: startDate
          in: query
          required: true
          description: Start date of the report period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2024-01-01T00:00:00Z'
        - name: endDate
          in: query
          required: true
          description: End date of the report period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2024-01-31T23:59:59Z'
        - name: timezone
          in: query
          required: true
          description: Timezone for the report
          schema:
            type: string
            example: 'America/New_York'
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            example: 1
        - name: perPage
          in: query
          description: Number of items per page
          schema:
            type: integer
            example: 15
        - name: compareStartDate
          in: query
          description: Start date for comparison period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2023-12-01T00:00:00Z'
        - name: compareEndDate
          in: query
          description: End date for comparison period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2023-12-31T23:59:59Z'
      responses:
        '200':
          description: Report data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 15
                      total:
                        type: integer
                        example: 100
                      last_page:
                        type: integer
                        example: 7
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/SearchReportItem'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
  /reports/articles:
    get:
      tags:
        - Reports
      summary: Get help center articles report
      description: Get analytics on help center articles including views, helpfulness scores, and feedback
      parameters:
        - name: startDate
          in: query
          required: true
          description: Start date of the report period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2024-01-01T00:00:00Z'
        - name: endDate
          in: query
          required: true
          description: End date of the report period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2024-01-31T23:59:59Z'
        - name: timezone
          in: query
          required: true
          description: Timezone for the report
          schema:
            type: string
            example: 'America/New_York'
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            example: 1
        - name: perPage
          in: query
          description: Number of items per page
          schema:
            type: integer
            example: 15
        - name: compareStartDate
          in: query
          description: Start date for comparison period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2023-12-01T00:00:00Z'
        - name: compareEndDate
          in: query
          description: End date for comparison period (ISO 8601 format)
          schema:
            type: string
            format: date-time
            example: '2023-12-31T23:59:59Z'
      responses:
        '200':
          description: Report data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 15
                      total:
                        type: integer
                        example: 50
                      last_page:
                        type: integer
                        example: 4
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ArticleReportItem'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'

  /auth/register:
    post:
      security: []
      tags:
        - Auth
      summary: Register for a new account
      operationId: register
      responses:
        '200':
          description: User registered
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  user:
                    $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          description: Invalid data specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422-Response'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: 'example@gmail.com'
                password:
                  type: string
                  example: password
                token_name:
                  type: string
                  example: 'iphone 12'
  /auth/login:
    post:
      security: []
      tags:
        - Auth
      summary: Get access token
      description: 'Logs in specified user and returns user object along with access token. <br><br> Access Token is a string that enables SITE_NAME to verify that a request belongs to an authorized session. This token should be sent along with every request to SITE_NAME API in a authorization header: `Authorization: Bearer <Token>`.'
      operationId: login
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  user:
                    $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          description: Invalid data specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422-Response'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: 'example@gmail.com'
                password:
                  type: string
                  example: 'password'
                device_name:
                  type: string
                  example: 'iphone 12'

  /envato/validate-purchase-code:
    post:
      tags:
        - Envato
      summary: Validate specified envato purchase code
      operationId: validatePurchaseCode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                purchase_code:
                  type: string
                  required: true
      responses:
        '200':
          description: On success, the response body contains purchse code object in JSON format
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  code:
                    $ref: '#/components/schemas/EnvatoPurchaseCode'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'

  /uploads:
    post:
      tags:
        - Uploads
      summary: Upload a file
      description: Upload a file to the server. The file will be stored and a file entry record will be created with metadata.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload
                clientMime:
                  type: string
                  description: Client-detected MIME type
                  example: 'image/png'
                clientExtension:
                  type: string
                  description: Client-detected file extension
                  example: 'png'
                uploadType:
                  type: string
                  description: Type of upload (e.g., avatar, attachment, public)
                  example: 'attachment'
                backendId:
                  type: string
                  description: Backend storage identifier
                  example: 'local'
                parentId:
                  type: integer
                  nullable: true
                  description: Parent folder ID for organizing files
                  example: null
                relativePath:
                  type: string
                  nullable: true
                  description: Relative path for file organization
                  example: null
      responses:
        '201':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  fileEntry:
                    $ref: '#/components/schemas/FileEntry'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'

  /uploads/{id}:
    get:
      tags:
        - Uploads
      summary: Get a file entry
      description: Retrieve a file entry by ID. This returns the actual file content with appropriate headers.
      parameters:
        - name: id
          in: path
          required: true
          description: File entry ID
          schema:
            type: integer
            example: 42
      responses:
        '200':
          description: File returned successfully
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
            image/*:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'

  /lc/campaigns:
    get:
      tags:
        - Campaigns
      summary: List campaigns
      description: Get a paginated list of campaigns with support for search and filtering
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            example: 1
        - name: perPage
          in: query
          description: Number of items per page
          schema:
            type: integer
            example: 15
        - name: query
          in: query
          description: Search query
          schema:
            type: string
        - name: orderBy
          in: query
          description: Field to order by
          schema:
            type: string
            example: created_at
        - name: orderDir
          in: query
          description: Order direction
          schema:
            type: string
            enum: [asc, desc]
            example: desc
        - name: filters
          in: query
          description: JSON encoded filters
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 15
                      total:
                        type: integer
                        example: 42
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Campaign'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
    post:
      tags:
        - Campaigns
      summary: Create a new campaign
      description: Create a new campaign with content items and conditions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - width
                - height
              properties:
                name:
                  type: string
                  description: Campaign name (must be unique)
                  example: 'Welcome popup'
                content:
                  type: array
                  description: Content items for the campaign
                  items:
                    $ref: '#/components/schemas/CampaignContentItem'
                conditions:
                  type: array
                  description: Conditions for when the campaign should display
                  items:
                    $ref: '#/components/schemas/CampaignCondition'
                appearance:
                  $ref: '#/components/schemas/CampaignAppearance'
                width:
                  type: number
                  description: Width of the campaign popup
                  example: 240
                height:
                  type: number
                  description: Height of the campaign popup
                  example: 156
      responses:
        '200':
          description: Campaign created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaign:
                    $ref: '#/components/schemas/Campaign'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          $ref: '#/components/schemas/422-Response'

  /lc/campaigns/{campaignId}:
    get:
      tags:
        - Campaigns
      summary: Get a campaign by ID
      description: Retrieve detailed information about a specific campaign
      parameters:
        - name: campaignId
          in: path
          required: true
          description: Campaign ID
          schema:
            type: integer
            example: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaign:
                    $ref: '#/components/schemas/Campaign'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
    put:
      tags:
        - Campaigns
      summary: Update a campaign
      description: Update an existing campaign's properties, content, or conditions
      parameters:
        - name: campaignId
          in: path
          required: true
          description: Campaign ID
          schema:
            type: integer
            example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Campaign name
                  example: 'Updated campaign name'
                enabled:
                  type: boolean
                  description: Whether the campaign is enabled
                  example: true
                content:
                  type: array
                  description: Content items for the campaign
                  items:
                    $ref: '#/components/schemas/CampaignContentItem'
                conditions:
                  type: array
                  description: Conditions for when the campaign should display
                  items:
                    $ref: '#/components/schemas/CampaignCondition'
                appearance:
                  $ref: '#/components/schemas/CampaignAppearance'
                width:
                  type: number
                  description: Width of the campaign popup
                  example: 240
                height:
                  type: number
                  description: Height of the campaign popup
                  example: 156
      responses:
        '200':
          description: Campaign updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaign:
                    $ref: '#/components/schemas/Campaign'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'
        '422':
          $ref: '#/components/schemas/422-Response'

  /lc/campaigns/{ids}:
    delete:
      tags:
        - Campaigns
      summary: Delete campaigns
      description: Delete one or more campaigns by IDs
      parameters:
        - name: ids
          in: path
          required: true
          description: Comma-separated campaign IDs
          schema:
            type: string
            example: '1,2,3'
      responses:
        '200':
          description: Campaigns deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'

  /lc/campaigns/{campaignId}/report:
    get:
      tags:
        - Campaigns
        - Reports
      summary: Get campaign report
      description: Get detailed analytics and report data for a specific campaign
      parameters:
        - name: campaignId
          in: path
          required: true
          description: Campaign ID
          schema:
            type: integer
            example: 1
        - name: startDate
          in: query
          required: true
          description: Start date for report in ISO format
          schema:
            type: string
            format: date-time
            example: '2024-01-01T00:00:00Z'
        - name: endDate
          in: query
          required: true
          description: End date for report in ISO format
          schema:
            type: string
            format: date-time
            example: '2024-01-31T23:59:59Z'
        - name: timezone
          in: query
          required: true
          description: Timezone for date range
          schema:
            type: string
            example: 'America/New_York'
        - name: country
          in: query
          description: Filter by country code
          schema:
            type: string
            example: 'US'
      responses:
        '200':
          description: Successful response with campaign report data
          content:
            application/json:
              schema:
                type: object
                properties:
                  report:
                    $ref: '#/components/schemas/CampaignReport'
                  campaign:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      name:
                        type: string
                        example: 'Welcome popup'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'

  /lc/campaign-templates:
    get:
      tags:
        - Campaigns
      summary: Get campaign templates
      description: Retrieve a list of predefined campaign templates to use as starting points for new campaigns
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  templates:
                    type: array
                    items:
                      $ref: '#/components/schemas/CampaignTemplate'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'

  /lc/reports/campaigns:
    get:
      tags:
        - Reports
      summary: Get all campaigns report
      description: Get overview analytics for all campaigns with a breakdown of top campaigns
      parameters:
        - name: startDate
          in: query
          required: true
          description: Start date for report in ISO format
          schema:
            type: string
            format: date-time
            example: '2024-01-01T00:00:00Z'
        - name: endDate
          in: query
          required: true
          description: End date for report in ISO format
          schema:
            type: string
            format: date-time
            example: '2024-01-31T23:59:59Z'
        - name: timezone
          in: query
          required: true
          description: Timezone for date range
          schema:
            type: string
            example: 'America/New_York'
        - name: country
          in: query
          description: Filter by country code
          schema:
            type: string
            example: 'US'
      responses:
        '200':
          description: Successful response with overview report
          content:
            application/json:
              schema:
                type: object
                properties:
                  overview:
                    $ref: '#/components/schemas/CampaignReport'
                  campaigns:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: 'Welcome popup'
                        impression_count:
                          type: integer
                          example: 1250
                        interaction_count:
                          type: integer
                          example: 320
                        created_at:
                          type: string
                          format: date-time
                          example: '2024-01-15T10:30:00Z'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'

components:
  schemas:
    401-Response:
      description: Unauthenticated. Either access token is not provided or is invalid.
    403-Response:
      description: Unauthorized access. You don't have permissions required to perform this operation.
    404-Response:
      description: Resource not found. Could not find a resource with specified name or ID.
    422-Response:
      description: Invalid data specified.
      type: object
      properties:
        status:
          type: string
          example: error
        message:
          type: string
          example: 'Reason for the error'
        errors:
          type: object
          properties:
            some_data_1:
              type: string
              example: Error message for data 1
            some_data_2:
              type: string
              example: Error message for data 2

    Tag:
      type: object
      description: Represents a tag that can be associated with various resources
      properties:
        id:
          type: integer
          description: Unique identifier for the tag
          example: 1
        name:
          type: string
          description: Tag name
          example: 'important'
        display_name:
          type: string
          nullable: true
          description: Display name for the tag
          example: 'Important'
        type:
          type: string
          nullable: true
          description: Type of tag
          example: 'custom'

    FileEntry:
      type: object
      description: Represents a file entry in the system with metadata and relationships
      properties:
        id:
          type: integer
          description: Unique identifier for the file entry
          example: 42
        name:
          type: string
          description: Display name of the file
          example: 'document.pdf'
        file_name:
          type: string
          description: Actual filename on disk
          example: 'a1b2c3d4e5f6.pdf'
        mime:
          type: string
          description: MIME type of the file
          example: 'application/pdf'
        extension:
          type: string
          nullable: true
          description: File extension
          example: 'pdf'
        type:
          type: string
          description: Type of file entry (file or folder)
          example: 'file'
        file_size:
          type: integer
          nullable: true
          description: Size of the file in bytes
          example: 2048576
        url:
          type: string
          description: Public URL to access the file
          example: 'https://example.com/storage/files/document.pdf'
        hash:
          type: string
          description: Unique hash identifier for the file
          example: 'a1b2c3d4e5f6g7h8'
        path:
          type: string
          description: Storage path of the file
          example: 'uploads/2024/01/document.pdf'
        public:
          type: boolean
          nullable: true
          description: Whether the file is publicly accessible
          example: false
        description:
          type: string
          nullable: true
          description: Optional description of the file
          example: 'Important document for project X'
        parent_id:
          type: integer
          nullable: true
          description: ID of parent folder (if organized in folders)
          example: null
        thumbnail:
          type: boolean
          nullable: true
          description: Whether this file has a thumbnail available
          example: true
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: Soft delete timestamp
          example: null
        created_at:
          type: string
          format: date-time
          description: Timestamp when file was uploaded
          example: '2024-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Timestamp when file entry was last updated
          example: '2024-01-15T10:30:00Z'
        tags:
          type: array
          nullable: true
          description: Tags associated with this file
          items:
            $ref: '#/components/schemas/Tag'
        users:
          type: array
          nullable: true
          description: Users associated with this file entry
          items:
            type: object
            properties:
              id:
                type: integer
                example: 1
              email:
                type: string
                example: 'user@example.com'
              owns_entry:
                type: boolean
                nullable: true
                description: Whether this user is the owner of the entry
                example: true
        parent:
          nullable: true
          description: Parent folder entry (if applicable)
          allOf:
            - $ref: '#/components/schemas/FileEntry'
        children:
          type: array
          nullable: true
          description: Child entries (if this is a folder)
          items:
            $ref: '#/components/schemas/FileEntry'

    Conversation:
      type: object
      properties:
        id:
          type: integer
          example: 1
        type:
          type: string
          enum: [ticket, chat]
          example: ticket
        subject:
          type: string
          example: 'Need help with feature X'
        status:
          type: string
          example: open
        status_id:
          type: integer
          example: 1
        user_id:
          type: integer
          example: 10
        assigned_to:
          type: integer
          nullable: true
          example: 5
        group_id:
          type: integer
          nullable: true
          example: 2
        category_id:
          type: integer
          nullable: true
          example: 3
        created_at:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2024-01-15T14:20:00Z'
        attributes:
          type: object
          description: Custom attributes

    ConversationListItem:
      type: object
      properties:
        id:
          type: integer
          example: 1
        type:
          type: string
          enum: [ticket, chat]
          example: ticket
        subject:
          type: string
          example: 'Need help with feature X'
        status:
          type: string
          example: open
        user_id:
          type: integer
          example: 10
        assigned_to:
          type: integer
          nullable: true
          example: 5
        group_id:
          type: integer
          nullable: true
          example: 2
        created_at:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2024-01-15T14:20:00Z'
        customer:
          $ref: '#/components/schemas/User'

    ConversationMessage:
      type: object
      properties:
        id:
          type: integer
          example: 1
        conversation_id:
          type: integer
          example: 1
        user_id:
          type: integer
          example: 5
        body:
          type: string
          example: 'This is the message content'
        type:
          type: string
          example: message
        created_at:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        attachments:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              url:
                type: string

    OriginalReplyEmailResponse:
      type: object
      description: Original email content with headers and body in multiple formats
      properties:
        email:
          type: object
          properties:
            headers:
              type: object
              additionalProperties:
                type: string
              description: Email headers as key-value pairs
              example:
                From: 'customer@example.com'
                To: 'support@example.com'
                Subject: 'Help with feature X'
                Date: 'Mon, 15 Jan 2024 10:30:00 +0000'
                Message-ID: '<abc123@mail.example.com>'
            body:
              type: object
              properties:
                html:
                  type: string
                  description: HTML version of the email body
                  example: '<html><body><p>This is the email content</p></body></html>'
                plain:
                  type: string
                  description: Plain text version of the email body
                  example: 'This is the email content'

    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
        email:
          type: string
          format: email
          example: 'user@example.com'
        first_name:
          type: string
          example: 'John'
        last_name:
          type: string
          example: 'Doe'
        avatar:
          type: string
          nullable: true
          example: 'https://example.com/avatar.jpg'
        created_at:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'

    FullConversationResponse:
      type: object
      properties:
        conversation:
          type: object
          properties:
            id:
              type: integer
              example: 1
            model_type:
              type: string
              example: 'conversation'
            type:
              type: string
              enum: [ticket, chat]
              example: ticket
            status_id:
              type: integer
              example: 1
            status_category:
              type: integer
              example: 1
            subject:
              type: string
              nullable: true
              example: 'Need help with feature X'
            assignee:
              type: object
              nullable: true
              properties:
                id:
                  type: integer
                  example: 5
                name:
                  type: string
                  example: 'John Agent'
                image:
                  type: string
                  example: 'https://example.com/agent.jpg'
            group:
              type: object
              nullable: true
              properties:
                id:
                  type: integer
                  example: 2
                name:
                  type: string
                  example: 'Support Team'
            rating:
              type: boolean
              nullable: true
              example: true
            created_at:
              type: string
              format: date-time
              nullable: true
              example: '2024-01-15T10:30:00Z'
            updated_at:
              type: string
              format: date-time
              nullable: true
              example: '2024-01-15T14:20:00Z'
        user:
          type: object
          properties:
            id:
              type: integer
              example: 10
            name:
              type: string
              nullable: true
              example: 'John Customer'
            email:
              type: string
              nullable: true
              example: 'customer@example.com'
            country:
              type: string
              nullable: true
              example: 'US'
            city:
              type: string
              nullable: true
              example: 'New York'
            timezone:
              type: string
              nullable: true
              example: 'America/New_York'
            tags:
              type: array
              items:
                type: string
              example: ['vip', 'premium']
            banned_at:
              type: string
              format: date-time
              nullable: true
              example: null
            bans:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1
                  expired_at:
                    type: string
                    format: date-time
                    example: '2024-02-15T10:30:00Z'
                  comment:
                    type: string
                    example: 'Temporary ban for spam'
        visits:
          type: object
          properties:
            pagination:
              type: object
              properties:
                current_page:
                  type: integer
                per_page:
                  type: integer
                total:
                  type: integer
            data:
              type: array
              items:
                $ref: '#/components/schemas/PageVisit'
        summary:
          nullable: true
          $ref: '#/components/schemas/ConversationSummary'
        session:
          nullable: true
          $ref: '#/components/schemas/CustomerSession'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/CompactAttribute'
        envatoPurchaseCodes:
          type: array
          items:
            $ref: '#/components/schemas/EnvatoPurchaseCode'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/ConversationTag'

    ConversationTag:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: 'urgent'

    CustomerSession:
      type: object
      properties:
        id:
          type: integer
          example: 1
        ip_address:
          type: string
          example: '192.168.1.1'
        platform:
          type: string
          example: 'Windows'
        browser:
          type: string
          example: 'Chrome'
        device:
          type: string
          example: 'Desktop'

    PageVisit:
      type: object
      properties:
        id:
          type: integer
          example: 1
        url:
          type: string
          example: 'https://example.com/pricing'
        title:
          type: string
          example: 'Pricing Page'
        created_at:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'

    ConversationSummary:
      type: object
      properties:
        summary:
          type: string
          example: 'Customer inquiring about pricing and features'
        sentiment:
          type: string
          example: 'neutral'
        key_points:
          type: array
          items:
            type: string
          example: ['pricing inquiry', 'feature comparison']

    Attribute:
      type: object
      description: Full attribute object used for management
      properties:
        id:
          type: integer
          example: 1
        type:
          type: string
          enum: [conversation, user, aiAgentSession]
          description: Type of entity this attribute applies to
          example: conversation
        name:
          type: string
          description: Internal attribute name
          example: 'Priority Level'
        key:
          type: string
          description: Unique key identifier (auto-generated from name)
          example: 'priority_level'
        customer_name:
          type: string
          nullable: true
          description: Customer-facing attribute name
          example: 'Priority'
        description:
          type: string
          nullable: true
          description: Internal description for agents
          example: 'Priority level for ticket routing'
        customer_description:
          type: string
          nullable: true
          description: Description shown to customers
          example: 'Select the priority of your issue'
        active:
          type: boolean
          description: Whether the attribute is active and available for use
          example: true
        format:
          type: string
          enum:
            [
              text,
              multiLineText,
              email,
              url,
              switch,
              number,
              phone,
              date,
              radioGroup,
              checkboxGroup,
              dropdown,
              rating,
            ]
          description: Input format/control type
          example: dropdown
        required:
          type: boolean
          description: Whether the attribute is required
          example: true
        internal:
          type: boolean
          description: Whether this is an internal system attribute
          example: false
        permission:
          type: string
          enum: [userCanEdit, userCanView, agentCanEdit]
          description: Who can edit this attribute
          example: agentCanEdit
        created_at:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2024-01-15T14:20:00Z'
        config:
          type: object
          nullable: true
          description: Additional configuration (e.g., options for dropdown)
          properties:
            options:
              type: array
              items:
                type: object
                properties:
                  label:
                    type: string
                    example: 'High'
                  value:
                    type: string
                    example: 'high'

    CompactAttribute:
      type: object
      description: Simplified attribute object used in forms and dropdowns
      properties:
        id:
          type: integer
          example: 1
        key:
          type: string
          description: Unique key identifier
          example: 'priority_level'
        type:
          type: string
          enum: [conversation, user, aiAgentSession]
          description: Type of entity this attribute applies to
          example: conversation
        format:
          type: string
          enum:
            [
              text,
              multiLineText,
              email,
              url,
              switch,
              number,
              phone,
              date,
              radioGroup,
              checkboxGroup,
              dropdown,
              rating,
            ]
          description: Input format/control type
          example: dropdown
        required:
          type: boolean
          description: Whether the attribute is required
          example: true
        materialized:
          type: boolean
          description: Whether the attribute is stored as a direct column in the database
          example: false
        name:
          type: string
          description: Display name (customer_name if for customer, otherwise internal name)
          example: 'Priority'
        description:
          type: string
          nullable: true
          description: Description text (customer_description if for customer)
          example: 'Select the priority of your issue'
        config:
          type: object
          nullable: true
          description: Additional configuration (e.g., options for dropdown)
          properties:
            options:
              type: array
              items:
                type: object
                properties:
                  label:
                    type: string
                    example: 'High'
                  value:
                    type: string
                    example: 'high'
        value:
          description: Current value of the attribute (only present when attribute is attached to an entity)
          nullable: true
          oneOf:
            - type: string
            - type: number
            - type: boolean
            - type: array
              items:
                type: string

    EnvatoPurchaseCode:
      type: object
      properties:
        id:
          type: integer
          example: 1
        code:
          type: string
          example: 'abc123-def456-ghi789'
        item_id:
          type: integer
          example: 123
        item_name:
          type: string
          example: 'BeDesk - Customer Support Software'
        supported_until:
          type: string
          format: date-time
          nullable: true
          example: '2024-12-31T23:59:59Z'

    ConversationStatus:
      type: object
      properties:
        id:
          type: integer
          example: 1
        label:
          type: string
          description: Status label shown to agents
          example: 'Awaiting Customer Response'
        user_label:
          type: string
          nullable: true
          description: Optional custom label shown to customers
          example: 'Waiting for your reply'
        category:
          type: integer
          enum: [3, 4, 5, 6]
          description: Status category (3=locked, 4=closed, 5=pending, 6=open)
          example: 5
        active:
          type: boolean
          description: Whether the status is active and available for use
          example: true
        internal:
          type: boolean
          description: Whether this is an internal system status
          example: false
        updated_at:
          type: string
          format: date-time
          example: '2024-01-15T14:20:00Z'

    CompactConversationStatus:
      type: object
      properties:
        id:
          type: integer
          example: 1
        label:
          type: string
          description: Status label (agent or user-facing depending on request)
          example: 'Open'
        category:
          type: integer
          enum: [3, 4, 5, 6]
          description: Status category (3=locked, 4=closed, 5=pending, 6=open)
          example: 6

    View:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          description: Name of the view
          example: 'High Priority Tickets'
        icon:
          type: string
          nullable: true
          description: Icon identifier for the view
          example: 'urgent'
        access:
          type: string
          enum: [anyone, owner, group]
          description: Access control for the view
          example: 'anyone'
        active:
          type: boolean
          description: Whether the view is active and visible
          example: true
        pinned:
          type: boolean
          description: Whether the view is pinned to sidebar
          example: true
        group_id:
          type: integer
          nullable: true
          description: Group ID if access is restricted to a group
          example: 2
        group:
          type: object
          nullable: true
          description: Group details if associated with a group
          properties:
            id:
              type: integer
              example: 2
            name:
              type: string
              example: 'Support Team'
        owner_id:
          type: integer
          nullable: true
          description: User ID of the view creator
          example: 5
        user:
          type: object
          nullable: true
          description: Owner details
          properties:
            id:
              type: integer
              example: 5
            name:
              type: string
              example: 'John Agent'
            email:
              type: string
              example: 'agent@example.com'
            image:
              type: string
              nullable: true
              example: 'https://example.com/avatar.jpg'
        description:
          type: string
          nullable: true
          description: Description of the view
          example: 'All high priority support tickets'
        conditions:
          type: array
          nullable: true
          description: Filter conditions that define what conversations appear in this view
          items:
            $ref: '#/components/schemas/ViewCondition'
        columns:
          type: array
          nullable: true
          description: Columns to display in the conversation list
          items:
            type: string
          example: ['subject', 'status', 'assigned_to', 'updated_at']
        order_by:
          type: string
          nullable: true
          description: Field to order conversations by
          example: 'updated_at'
        order_dir:
          type: string
          enum: [asc, desc]
          nullable: true
          description: Sort direction
          example: 'desc'
        internal:
          type: boolean
          description: Whether this is a system/internal view that cannot be deleted
          example: false
        updated_at:
          type: string
          format: date-time
          nullable: true
          example: '2024-01-15T14:20:00Z'

    ViewCondition:
      type: object
      description: A filter condition for a view
      properties:
        key:
          type: string
          description: The field to filter on
          example: 'status'
        operator:
          type: string
          description: Comparison operator
          enum:
            [
              '=',
              '!=',
              '>',
              '<',
              '>=',
              '<=',
              'contains',
              'doesnt_contain',
              'starts_with',
              'ends_with',
              'is_set',
              'is_not_set',
              'between',
              'in',
              'not_in',
            ]
          example: '='
        value:
          oneOf:
            - type: string
            - type: number
            - type: array
              items:
                oneOf:
                  - type: string
                  - type: number
          description: The value to compare against
          example: 'open'
        match_type:
          type: string
          enum: [all, any]
          description: Whether all or any conditions must match
          example: 'all'

    Group:
      type: object
      description: Full group object with all details
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          description: Group name
          example: 'Support Team'
        assignment_mode:
          type: string
          enum: [auto, manual]
          description: How conversations are assigned (auto or manual)
          example: 'auto'
        default:
          type: boolean
          description: Whether this is the default group
          example: false
        users:
          type: array
          description: List of agents in this group
          items:
            $ref: '#/components/schemas/GroupUser'

    GroupUser:
      type: object
      description: User object within a group with priority settings
      properties:
        id:
          type: integer
          example: 5
        name:
          type: string
          example: 'John Agent'
        image:
          type: string
          nullable: true
          example: 'https://example.com/avatar.jpg'
        role:
          type: object
          nullable: true
          properties:
            id:
              type: integer
              example: 2
            name:
              type: string
              example: 'Agent'
        conversation_priority:
          type: string
          enum: [primary, backup]
          nullable: true
          description: Agent's priority level in this group
          example: 'primary'

    GroupTableItem:
      type: object
      description: Simplified group object used in lists/tables
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: 'Support Team'
        default:
          type: boolean
          example: false
        users:
          type: array
          description: Simplified list of users in this group
          items:
            type: object
            properties:
              id:
                type: integer
                example: 5
              name:
                type: string
                example: 'John Agent'
              image:
                type: string
                example: 'https://example.com/avatar.jpg'

    Agent:
      type: object
      description: Full agent object with all details
      properties:
        id:
          type: integer
          example: 5
        name:
          type: string
          example: 'John Agent'
        email:
          type: string
          format: email
          example: 'agent@example.com'
        image:
          type: string
          nullable: true
          example: 'https://example.com/avatar.jpg'
        roles:
          type: array
          description: User roles
          items:
            type: object
            properties:
              id:
                type: integer
                example: 2
              name:
                type: string
                example: 'Agent'
        groups:
          type: array
          description: Groups this agent belongs to
          items:
            type: object
            properties:
              id:
                type: integer
                example: 1
              name:
                type: string
                example: 'Support Team'
        agent_settings:
          type: object
          description: Agent-specific configuration
          properties:
            assignment_limit:
              type: integer
              description: Maximum concurrent conversations
              example: 10
            accepts_conversations:
              type: string
              enum: [yes, no, workingHours]
              description: When agent accepts conversations
              example: 'workingHours'
            working_hours:
              type: object
              nullable: true
              description: Working hours by day
              additionalProperties:
                type: object
                properties:
                  from:
                    type: string
                    example: '09:00'
                  to:
                    type: string
                    example: '17:00'
        banned_at:
          type: string
          format: date-time
          nullable: true
          example: null
        bans:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              expired_at:
                type: string
                format: date-time
              comment:
                type: string

    AgentTableItem:
      type: object
      description: Simplified agent object used in lists/tables
      properties:
        id:
          type: integer
          example: 5
        name:
          type: string
          example: 'John Agent'
        email:
          type: string
          format: email
          example: 'agent@example.com'
        role:
          type: string
          description: Primary role name
          example: 'Agent'
        banned_at:
          type: string
          format: date-time
          nullable: true
          example: null
        last_active_at:
          type: string
          format: date-time
          nullable: true
          example: '2024-01-15T10:30:00Z'
        accepts_conversations:
          type: boolean
          description: Whether agent is accepting new conversations
          example: true

    CompactAgent:
      type: object
      description: Minimal agent object for dropdowns and real-time updates
      properties:
        id:
          type: integer
          example: 5
        name:
          type: string
          example: 'John Agent'
        email:
          type: string
          format: email
          nullable: true
          example: 'agent@example.com'
        image:
          type: string
          example: 'https://example.com/avatar.jpg'
        wasActiveRecently:
          type: boolean
          description: Whether agent was recently active
          example: true
        acceptsConversations:
          type: boolean
          description: Whether agent accepts new conversations
          example: true
        activeAssignedConversationsCount:
          type: integer
          description: Number of active conversations assigned to agent
          example: 5
        groups:
          type: array
          description: Groups this agent belongs to
          items:
            type: object
            properties:
              id:
                type: integer
                example: 1
              name:
                type: string
                example: 'Support Team'

    AgentInvite:
      type: object
      description: Agent invitation object
      properties:
        id:
          type: integer
          example: 1
        email:
          type: string
          format: email
          description: Email address that was invited
          example: 'newagent@example.com'
        role:
          type: string
          nullable: true
          description: Role name assigned to invite
          example: 'Agent'
        group:
          type: string
          nullable: true
          description: Group name assigned to invite
          example: 'Support Team'
        created_at:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'

    Customer:
      type: object
      description: Customer object as shown in lists/tables
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          nullable: true
          example: 'John Customer'
        email:
          type: string
          format: email
          example: 'customer@example.com'
        image:
          type: string
          nullable: true
          description: Avatar URL
          example: 'https://example.com/avatar.jpg'
        created_at:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2024-01-15T14:20:00Z'
        email_verified_at:
          type: string
          format: date-time
          nullable: true
          example: '2024-01-15T10:35:00Z'
        banned_at:
          type: string
          format: date-time
          nullable: true
          example: null

    CustomerProfile:
      type: object
      description: Full customer profile with detailed information
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: 'John Customer'
        email:
          type: string
          format: email
          example: 'customer@example.com'
        image:
          type: string
          nullable: true
          description: Avatar URL
          example: 'https://example.com/avatar.jpg'
        created_at:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2024-01-15T14:20:00Z'
        last_active_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of last activity
          example: '2024-01-20T18:45:00Z'
        was_active_recently:
          type: boolean
          description: Whether the customer was active recently (within last 15 minutes)
          example: true
        banned_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when customer was banned
          example: null
        ban_reason:
          type: string
          nullable: true
          description: Reason for ban if customer is banned
          example: null
        timezone:
          type: string
          description: Customer timezone
          example: 'America/New_York'
        country:
          type: string
          nullable: true
          description: ISO country code
          example: 'US'
        city:
          type: string
          nullable: true
          description: City name
          example: 'New York'
        language:
          type: string
          nullable: true
          description: Language code
          example: 'en'
        tags:
          type: array
          items:
            type: string
          description: Array of tag names assigned to customer
          example: ['vip', 'premium']
        notes:
          type: string
          nullable: true
          description: Internal notes about the customer
          example: 'Important client'
        emails:
          type: array
          items:
            type: string
            format: email
          description: Additional email addresses associated with customer
          example: ['john@example.com', 'john.doe@company.com']
        envato_purchase_codes:
          type: array
          items:
            $ref: '#/components/schemas/EnvatoPurchaseCode'
          description: Envato purchase codes associated with customer
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/CompactAttribute'
          description: Custom attribute values
        session:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/CustomerSession'
          description: Latest session information

    HcLandingPageData:
      type: object
      description: Help center landing page data with categories and articles
      properties:
        categories:
          type: array
          items:
            $ref: '#/components/schemas/HcLandingPageCategory'
          description: List of root categories with nested sections
        articles:
          type: array
          nullable: true
          items:
            type: object
            properties:
              id:
                type: integer
                example: 1
              title:
                type: string
                example: 'Getting started guide'
              body:
                type: string
                example: '<p>Welcome to our help center...</p>'
          description: Optional featured articles

    HcLandingPageCategory:
      type: object
      description: Category or section in landing page hierarchy
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: 'Getting Started'
        image:
          type: string
          nullable: true
          description: Category image URL or identifier
          example: 'images/category.svg'
        description:
          type: string
          nullable: true
          description: Category description
          example: 'Learn the basics'
        parent_id:
          type: integer
          nullable: true
          description: Parent category ID (null for root categories)
          example: null
        articles_count:
          type: integer
          description: Number of articles in this category/section
          example: 15
        hide_from_structure:
          type: boolean
          description: Whether to hide from navigation
          example: false
        sections:
          type: array
          items:
            $ref: '#/components/schemas/HcLandingPageCategory'
          description: Child sections (recursive)

    HcCategory:
      type: object
      description: Full category/section object with management details
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: 'Getting Started'
        description:
          type: string
          nullable: true
          example: 'Learn the basics'
        image:
          type: string
          nullable: true
          example: 'images/category.svg'
        is_section:
          type: boolean
          description: Whether this is a section (has parent) or category
          example: false
        parent_id:
          type: integer
          nullable: true
          description: Parent category ID
          example: null
        visible_to_role:
          type: integer
          nullable: true
          description: Role ID required to view
          example: 2
        managed_by_role:
          type: integer
          nullable: true
          description: Role ID required to manage
          example: 3
        hide_from_structure:
          type: boolean
          example: false
        articles_count:
          type: integer
          description: Number of articles
          example: 15
        sections_count:
          type: integer
          description: Number of child sections
          example: 5

    HcCategoryPageData:
      type: object
      description: Category page data for viewing a category
      properties:
        category:
          type: object
          properties:
            id:
              type: integer
              example: 1
            name:
              type: string
              example: 'Getting Started'
            image:
              type: string
              nullable: true
              example: 'images/category.svg'
            description:
              type: string
              example: 'Learn the basics'
            is_section:
              type: boolean
              example: false
            hide_from_structure:
              type: boolean
              example: false
            parent_id:
              type: integer
              nullable: true
              example: null
            parent:
              type: object
              nullable: true
              properties:
                id:
                  type: integer
                  example: 1
                name:
                  type: string
                  example: 'Documentation'
                hide_from_structure:
                  type: boolean
                  example: false
        categoryNav:
          type: array
          description: Navigation structure for sidebar
          items:
            type: object
            properties:
              id:
                type: integer
                example: 1
              name:
                type: string
                example: 'Getting Started'
              parent_id:
                type: integer
                nullable: true
                example: null
              articles:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 10
                    title:
                      type: string
                      example: 'Installation'
                    slug:
                      type: string
                      example: 'installation'

    HcManagerCategoriesResponse:
      type: object
      description: Response for manager categories/sections list
      properties:
        categories:
          type: array
          items:
            $ref: '#/components/schemas/HcManagerCategory'
          description: List of categories or sections
        category:
          type: object
          nullable: true
          description: Parent category (if viewing sections)
          properties:
            id:
              type: integer
              example: 1
            name:
              type: string
              example: 'Documentation'

    HcManagerCategory:
      type: object
      description: Category/section item in manager view
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: 'Getting Started'
        is_section:
          type: boolean
          description: Whether this is a section or category
          example: false
        parent_id:
          type: integer
          nullable: true
          example: null
        description:
          type: string
          nullable: true
          example: 'Learn the basics'
        image:
          type: string
          nullable: true
          example: 'images/category.svg'
        visible_to_role:
          type: integer
          nullable: true
          example: 2
        managed_by_role:
          type: integer
          nullable: true
          example: 3
        hide_from_structure:
          type: boolean
          example: false
        articles_count:
          type: integer
          example: 15
        sections_count:
          type: integer
          description: Number of child sections (for categories)
          example: 5

    HcManagerArticlesResponse:
      type: object
      description: Response for manager articles list in a section
      properties:
        articles:
          type: array
          items:
            $ref: '#/components/schemas/HcManagerArticle'
          description: List of articles
        section:
          type: object
          properties:
            id:
              type: integer
              example: 5
            name:
              type: string
              example: 'Installation'
        category:
          type: object
          properties:
            id:
              type: integer
              example: 1
            name:
              type: string
              example: 'Getting Started'

    HcManagerArticle:
      type: object
      description: Article item in manager view
      properties:
        id:
          type: integer
          example: 10
        title:
          type: string
          example: 'How to install'
        position:
          type: integer
          description: Display order position
          example: 1

    HcArticleDatatableItem:
      type: object
      description: Article item in datatable/list view
      properties:
        id:
          type: integer
          example: 10
        title:
          type: string
          example: 'How to reset your password'
        slug:
          type: string
          example: 'how-to-reset-password'
        draft:
          type: boolean
          description: Whether article is a draft
          example: false
        author:
          type: object
          nullable: true
          properties:
            id:
              type: integer
              example: 5
            name:
              type: string
              example: 'John Agent'
            image:
              type: string
              nullable: true
              example: 'https://example.com/avatar.jpg'
            email:
              type: string
              nullable: true
              example: 'agent@example.com'
        updated_at:
          type: string
          format: date-time
          example: '2024-01-15T14:20:00Z'
        path:
          type: array
          items:
            $ref: '#/components/schemas/HcArticlePathItem'
          description: Article path (category and section hierarchy)

    HcArticlePathItem:
      type: object
      description: Single item in article path (category or section)
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: 'Getting Started'
        is_section:
          type: boolean
          nullable: true
          example: false
        parent_id:
          type: integer
          nullable: true
          example: null
        hide_from_structure:
          type: boolean
          nullable: true
          example: false

    HcArticlePageData:
      type: object
      description: Article data for viewing (customer-facing)
      properties:
        article:
          type: object
          properties:
            id:
              type: integer
              example: 10
            path:
              type: array
              items:
                $ref: '#/components/schemas/HcArticlePathItem'
              description: Article path breadcrumb
            title:
              type: string
              example: 'How to reset your password'
            body:
              type: string
              description: Article content (HTML)
              example: '<p>Step 1: Click on forgot password...</p>'
            managed_by_role:
              type: integer
              nullable: true
              example: 3
            attachments:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1
                  name:
                    type: string
                    example: 'screenshot.png'
                  file_size:
                    type: integer
                    example: 102400
                  hash:
                    type: string
                    example: 'abc123'
        pageNav:
          type: array
          description: Navigation for article TOC (table of contents)
          items:
            type: object
            properties:
              indent:
                type: boolean
                example: false
              display_name:
                type: string
                example: 'Introduction'
              slug:
                type: string
                example: 'introduction'
              type:
                type: string
                example: 'h2'
        categoryNav:
          type: array
          description: Sidebar navigation structure
          items:
            type: object
            properties:
              id:
                type: integer
                example: 1
              name:
                type: string
                example: 'Getting Started'
              parent_id:
                type: integer
                nullable: true
                example: null
              articles:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 10
                    title:
                      type: string
                      example: 'Installation'
                    slug:
                      type: string
                      example: 'installation'
        loader:
          type: string
          enum: [articlePage]
          example: articlePage

    HcUpdateArticlePageData:
      type: object
      description: Article data for editing (agent-facing)
      properties:
        article:
          type: object
          properties:
            id:
              type: integer
              example: 10
            title:
              type: string
              example: 'How to reset your password'
            slug:
              type: string
              example: 'how-to-reset-password'
            visible_to_role:
              type: integer
              nullable: true
              example: 2
            author_id:
              type: integer
              example: 5
            managed_by_role:
              type: integer
              nullable: true
              example: 3
            sections:
              type: array
              description: Sections this article belongs to
              items:
                type: object
                properties:
                  id:
                    type: integer
                    example: 5
                  name:
                    type: string
                    example: 'Installation'
                  parent_id:
                    type: integer
                    example: 1
            tags:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1
                  name:
                    type: string
                    example: 'password'
            attachments:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1
                  name:
                    type: string
                    example: 'screenshot.png'
            draft:
              type: boolean
              example: false
            body:
              type: string
              description: Article content (HTML)
              example: '<p>Step 1: Click on forgot password...</p>'
        loader:
          type: string
          enum: [updateArticle]
          example: updateArticle

    SearchArticlesResponse:
      type: object
      description: Search results for articles
      properties:
        pagination:
          type: object
          properties:
            data:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                    example: 10
                  title:
                    type: string
                    example: 'How to reset your password'
                  slug:
                    type: string
                    example: 'how-to-reset-password'
                  updated_at:
                    type: string
                    format: date-time
                    example: '2024-01-15T14:20:00Z'
                  path:
                    type: array
                    items:
                      $ref: '#/components/schemas/HcArticlePathItem'
            per_page:
              type: integer
              example: 20
            current_page:
              type: integer
              example: 1
            from:
              type: integer
              nullable: true
              example: 1
            to:
              type: integer
              nullable: true
              example: 20
        query:
          type: string
          description: The search query string
          example: 'password reset'
        categoryIds:
          type: array
          nullable: true
          items:
            type: integer
          description: Category IDs used to filter results
          example: [1, 2]

    HcArticleAuthor:
      type: object
      description: Article author (user) for dropdowns
      properties:
        id:
          type: integer
          example: 5
        name:
          type: string
          example: 'John Agent'
        email:
          type: string
          nullable: true
          example: 'agent@example.com'
        image:
          type: string
          nullable: true
          example: 'https://example.com/avatar.jpg'

    HcNormalizedCategory:
      type: object
      description: Simplified category for dropdowns and filters
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: 'Getting Started'
        image:
          type: string
          example: 'images/category.svg'
        sections:
          type: array
          description: Child sections
          items:
            type: object
            properties:
              id:
                type: integer
                example: 5
              name:
                type: string
                example: 'Installation'
              parent_id:
                type: integer
                example: 1

    CannedReply:
      type: object
      description: Saved reply template that can be reused in conversations
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          description: Name/title of the canned reply
          example: 'Welcome message'
        description:
          type: string
          nullable: true
          description: Optional description of when to use this reply
          example: 'Use for greeting new customers'
        body:
          type: string
          description: Content of the reply (HTML)
          example: '<p>Thank you for contacting us. How can we help you today?</p>'
        shared:
          type: boolean
          description: Whether the reply is shared with a group
          example: true
        group_id:
          type: integer
          nullable: true
          description: Group ID if shared with specific group
          example: 1
        user_id:
          type: integer
          description: ID of the user who created this reply
          example: 5
        user:
          type: object
          nullable: true
          description: User who created this reply
          properties:
            id:
              type: integer
              example: 5
            name:
              type: string
              example: 'John Agent'
            image:
              type: string
              nullable: true
              example: 'https://example.com/avatar.jpg'
        attachments:
          type: array
          description: File attachments associated with this reply
          items:
            type: object
            properties:
              id:
                type: integer
                example: 1
              name:
                type: string
                example: 'attachment.pdf'
              file_name:
                type: string
                example: 'attachment.pdf'
              url:
                type: string
                example: 'https://example.com/storage/files/attachment.pdf'
              file_size:
                type: integer
                description: File size in bytes
                example: 102400
              mime:
                type: string
                example: 'application/pdf'
        tags:
          type: array
          description: Tags associated with this reply for categorization
          items:
            $ref: '#/components/schemas/CannedReplyTag'
        updated_at:
          type: string
          format: date-time
          nullable: true
          example: '2024-01-15T14:20:00Z'
        created_at:
          type: string
          format: date-time
          nullable: true
          example: '2024-01-15T10:30:00Z'

    CannedReplyTag:
      type: object
      description: Tag associated with a canned reply
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: 'greeting'
        display_name:
          type: string
          nullable: true
          example: 'Greeting'

    Trigger:
      type: object
      description: Automation trigger that performs actions when conditions are met
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          description: Name of the trigger
          example: 'Auto-assign to support team'
        description:
          type: string
          nullable: true
          description: Optional description of what this trigger does
          example: 'Automatically assigns new tickets from premium customers to support team'
        times_fired:
          type: integer
          description: Number of times this trigger has been executed
          example: 42
        created_at:
          type: string
          format: date-time
          nullable: true
          example: '2024-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          nullable: true
          example: '2024-01-15T14:20:00Z'
        config:
          type: object
          description: Trigger configuration containing conditions and actions
          properties:
            conditions:
              type: array
              description: Array of conditions that must be met for this trigger to fire
              items:
                $ref: '#/components/schemas/TriggerCondition'
            actions:
              type: array
              description: Array of actions to perform when conditions are met
              items:
                $ref: '#/components/schemas/TriggerAction'

    TriggerCondition:
      type: object
      description: A condition that must be met for a trigger to fire
      required:
        - name
        - operator
        - match_type
        - value
      properties:
        name:
          type: string
          description: The condition type identifier (e.g., 'conversation:subject', 'user:email')
          example: 'conversation:status'
        operator:
          type: string
          description: The comparison operator to use
          enum:
            [
              equals,
              not_equals,
              contains,
              not_contains,
              starts_with,
              ends_with,
              matches_regex,
              more,
              less,
              is,
              not,
              changed,
              changed_to,
              changed_from,
              not_changed,
              not_changed_to,
            ]
          example: 'equals'
        match_type:
          type: string
          enum: [all, any]
          description: Whether all or any conditions must match
          example: 'all'
        value:
          oneOf:
            - type: string
            - type: number
          description: The value to compare against
          example: 'open'

    TriggerAction:
      type: object
      description: An action to perform when trigger conditions are met
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: The action type identifier (e.g., 'change_status', 'assign_to_agent')
          example: 'assign_to_group'
        value:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: number
          description: Action-specific configuration values
          example:
            group_id: '2'

    TriggerConfig:
      type: object
      description: Configuration data for building triggers including available conditions, actions, and operators
      properties:
        actions:
          type: object
          description: Available actions that can be performed
          additionalProperties:
            type: object
            properties:
              label:
                type: string
                description: Human-readable label for the action
                example: 'Assign to group'
              input_config:
                type: object
                nullable: true
                description: Configuration for action inputs
                properties:
                  inputs:
                    type: array
                    items:
                      $ref: '#/components/schemas/TriggerActionInputConfig'
        conditions:
          type: object
          description: Available conditions that can be checked
          additionalProperties:
            $ref: '#/components/schemas/TriggerConditionConfig'
        groupedConditions:
          type: object
          description: Conditions grouped by category for easier navigation
          additionalProperties:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/TriggerConditionConfig'
        operators:
          type: object
          description: Available comparison operators
          additionalProperties:
            type: object
            properties:
              label:
                type: string
                example: 'Equals'
              type:
                type: string
                enum: [primitive, mixed]
                example: 'primitive'
        selectOptions:
          type: object
          description: Available options for select-type inputs
          additionalProperties:
            type: array
            items:
              type: object
              properties:
                name:
                  type: string
                  example: 'Open'
                value:
                  type: string
                  example: 'open'
                description:
                  type: string
                  nullable: true
                  example: 'Ticket is open'
                image:
                  type: string
                  nullable: true
                  example: 'https://example.com/icon.svg'

    TriggerConditionConfig:
      type: object
      description: Configuration for a trigger condition type
      properties:
        label:
          type: string
          description: Human-readable label for the condition
          example: 'Conversation status'
        group:
          type: string
          description: Category this condition belongs to
          example: 'Conversation'
        operators:
          type: array
          items:
            type: string
          description: List of allowed operators for this condition
          example: ['equals', 'not_equals', 'changed_to']
        time_based:
          type: boolean
          nullable: true
          description: Whether this condition is time-based (executes on schedule vs event)
          example: false
        input_config:
          oneOf:
            - $ref: '#/components/schemas/TriggerConditionTextInputConfig'
            - $ref: '#/components/schemas/TriggerConditionSelectInputConfig'

    TriggerConditionTextInputConfig:
      type: object
      description: Text input configuration for a condition
      properties:
        type:
          type: string
          enum: [text]
          example: 'text'
        input_type:
          type: string
          enum: [text, number]
          nullable: true
          description: HTML input type
          example: 'text'

    TriggerConditionSelectInputConfig:
      type: object
      description: Select input configuration for a condition
      properties:
        type:
          type: string
          enum: [select]
          example: 'select'
        select_options:
          oneOf:
            - type: string
              description: Reference to predefined options (e.g., 'conversation:status')
              example: 'conversation:status'
            - type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    example: 'High priority'
                  value:
                    type: string
                    example: 'high'
                  image:
                    type: string
                    nullable: true
                    example: 'https://example.com/icon.svg'
                  description:
                    type: string
                    nullable: true
                    example: 'High priority tickets'

    TriggerActionInputConfig:
      type: object
      description: Input configuration for a trigger action
      properties:
        name:
          type: string
          description: Input field name
          example: 'group_id'
        display_name:
          type: string
          description: Human-readable label
          example: 'Assign to group'
        type:
          type: string
          enum: [text, textarea, select]
          description: Input type
          example: 'select'
        placeholder:
          type: string
          nullable: true
          description: Placeholder text for input
          example: 'Select a group'
        default_value:
          oneOf:
            - type: string
            - type: number
          nullable: true
          description: Default value for the input
          example: '1'
        select_options:
          type: string
          nullable: true
          description: Reference to predefined select options (only for select type)

    ConversationsReport:
      type: object
      description: Comprehensive analytics report for conversations with metrics, charts, and performance data
      properties:
        newConversations:
          $ref: '#/components/schemas/ReportMetric'
          description: Time series data for new conversations with totals and percentages
        firstReplyTimes:
          type: object
          description: Distribution of first reply times
          properties:
            datasets:
              type: array
              items:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        label:
                          type: string
                          example: '0-1 hours'
                        value:
                          type: number
                          example: 45
                        percentage:
                          type: number
                          example: 0.45
                        granularity:
                          type: string
                          enum: [minutes, hours]
                          example: hours
                  average:
                    type: number
                    description: Average first reply time in seconds
                    example: 3600
            generatedAt:
              type: string
              format: date-time
              nullable: true
              example: '2024-01-31T23:59:59Z'
        busiestTimeOfDay:
          type: object
          description: Heatmap data showing busiest hours and days
          properties:
            data:
              type: array
              items:
                type: array
                items:
                  type: number
              example: [[0, 1, 2], [3, 4, 5]]
        tags:
          type: object
          description: Tag usage analytics
          properties:
            datasets:
              type: array
              items:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TagsReportDatasetItem'
            generatedAt:
              type: string
              format: date-time
              nullable: true
        taggedConversations:
          type: object
          description: Time series of tagged vs total conversations
          properties:
            datasets:
              type: array
              items:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        label:
                          type: string
                          example: '2024-01-15'
                        value:
                          type: number
                          example: 25
                  total:
                    type: number
                    description: Total conversations in period
                    example: 100
                  taggedTotal:
                    type: number
                    description: Total tagged conversations in period
                    example: 75
            generatedAt:
              type: string
              format: date-time
              nullable: true
        agents:
          $ref: '#/components/schemas/AgentsPerformanceMetric'
          description: Agent performance metrics and table data

    AgentsPerformanceReport:
      type: object
      description: Detailed agent performance report
      properties:
        agents:
          $ref: '#/components/schemas/AgentsPerformanceMetric'

    AgentsPerformanceMetric:
      type: object
      description: Agent performance metrics with comparison data
      properties:
        datasets:
          type: array
          items:
            type: object
            properties:
              data:
                type: array
                description: Per-agent performance data
                items:
                  $ref: '#/components/schemas/AgentPerformanceItem'
              totalAgentReplies:
                type: number
                description: Total replies across all agents
                example: 1250
              avgResponseTime:
                type: number
                description: Average response time in seconds across all agents
                example: 7200
              satisfaction:
                type: number
                nullable: true
                description: Overall satisfaction percentage (0-100)
                example: 85.5
              totalConversations:
                type: number
                description: Total conversations handled by all agents
                example: 450
        generatedAt:
          type: string
          format: date-time
          nullable: true
          example: '2024-01-31T23:59:59Z'

    AgentPerformanceItem:
      type: object
      description: Individual agent performance metrics
      properties:
        id:
          type: integer
          example: 5
        name:
          type: string
          example: 'John Agent'
        image:
          type: string
          nullable: true
          example: 'https://example.com/avatar.jpg'
        conversations:
          type: number
          description: Number of conversations handled
          example: 45
        replies:
          type: number
          description: Number of replies sent
          example: 125
        avgResponseTime:
          type: number
          description: Average response time in seconds
          example: 3600
        satisfaction:
          type: number
          nullable: true
          description: Satisfaction percentage (0-100)
          example: 92.5

    TagsReport:
      type: object
      description: Tag usage analytics report
      properties:
        tags:
          type: object
          description: Tag usage metrics
          properties:
            datasets:
              type: array
              items:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TagsReportDatasetItem'
            generatedAt:
              type: string
              format: date-time
              nullable: true
        taggedConversations:
          type: object
          description: Time series of tagged conversations
          properties:
            datasets:
              type: array
              items:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        label:
                          type: string
                          example: '2024-01-15'
                        value:
                          type: number
                          example: 25
                  total:
                    type: number
                    description: Total conversations
                    example: 100
                  taggedTotal:
                    type: number
                    description: Tagged conversations
                    example: 75
            generatedAt:
              type: string
              format: date-time
              nullable: true

    TagsReportDatasetItem:
      type: object
      description: Individual tag usage statistics
      properties:
        id:
          type: integer
          example: 1
        label:
          type: string
          description: Tag name
          example: 'urgent'
        value:
          type: number
          description: Number of times used
          example: 42
        percentageOfConversations:
          type: number
          description: Percentage of all conversations with this tag
          example: 15.5

    SearchReportItem:
      type: object
      description: Search term analytics item
      properties:
        id:
          type: integer
          example: 1
        term:
          type: string
          description: Search term
          example: 'password reset'
        count:
          type: string
          description: Number of times searched (string for large numbers)
          example: '156'
        ctr:
          type: number
          description: Click-through rate (0-1)
          example: 0.75
        resulted_in_ticket:
          type: number
          description: Number of searches that resulted in ticket creation
          example: 12
        last_seen:
          type: string
          format: date-time
          description: Last time this search term was used
          example: '2024-01-30T15:30:00Z'
        category:
          type: object
          nullable: true
          description: Most commonly clicked category for this search
          properties:
            id:
              type: integer
              example: 1
            name:
              type: string
              example: 'Getting Started'
            image:
              type: string
              nullable: true
              example: 'images/category.svg'

    ArticleReportItem:
      type: object
      description: Help center article analytics item
      properties:
        id:
          type: integer
          example: 10
        title:
          type: string
          example: 'How to reset your password'
        slug:
          type: string
          example: 'how-to-reset-password'
        views:
          type: number
          description: Number of views
          example: 1250
        score:
          type: number
          description: Helpfulness score percentage (0-100)
          example: 87.5
        positive_votes:
          type: number
          description: Number of positive feedback votes
          example: 105
        negative_votes:
          type: number
          description: Number of negative feedback votes
          example: 15
        path:
          type: array
          description: Article path breadcrumb
          items:
            $ref: '#/components/schemas/HcArticlePathItem'

    ReportMetric:
      type: object
      description: Generic report metric with time series and comparison data
      properties:
        datasets:
          type: array
          description: Array containing current and comparison period data
          items:
            type: object
            properties:
              data:
                type: array
                description: Time series data points
                items:
                  type: object
                  properties:
                    label:
                      type: string
                      description: Date label for data point
                      example: '2024-01-15'
                    value:
                      type: number
                      description: Value for this data point
                      example: 42
              total:
                type: number
                description: Total value for the period
                example: 1250
              solvedTotal:
                type: number
                nullable: true
                description: Total solved conversations (if applicable)
                example: 950
              solvedOnFirstReplyPercentage:
                type: number
                nullable: true
                description: Percentage solved on first reply (if applicable)
                example: 35.5
        generatedAt:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when report was generated
          example: '2024-01-31T23:59:59Z'

    Campaign:
      type: object
      description: Livechat campaign for displaying targeted messages to website visitors
      properties:
        id:
          type: integer
          description: Unique identifier for the campaign
          example: 1
        name:
          type: string
          description: Campaign name
          example: 'Welcome popup'
        width:
          type: number
          description: Width of the campaign popup in pixels
          example: 240
        height:
          type: number
          description: Height of the campaign popup in pixels
          example: 156
        enabled:
          type: boolean
          description: Whether the campaign is enabled and will be shown to visitors
          example: true
        impression_count:
          type: integer
          description: Total number of times the campaign has been displayed
          example: 1250
        interaction_count:
          type: integer
          description: Total number of times users have interacted with the campaign
          example: 320
        content:
          type: array
          description: Content items that make up the campaign display
          items:
            $ref: '#/components/schemas/CampaignContentItem'
        conditions:
          type: array
          description: Conditions that determine when and where the campaign should be displayed
          items:
            $ref: '#/components/schemas/CampaignCondition'
        appearance:
          $ref: '#/components/schemas/CampaignAppearance'
        created_at:
          type: string
          format: date-time
          description: Campaign creation timestamp
          example: '2024-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Campaign last update timestamp
          example: '2024-01-15T10:30:00Z'

    CampaignContentItem:
      type: object
      description: A content item that can be displayed in a campaign (image, text, button, etc.)
      properties:
        id:
          type: string
          description: Unique identifier for the content item
          example: 'item-123'
        type:
          type: string
          description: Type of content item
          enum: [image, text, button, messageInput, embed, agent]
          example: 'text'
        config:
          type: object
          description: Configuration specific to the content item type
          additionalProperties: true
          example:
            text: 'Welcome to our site!'
            fontSize: 16

    CampaignCondition:
      type: object
      description: A condition that determines when a campaign should be displayed
      properties:
        id:
          type: string
          description: Unique identifier for the condition
          example: 'condition-456'
        name:
          type: string
          description: Condition type name
          example: 'urlPath'
        operator:
          type: string
          description: Comparison operator
          enum:
            [
              equals,
              contains,
              startsWith,
              endsWith,
              matches,
              doesNotEqual,
              doesNotContain,
            ]
          example: 'contains'
        value:
          description: Value to compare against (can be string, number, boolean, or array)
          oneOf:
            - type: string
            - type: number
            - type: boolean
            - type: array
              items: {}
          example: '/pricing'

    CampaignAppearance:
      type: object
      description: Visual appearance configuration for a campaign
      properties:
        textColor:
          type: string
          nullable: true
          description: Text color in hex format
          example: '#ffffff'
        size:
          type: string
          nullable: true
          description: Overall size of the campaign
          enum: [sm, md, lg]
          example: 'md'
        textSize:
          type: string
          nullable: true
          description: Text size setting
          enum: [sm, md, lg]
          example: 'md'
        fontConfig:
          type: object
          nullable: true
          description: Font configuration settings
          properties:
            family:
              type: string
              example: 'Roboto'
            google:
              type: boolean
              example: true
        bgConfig:
          type: object
          nullable: true
          description: Background configuration settings
          properties:
            type:
              type: string
              enum: [color, gradient, image]
              example: 'color'
            value:
              type: string
              example: '#4CAF50'

    CampaignTemplate:
      type: object
      description: A predefined campaign template that can be used as a starting point
      properties:
        name:
          type: string
          description: Template identifier name
          example: 'welcome-popup'
        label:
          type: string
          description: Human-readable template label
          example: 'Welcome Popup'
        width:
          type: number
          description: Default width for campaigns created from this template
          example: 240
        height:
          type: number
          description: Default height for campaigns created from this template
          example: 156
        content:
          type: array
          description: Default content items for this template
          items:
            $ref: '#/components/schemas/CampaignContentItem'
        conditions:
          type: array
          description: Default conditions for this template
          items:
            $ref: '#/components/schemas/CampaignCondition'
        appearance:
          nullable: true
          description: Default appearance configuration
          allOf:
            - $ref: '#/components/schemas/CampaignAppearance'

    CampaignReport:
      type: object
      description: Analytics and metrics report for a campaign
      properties:
        impressions:
          $ref: '#/components/schemas/ReportMetric'
        devices:
          type: object
          description: Device breakdown metrics
          properties:
            datasets:
              type: array
              items:
                type: object
                properties:
                  label:
                    type: string
                    example: 'Desktop'
                  value:
                    type: number
                    example: 850
        browsers:
          type: object
          description: Browser breakdown metrics
          properties:
            datasets:
              type: array
              items:
                type: object
                properties:
                  label:
                    type: string
                    example: 'Chrome'
                  value:
                    type: number
                    example: 620
        platforms:
          type: object
          description: Platform/OS breakdown metrics
          properties:
            datasets:
              type: array
              items:
                type: object
                properties:
                  label:
                    type: string
                    example: 'Windows'
                  value:
                    type: number
                    example: 560
        countries:
          type: object
          description: Country breakdown metrics with location data
          properties:
            datasets:
              type: array
              items:
                type: object
                properties:
                  label:
                    type: string
                    description: Country name
                    example: 'United States'
                  value:
                    type: number
                    description: Count for this country
                    example: 450
                  code:
                    type: string
                    description: ISO country code
                    example: 'US'
        cities:
          type: object
          description: City breakdown metrics with location data
          properties:
            datasets:
              type: array
              items:
                type: object
                properties:
                  label:
                    type: string
                    description: City name
                    example: 'New York'
                  value:
                    type: number
                    description: Count for this city
                    example: 125
                  code:
                    type: string
                    nullable: true
                    description: City code if available
                    example: null

  securitySchemes:
    accessToken:
      type: http
      scheme: bearer
