openapi: 3.2.0
info:
  contact:
    email: hello@entergram.com
    name: Entergram
  description: Secure, workspace-scoped API for Entergram PRO. Use API keys created in Settings > Developers to access workspace metadata, accounts, contacts, groups, chats, custom fields, and tickets through a stable, documented contract.
  title: Entergram Public Chats API
  version: v1
security:
- ApiKeyAuth: []
tags:
- description: Actor-scoped chats, linked tickets, and internal chat comments keyed by Telegram chat ID.
  name: Chats
paths:
  /v1/chats:
    get:
      description: Returns active workspace chats keyed by internal chat records. Use `/chats/{chat_id}` when you want the canonical Telegram chat id contract.
      operationId: list-chats
      parameters:
      - description: Number of chats to return per page.
        explode: false
        in: query
        name: limit
        schema:
          default: 50
          description: Number of chats to return per page.
          examples:
          - 50
          format: int64
          maximum: 200
          minimum: 1
          type: integer
      - description: Zero-based offset for pagination.
        explode: false
        in: query
        name: offset
        schema:
          default: 0
          description: Zero-based offset for pagination.
          examples:
          - 0
          format: int64
          minimum: 0
          type: integer
      - description: Optional RFC3339 lower bound. Returns chats whose snapshot or last-message date is newer.
        explode: false
        in: query
        name: updated_since
        schema:
          description: Optional RFC3339 lower bound. Returns chats whose snapshot or last-message date is newer.
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatsEnvelope'
          description: OK
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Forbidden
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
      summary: List active chats for the current workspace
      tags:
      - Chats
      x-required-scopes:
      - chats.read
  /v1/chats/{chat_id}:
    get:
      description: Returns the canonical workspace chat view, including invite-link metadata, linked-ticket counters, and latest internal chat-comment summary.
      operationId: get-chat
      parameters:
      - description: Canonical Telegram chat identifier.
        in: path
        name: chat_id
        required: true
        schema:
          description: Canonical Telegram chat identifier.
          examples:
          - '-1000001234567'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatEnvelope'
          description: OK
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Forbidden
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Not Found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
      summary: Get a chat by Telegram chat id
      tags:
      - Chats
      x-required-scopes:
      - chats.read
  /v1/chats/{chat_id}/comments:
    get:
      description: Returns internal workspace comments attached to the Telegram chat id in ascending chronological order.
      operationId: list-chat-comments
      parameters:
      - description: Canonical Telegram chat identifier.
        in: path
        name: chat_id
        required: true
        schema:
          description: Canonical Telegram chat identifier.
          examples:
          - '-1000001234567'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCommentsEnvelope'
          description: OK
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Forbidden
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Not Found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
      summary: List internal chat comments
      tags:
      - Chats
      x-required-scopes:
      - chats.read
    post:
      description: Creates a plain-text internal note authored by the API key creator.
      operationId: create-chat-comment
      parameters:
      - description: Canonical Telegram chat identifier.
        in: path
        name: chat_id
        required: true
        schema:
          description: Canonical Telegram chat identifier.
          examples:
          - '-1000001234567'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCommentBody'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCommentEnvelope'
          description: Created
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Request
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Forbidden
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Not Found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
      summary: Create an internal chat comment
      tags:
      - Chats
      x-required-scopes:
      - chats.write
  /v1/chats/{chat_id}/comments/{comment_id}:
    delete:
      description: Deletes a chat comment. The author can delete their own comment, and workspace admins can delete any chat comment.
      operationId: delete-chat-comment
      parameters:
      - description: Canonical Telegram chat identifier.
        in: path
        name: chat_id
        required: true
        schema:
          description: Canonical Telegram chat identifier.
          examples:
          - '-1000001234567'
          type: string
      - description: Chat comment identifier.
        in: path
        name: comment_id
        required: true
        schema:
          description: Chat comment identifier.
          examples:
          - chat_comment_demo_123
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatDeletedEnvelope'
          description: OK
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Forbidden
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Not Found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
      summary: Delete an internal chat comment
      tags:
      - Chats
      x-required-scopes:
      - chats.write
    patch:
      description: Updates a chat comment. Only the original author can edit a chat comment.
      operationId: update-chat-comment
      parameters:
      - description: Canonical Telegram chat identifier.
        in: path
        name: chat_id
        required: true
        schema:
          description: Canonical Telegram chat identifier.
          examples:
          - '-1000001234567'
          type: string
      - description: Chat comment identifier.
        in: path
        name: comment_id
        required: true
        schema:
          description: Chat comment identifier.
          examples:
          - chat_comment_demo_123
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCommentBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCommentEnvelope'
          description: OK
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Request
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Forbidden
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Not Found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
      summary: Update an internal chat comment
      tags:
      - Chats
      x-required-scopes:
      - chats.write
  /v1/chats/{chat_id}/tickets:
    get:
      description: Returns workspace tickets linked to the provided Telegram chat id. This is the reverse relation for `linkedChatIds` on ticket responses.
      operationId: list-chat-linked-tickets
      parameters:
      - description: Canonical Telegram chat identifier.
        in: path
        name: chat_id
        required: true
        schema:
          description: Canonical Telegram chat identifier.
          examples:
          - '-1000001234567'
          type: string
      - description: Number of linked tickets to return.
        explode: false
        in: query
        name: limit
        schema:
          default: 50
          description: Number of linked tickets to return.
          examples:
          - 50
          format: int64
          maximum: 200
          minimum: 1
          type: integer
      - description: Zero-based offset for pagination.
        explode: false
        in: query
        name: offset
        schema:
          default: 0
          description: Zero-based offset for pagination.
          examples:
          - 0
          format: int64
          minimum: 0
          type: integer
      - description: Optional status filter applied after chat linkage.
        explode: false
        in: query
        name: status
        schema:
          description: Optional status filter applied after chat linkage.
          examples:
          - OPEN
          type: string
      - description: Optional priority filter applied after chat linkage.
        explode: false
        in: query
        name: priority
        schema:
          description: Optional priority filter applied after chat linkage.
          examples:
          - HIGH
          type: string
      - description: Case-insensitive search over linked tickets.
        explode: false
        in: query
        name: search
        schema:
          description: Case-insensitive search over linked tickets.
          examples:
          - onboarding
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkedTicketsEnvelope'
          description: OK
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Forbidden
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Not Found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
      summary: List tickets linked to a chat
      tags:
      - Chats
      x-required-scopes:
      - tickets.read
