Entergram Workspace Chats API

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 Workspace Chats API
  version: v1
security:
- ApiKeyAuth: []
tags:
- description: Shared CRM chat view from frontend DB, deduplicated across workspace accounts and suited for metadata, custom fields, and ticket workflows.
  name: Workspace Chats
paths:
  /v1/workspace/chats:
    get:
      description: Returns the shared CRM chat view from Entergram frontend DB, deduplicated by canonical Telegram chat id across workspace accounts. Use this for priority, email, tickets, comments, and custom-field workflows. This is not the live Telegram transport view.
      operationId: list-workspace-chats
      parameters:
      - description: Number of shared workspace chat rows to return per page.
        explode: false
        in: query
        name: limit
        schema:
          default: 50
          description: Number of shared workspace chat rows 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/WorkspaceChatsEnvelope'
          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 shared workspace CRM chats
      tags:
      - Workspace Chats
      x-required-scopes:
      - chats.read
      - members.read
  /v1/workspace/chats/{chat_id}:
    get:
      description: Returns the shared CRM chat detail from Entergram frontend DB for a canonical Telegram chat id. Prefer this over `/live/chats` when you need workspace metadata, ticket counts, comments, or custom-field context.
      operationId: get-workspace-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/WorkspaceChatEnvelope'
          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 shared workspace CRM chat
      tags:
      - Workspace Chats
      x-required-scopes:
      - chats.read
      - members.read
    patch:
      description: Applies a partial update to the shared CRM chat row in frontend DB for the canonical Telegram chat id. Changes propagate across workspace copies of the same chat. Send empty strings to clear scalar fields.
      operationId: update-workspace-chat
      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/UpdateChatBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceChatEnvelope'
          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 shared workspace CRM chat metadata
      tags:
      - Workspace Chats
      x-required-scopes:
      - chats.write
      - members.read
  /v1/workspace/chats/{chat_id}/assignment:
    patch:
      description: Updates the assignee for one exact connected-account and Telegram-chat pair. Send an empty assignedToUserId to unassign. This uses the same WorkspaceChatAssignment model as the Entergram CRM assignee field and filters.
      operationId: update-workspace-chat-assignment
      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/UpdateChatAssignmentBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceChatAssignmentEnvelope'
          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: Assign or unassign a workspace chat
      tags:
      - Workspace Chats
      x-required-scopes:
      - chats.write
      - members.read
components:
  schemas:
    WorkspaceChatEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/ChatDetail'
      required:
      - data
      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
    WorkspaceChatAssignment:
      additionalProperties: false
      properties:
        assignedByUserId:
          description: Workspace member user id that last changed the assignment.
          examples:
          - 00000000-0000-4000-8000-000000000002
          type:
          - string
          - 'null'
        assignedToUserId:
          description: Workspace member user id assigned to the chat.
          examples:
          - 00000000-0000-4000-8000-000000000001
          type: string
        connectedAccountId:
          description: Connected account that owns this assignment.
          examples:
          - acct_demo_123
          type: string
        telegramId:
          description: Canonical Telegram chat identifier.
          examples:
          - '-1000001234567'
          type: string
        updatedAt:
          description: Timestamp of the latest assignment change.
          format: date-time
          type: string
      required:
      - connectedAccountId
      - telegramId
      - assignedToUserId
      - assignedByUserId
      - updatedAt
      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
    WorkspaceChatAssignmentResult:
      additionalProperties: false
      properties:
        assignment:
          $ref: '#/components/schemas/WorkspaceChatAssignment'
        connectedAccountId:
          type: string
        telegramId:
          type: string
      required:
      - connectedAccountId
      - telegramId
      - assignment
      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
    UpdateChatBody:
      additionalProperties: false
      properties:
        email:
          description: Workspace CRM email for the chat. Send an empty string to clear it.
          examples:
          - alex@example.com
          type: string
        phoneNumber:
          description: Workspace CRM phone number for the chat. Send an empty string to clear it.
          examples:
          - '+48123123123'
          type: string
        priority:
          description: Workspace CRM priority label. Send an empty string to clear it.
          examples:
          - High
          type: string
        telegramFirstName:
          description: Workspace override for Telegram first name. Send an empty string to clear it.
          examples:
          - Alex
          type: string
        telegramLastName:
          description: Workspace override for Telegram last name. Send an empty string to clear it.
          examples:
          - Johnson
          type: string
      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
    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
    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
    WorkspaceChatsEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/WorkspaceChatsList'
      required:
      - data
      type: object
    UpdateChatAssignmentBody:
      additionalProperties: false
      properties:
        assignedToUserId:
          description: Workspace member user id to assign. Send an empty string to unassign.
          examples:
          - 00000000-0000-4000-8000-000000000001
          type: string
        connectedAccountId:
          description: Connected account id for the exact workspace chat occurrence.
          examples:
          - acct_demo_123
          minLength: 1
          type: string
      required:
      - connectedAccountId
      - assignedToUserId
      type: object
    WorkspaceChatsList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/ChatSummary'
          type:
          - array
          - 'null'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - items
      - pagination
      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
    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
    WorkspaceChatAssignmentEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/WorkspaceChatAssignmentResult'
      required:
      - data
      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