components:
  schemas:
    ChatCommentSummary:
      additionalProperties: false
      properties:
        attachmentCount:
          description: Number of attachments stored for this comment.
          examples:
          - 0
          format: int64
          type: integer
        author:
          $ref: '#/components/schemas/TicketUserSummary'
          description: Author of the chat comment.
        body:
          description: Internal chat comment body.
          examples:
          - Escalated to the sample operations queue.
          type: string
        createdAt:
          description: Comment creation timestamp.
          format: date-time
          type: string
        id:
          description: Chat comment identifier.
          examples:
          - chat_comment_demo_123
          type: string
        telegramChatId:
          description: Canonical Telegram chat identifier.
          examples:
          - '-1000001234567'
          type: string
        updatedAt:
          description: Comment last update timestamp.
          format: date-time
          type: string
      required:
      - id
      - telegramChatId
      - body
      - createdAt
      - updatedAt
      - attachmentCount
      - author
      type: object
    ChatDetail:
      additionalProperties: false
      properties:
        commentCount:
          description: Number of internal workspace comments attached to the chat.
          examples:
          - 2
          format: int64
          type: integer
        connectedAccount:
          $ref: '#/components/schemas/ChatConnectedAccountSummary'
          description: Connected account that currently owns this chat row.
        description:
          description: Telegram description or bio cached for the chat.
          examples:
          - Synthetic example chat for API documentation.
          type:
          - string
          - 'null'
        id:
          description: Internal chat record identifier for the selected workspace instance.
          examples:
          - chat_demo_123
          type: string
        inviteLink:
          description: Most recently cached invite link for the chat.
          examples:
          - https://t.me/+sampleinvite123
          type:
          - string
          - 'null'
        inviteLinkUpdatedAt:
          description: Timestamp of the last invite-link refresh.
          format: date-time
          type:
          - string
          - 'null'
        lastCommentAt:
          description: Timestamp of the latest internal chat comment.
          format: date-time
          type:
          - string
          - 'null'
        lastCommentBody:
          description: Latest internal comment body for the chat.
          examples:
          - Synthetic note for documentation only.
          type:
          - string
          - 'null'
        lastMessage:
          $ref: '#/components/schemas/ChatLastMessage'
          description: Complete canonical latest-message tuple. Existing flat fields remain for compatibility.
        lastMessageDate:
          description: Timestamp of the most recent message.
          format: date-time
          type:
          - string
          - 'null'
        lastMessageText:
          description: Most recent message preview captured for the chat.
          examples:
          - Please review the sample request.
          type:
          - string
          - 'null'
        lastMessageTimestamp:
          description: Telegram message timestamp of the latest message.
          examples:
          - 1774728948
          format: int64
          type:
          - integer
          - 'null'
        membersCount:
          description: Cached member count for groups/channels.
          examples:
          - 245
          format: int64
          type:
          - integer
          - 'null'
        name:
          description: Best available display name for the chat.
          examples:
          - Support Queue Alpha
          type: string
        openTicketCount:
          description: Number of linked tickets not in CLOSED status.
          examples:
          - 2
          format: int64
          type: integer
        photoUrl:
          description: Cached avatar or group photo URL.
          examples:
          - https://cdn.example.test/chat-photo.png
          type:
          - string
          - 'null'
        status:
          description: Lifecycle status of the chat record.
          examples:
          - active
          type: string
        telegramId:
          description: Canonical Telegram chat identifier used by Public API endpoints.
          examples:
          - '-1000001234567'
          type: string
        telegramUsername:
          description: Telegram username for the chat when available.
          examples:
          - samplecommunity
          type:
          - string
          - 'null'
        ticketCount:
          description: Number of tickets linked to the chat.
          examples:
          - 3
          format: int64
          type: integer
        title:
          description: Raw Telegram title for groups/channels.
          examples:
          - Community Alpha
          type:
          - string
          - 'null'
        type:
          description: Chat type.
          examples:
          - group
          type: string
        unreadCount:
          description: Unread message count for the connected account context.
          examples:
          - 4
          format: int64
          type:
          - integer
          - 'null'
        updatedAt:
          description: Last time the chat record changed in frontend DB.
          format: date-time
          type: string
        username:
          description: Workspace-level username alias when available.
          examples:
          - support_queue_alpha
          type:
          - string
          - 'null'
      required:
      - inviteLink
      - inviteLinkUpdatedAt
      - commentCount
      - ticketCount
      - openTicketCount
      - lastCommentBody
      - lastCommentAt
      - id
      - name
      - username
      - type
      - status
      - telegramId
      - telegramUsername
      - title
      - description
      - photoUrl
      - membersCount
      - lastMessageText
      - lastMessageDate
      - lastMessageTimestamp
      - lastMessage
      - unreadCount
      - updatedAt
      - connectedAccount
      type: object
    ChatDeletedResource:
      additionalProperties: false
      properties:
        id:
          description: Deleted resource identifier.
          examples:
          - chat_comment_demo_123
          type: string
      required:
      - id
      type: object
    ChatSummary:
      additionalProperties: false
      properties:
        connectedAccount:
          $ref: '#/components/schemas/ChatConnectedAccountSummary'
          description: Connected account that currently owns this chat row.
        description:
          description: Telegram description or bio cached for the chat.
          examples:
          - Synthetic example chat for API documentation.
          type:
          - string
          - 'null'
        id:
          description: Internal chat record identifier for the selected workspace instance.
          examples:
          - chat_demo_123
          type: string
        lastMessage:
          $ref: '#/components/schemas/ChatLastMessage'
          description: Complete canonical latest-message tuple. Existing flat fields remain for compatibility.
        lastMessageDate:
          description: Timestamp of the most recent message.
          format: date-time
          type:
          - string
          - 'null'
        lastMessageText:
          description: Most recent message preview captured for the chat.
          examples:
          - Please review the sample request.
          type:
          - string
          - 'null'
        lastMessageTimestamp:
          description: Telegram message timestamp of the latest message.
          examples:
          - 1774728948
          format: int64
          type:
          - integer
          - 'null'
        membersCount:
          description: Cached member count for groups/channels.
          examples:
          - 245
          format: int64
          type:
          - integer
          - 'null'
        name:
          description: Best available display name for the chat.
          examples:
          - Support Queue Alpha
          type: string
        photoUrl:
          description: Cached avatar or group photo URL.
          examples:
          - https://cdn.example.test/chat-photo.png
          type:
          - string
          - 'null'
        status:
          description: Lifecycle status of the chat record.
          examples:
          - active
          type: string
        telegramId:
          description: Canonical Telegram chat identifier used by Public API endpoints.
          examples:
          - '-1000001234567'
          type: string
        telegramUsername:
          description: Telegram username for the chat when available.
          examples:
          - samplecommunity
          type:
          - string
          - 'null'
        title:
          description: Raw Telegram title for groups/channels.
          examples:
          - Community Alpha
          type:
          - string
          - 'null'
        type:
          description: Chat type.
          examples:
          - group
          type: string
        unreadCount:
          description: Unread message count for the connected account context.
          examples:
          - 4
          format: int64
          type:
          - integer
          - 'null'
        updatedAt:
          description: Last time the chat record changed in frontend DB.
          format: date-time
          type: string
        username:
          description: Workspace-level username alias when available.
          examples:
          - support_queue_alpha
          type:
          - string
          - 'null'
      required:
      - id
      - name
      - username
      - type
      - status
      - telegramId
      - telegramUsername
      - title
      - description
      - photoUrl
      - membersCount
      - lastMessageText
      - lastMessageDate
      - lastMessageTimestamp
      - lastMessage
      - unreadCount
      - updatedAt
      - connectedAccount
      type: object
    TicketUserSummary:
      additionalProperties: false
      properties:
        displayName:
          description: Preferred display name for the member.
          examples:
          - Alex Example
          type:
          - string
          - 'null'
        email:
          description: Workspace member email when available.
          examples:
          - alex@example.test
          type:
          - string
          - 'null'
        id:
          description: Workspace member identifier.
          examples:
          - user_demo_123
          type: string
      required:
      - id
      - displayName
      - email
      type: object
    ChatsList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/ChatSummary'
          type:
          - array
          - 'null'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - items
      - pagination
      type: object
    ChatCommentsList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/ChatCommentSummary'
          type:
          - array
          - 'null'
      required:
      - items
      type: object
    Pagination:
      additionalProperties: false
      properties:
        hasMore:
          type: boolean
        limit:
          format: int64
          type: integer
        nextOffset:
          format: int64
          type:
          - integer
          - 'null'
        offset:
          format: int64
          type: integer
        total:
          format: int64
          type: integer
      required:
      - limit
      - offset
      - total
      - hasMore
      - nextOffset
      type: object
    ChatEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/ChatDetail'
      required:
      - data
      type: object
    ChatDeletedEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/ChatDeletedResource'
      required:
      - data
      type: object
    TicketCustomFieldSummary:
      additionalProperties: false
      properties:
        columnKey:
          description: Stable custom field key.
          examples:
          - source_campaign
          type: string
        value:
          description: Raw JSON value stored for the custom field.
      required:
      - columnKey
      - value
      type: object
    ChatCommentEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/ChatCommentSummary'
      required:
      - data
      type: object
    ChatConnectedAccountSummary:
      additionalProperties: false
      properties:
        color:
          description: Optional UI color associated with the connected account.
          examples:
          - '#2563eb'
          type:
          - string
          - 'null'
        displayName:
          description: Operator-facing label for the connected account.
          examples:
          - Ops Sample
          type:
          - string
          - 'null'
        id:
          description: Connected account identifier.
          examples:
          - acct_demo_123
          type: string
        username:
          description: Telegram username of the connected account.
          examples:
          - ops_sample
          type:
          - string
          - 'null'
      required:
      - id
      - username
      - displayName
      - color
      type: object
    ChatCommentsEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/ChatCommentsList'
      required:
      - data
      type: object
    LinkedTicketsList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/TicketSummary'
          type:
          - array
          - 'null'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - items
      - pagination
      type: object
    TicketSummary:
      additionalProperties: false
      properties:
        assignedTo:
          $ref: '#/components/schemas/TicketUserSummary'
          description: Workspace member assigned to the ticket.
        attachmentCount:
          description: Total number of ticket attachments.
          examples:
          - 1
          format: int64
          type: integer
        closedAt:
          description: Closing timestamp when the ticket is completed.
          format: date-time
          type:
          - string
          - 'null'
        closedBy:
          $ref: '#/components/schemas/TicketUserSummary'
          description: Workspace member who closed the ticket.
        comment:
          description: Optional short operator note stored directly on the ticket.
          examples:
          - Sample escalation note
          type:
          - string
          - 'null'
        commentCount:
          description: Total number of ticket comments.
          examples:
          - 3
          format: int64
          type: integer
        createdAt:
          description: Ticket creation timestamp.
          format: date-time
          type: string
        createdBy:
          $ref: '#/components/schemas/TicketUserSummary'
          description: Workspace member that created the ticket.
        customFields:
          description: Workspace ticket custom field values.
          items:
            $ref: '#/components/schemas/TicketCustomFieldSummary'
          type:
          - array
          - 'null'
        date:
          description: Optional business date associated with the ticket.
          format: date-time
          type:
          - string
          - 'null'
        description:
          description: Long-form ticket description.
          examples:
          - Synthetic customer asked for a follow-up next week.
          type:
          - string
          - 'null'
        displayId:
          description: Human-facing numbered ticket identifier.
          examples:
          - '#42'
          type: string
        id:
          description: Ticket identifier.
          examples:
          - ticket_demo_123
          type: string
        legacyTicketHash:
          description: Previous random ticket hash retained for lookup compatibility.
          examples:
          - '#TKT-001'
          type: string
        linkedChatIds:
          description: Telegram chat identifiers currently linked to the ticket.
          items:
            type: string
          type:
          - array
          - 'null'
        priority:
          description: Priority label.
          examples:
          - HIGH
          type: string
        status:
          description: Current workflow status.
          examples:
          - OPEN
          type: string
        ticketHash:
          description: Deprecated compatibility alias for displayId.
          examples:
          - '#42'
          type:
          - string
          - 'null'
        ticketNumber:
          description: Workspace-scoped human-facing ticket number.
          examples:
          - 42
          format: int64
          type: integer
        title:
          description: Ticket title.
          examples:
          - Review onboarding request
          type: string
        updatedAt:
          description: Ticket last update timestamp.
          format: date-time
          type: string
        userId:
          description: Owner user identifier in the frontend database.
          examples:
          - user_demo_123
          type: string
        workspaceId:
          description: Workspace identifier owning the ticket.
          examples:
          - workspace_demo_123
          type:
          - string
          - 'null'
      required:
      - id
      - ticketNumber
      - displayId
      - ticketHash
      - title
      - description
      - status
      - priority
      - comment
      - date
      - createdAt
      - updatedAt
      - closedAt
      - userId
      - workspaceId
      - commentCount
      - attachmentCount
      - linkedChatIds
      - customFields
      - createdBy
      - assignedTo
      - closedBy
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    ChatsEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/ChatsList'
      required:
      - data
      type: object
    ChatCommentBody:
      additionalProperties: false
      properties:
        body:
          description: Plain-text internal note for the chat.
          examples:
          - Synthetic account. Route billing questions to the assigned owner.
          minLength: 1
          type: string
      required:
      - body
      type: object
    ChatLastMessage:
      additionalProperties: false
      properties:
        date:
          description: Canonical timestamp of the latest message.
          format: date-time
          type:
          - string
          - 'null'
        id:
          description: Telegram message identifier for the canonical latest message.
          examples:
          - '123456'
          type:
          - string
          - 'null'
        isOut:
          description: True when the sender can be authoritatively matched to the connected Telegram account; null when direction is unknown.
          type:
          - boolean
          - 'null'
        sender:
          $ref: '#/components/schemas/ChatLastMessageSender'
          description: Canonical sender identity when available.
        text:
          description: Most recent message preview already stored on the chat snapshot.
          examples:
          - Please review the sample request.
          type:
          - string
          - 'null'
        timestamp:
          description: Telegram timestamp of the latest message.
          examples:
          - 1774728948
          format: int64
          type:
          - integer
          - 'null'
      required:
      - id
      - text
      - date
      - timestamp
      - isOut
      - sender
      type: object
    LinkedTicketsEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/LinkedTicketsList'
      required:
      - data
      type: object
    ChatLastMessageSender:
      additionalProperties: false
      properties:
        displayName:
          description: Best available sender display name from the canonical snapshot.
          examples:
          - David Hngr
          type:
          - string
          - 'null'
        id:
          description: Telegram sender identifier when the canonical snapshot exposed it.
          examples:
          - '580876383'
          type:
          - string
          - 'null'
      required:
      - id
      - displayName
      type: object
    ErrorModel:
      additionalProperties: false
      properties:
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          examples:
          - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
          - array
          - 'null'
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          examples:
          - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
          - 400
          format: int64
          type: integer
        title:
          description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
          examples:
          - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
          - https://example.com/errors/example
          format: uri
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Workspace-scoped PRO API key created in Entergram Settings > Developers.
      in: header
      name: X-API-Key
      type: apiKey
x-entergram-scopes:
- workspace.read
- members.read
- accounts.read
- contacts.read
- chats.read
- chats.write
- messages.read
- messages.write
- custom_fields.read
- custom_fields.write
- tickets.read
- tickets.write
- events.read
- webhooks.read
- webhooks.write