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 Messages API
  version: v1
security:
- ApiKeyAuth: []
tags:
- description: Telegram message history and message write operations scoped to an explicit account and chat.
  name: Messages
paths:
  /v1/chats/{chat_id}/messages:
    get:
      description: Returns message history for the given chat as seen by the selected connected account.
      operationId: list-chat-messages
      parameters:
      - description: Canonical Telegram chat identifier.
        in: path
        name: chat_id
        required: true
        schema:
          description: Canonical Telegram chat identifier.
          examples:
          - '-1000001234567'
          type: string
      - description: Connected account id from the accounts endpoint used to scope the chat history request.
        explode: false
        in: query
        name: account_id
        schema:
          description: Connected account id from the accounts endpoint used to scope the chat history request.
          examples:
          - acct_demo_123
          type: string
      - description: Number of messages to return.
        explode: false
        in: query
        name: limit
        schema:
          default: 50
          description: Number of messages to return.
          examples:
          - 50
          format: int64
          maximum: 100
          minimum: 1
          type: integer
      - description: Fetch messages older than this Telegram message id.
        explode: false
        in: query
        name: before_message_id
        schema:
          description: Fetch messages older than this Telegram message id.
          examples:
          - 123456
          format: int64
          type: integer
      - description: Reserved for forum topics. Not supported yet.
        explode: false
        in: query
        name: thread_id
        schema:
          description: Reserved for forum topics. Not supported yet.
          examples:
          - 77
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessagesPageEnvelope'
          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
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Too Many Requests
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Gateway
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Service Unavailable
        '504':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Gateway Timeout
      summary: List Telegram messages for a chat and account
      tags:
      - Messages
      x-required-scopes:
      - messages.read
    post:
      description: Sends a Telegram message using the chosen connected account. The destination may be an existing canonical chat id or a public Telegram username resolved live by that account.
      operationId: create-chat-message
      parameters:
      - description: Canonical Telegram chat identifier or public Telegram username for a new direct conversation.
        in: path
        name: chat_id
        required: true
        schema:
          description: Canonical Telegram chat identifier or public Telegram username for a new direct conversation.
          examples:
          - '@alex_example'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessageBody'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResultEnvelope'
          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
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Conflict
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Too Many Requests
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Gateway
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Service Unavailable
        '504':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Gateway Timeout
      summary: Send a Telegram message
      tags:
      - Messages
      x-required-scopes:
      - messages.write
  /v1/chats/{chat_id}/messages/forward:
    post:
      description: Forwards one or more messages from a source chat into the destination chat in the path.
      operationId: forward-chat-messages
      parameters:
      - description: Canonical Telegram destination chat identifier.
        in: path
        name: chat_id
        required: true
        schema:
          description: Canonical Telegram destination chat identifier.
          examples:
          - '-1000001234567'
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForwardMessagesBody'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResultEnvelope'
          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
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Conflict
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Too Many Requests
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Gateway
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Service Unavailable
        '504':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Gateway Timeout
      summary: Forward Telegram messages into a destination chat
      tags:
      - Messages
      x-required-scopes:
      - messages.write
  /v1/chats/{chat_id}/messages/media:
    post:
      description: Sends one or more previously uploaded media payloads into the selected chat.
      operationId: create-chat-media-message
      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/CreateMediaMessageBody'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResultEnvelope'
          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
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Conflict
        '413':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Request Entity Too Large
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Too Many Requests
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Gateway
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Service Unavailable
        '504':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Gateway Timeout
      summary: Send uploaded Telegram media
      tags:
      - Messages
      x-required-scopes:
      - messages.write
  /v1/chats/{chat_id}/messages/media/uploads:
    post:
      description: Reserves one or more temporary media upload slots for a chat and connected account.
      operationId: create-chat-media-upload-tickets
      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/CreateMediaUploadTicketsBody'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaUploadTicketsEnvelope'
          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
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Conflict
        '413':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Request Entity Too Large
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Too Many Requests
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Gateway
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Service Unavailable
        '504':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Gateway Timeout
      summary: Create upload tickets for Telegram media
      tags:
      - Messages
      x-required-scopes:
      - messages.write
  /v1/chats/{chat_id}/messages/{message_id}:
    delete:
      description: Deletes a Telegram message in the selected chat using the chosen connected account.
      operationId: delete-chat-message
      parameters:
      - description: Canonical Telegram chat identifier.
        in: path
        name: chat_id
        required: true
        schema:
          description: Canonical Telegram chat identifier.
          examples:
          - '-1000001234567'
          type: string
      - description: Telegram message identifier within the chat.
        in: path
        name: message_id
        required: true
        schema:
          description: Telegram message identifier within the chat.
          examples:
          - 123456
          format: int64
          type: integer
      - description: Connected account id from the accounts endpoint used to scope the delete operation.
        explode: false
        in: query
        name: account_id
        schema:
          description: Connected account id from the accounts endpoint used to scope the delete operation.
          examples:
          - acct_demo_123
          type: string
      - description: Also revoke the message for the other side when Telegram allows it.
        explode: false
        in: query
        name: revoke
        schema:
          default: false
          description: Also revoke the message for the other side when Telegram allows it.
          examples:
          - false
          type: boolean
      responses:
        '204':
          description: No Content
        '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
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Too Many Requests
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Gateway
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Service Unavailable
        '504':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Gateway Timeout
      summary: Delete a Telegram message
      tags:
      - Messages
      x-required-scopes:
      - messages.write
    get:
      description: Returns one Telegram message from the selected chat and connected account context.
      operationId: get-chat-message
      parameters:
      - description: Canonical Telegram chat identifier.
        in: path
        name: chat_id
        required: true
        schema:
          description: Canonical Telegram chat identifier.
          examples:
          - '-1000001234567'
          type: string
      - description: Telegram message identifier within the chat.
        in: path
        name: message_id
        required: true
        schema:
          description: Telegram message identifier within the chat.
          examples:
          - 123456
          format: int64
          type: integer
      - description: Connected account id from the accounts endpoint used to scope the message lookup.
        explode: false
        in: query
        name: account_id
        schema:
          description: Connected account id from the accounts endpoint used to scope the message lookup.
          examples:
          - acct_demo_123
          type: string
      - description: Reserved for forum topics. Not supported yet.
        explode: false
        in: query
        name: thread_id
        schema:
          description: Reserved for forum topics. Not supported yet.
          examples:
          - 77
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageEnvelope'
          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
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Too Many Requests
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Gateway
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Service Unavailable
        '504':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Gateway Timeout
      summary: Get a single Telegram message
      tags:
      - Messages
      x-required-scopes:
      - messages.read
    patch:
      description: Edits an existing Telegram message in the selected chat using the chosen connected account.
      operationId: update-chat-message
      parameters:
      - description: Canonical Telegram chat identifier.
        in: path
        name: chat_id
        required: true
        schema:
          description: Canonical Telegram chat identifier.
          examples:
          - '-1000001234567'
          type: string
      - description: Telegram message identifier within the chat.
        in: path
        name: message_id
        required: true
        schema:
          description: Telegram message identifier within the chat.
          examples:
          - 123456
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMessageBody'
        required: true
      responses:
        '204':
          description: No Content
        '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
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Conflict
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Too Many Requests
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Gateway
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Service Unavailable
        '504':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Gateway Timeout
      summary: Edit a Telegram message
      tags:
      - Messages
      x-required-scopes:
      - messages.write
  /v1/chats/{chat_id}/messages/{message_id}/media:
    get:
      description: Streams the message media as binary data. Supports a single HTTP byte range for resumable and chunked downloads.
      operationId: download-chat-message-media
      parameters:
      - description: Canonical Telegram chat identifier.
        in: path
        name: chat_id
        required: true
        schema:
          description: Canonical Telegram chat identifier.
          examples:
          - '-1000001234567'
          type: string
      - description: Telegram message identifier within the chat.
        in: path
        name: message_id
        required: true
        schema:
          description: Telegram message identifier within the chat.
          examples:
          - 123456
          format: int64
          minimum: 1
          type: integer
      - description: Connected account id used to download the media.
        explode: false
        in: query
        name: account_id
        schema:
          description: Connected account id used to download the media.
          examples:
          - acct_demo_123
          type: string
      - description: Optional single HTTP byte range, for example bytes=0-5242879.
        in: header
        name: Range
        schema:
          description: Optional single HTTP byte range, for example bytes=0-5242879.
          examples:
          - bytes=0-5242879
          type: string
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                contentMediaType: application/octet-stream
                format: binary
                type: string
          description: Complete media payload
        '206':
          content:
            application/octet-stream:
              schema:
                contentMediaType: application/octet-stream
                format: binary
                type: string
          description: Requested media byte range
        '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
        '416':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Requested Range Not Satisfiable
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Too Many Requests
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Gateway
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Service Unavailable
        '504':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Gateway Timeout
      summary: Download Telegram message media
      tags:
      - Messages
      x-required-scopes:
      - messages.read
  /v1/chats/{chat_id}/messages/{message_id}/reactions:
    get:
      description: Returns the current reaction aggregates for a message, including known reacting users when Telegram exposes them.
      operationId: get-chat-message-reactions
      parameters:
      - description: Canonical Telegram chat identifier.
        in: path
        name: chat_id
        required: true
        schema:
          description: Canonical Telegram chat identifier.
          examples:
          - '-1000001234567'
          type: string
      - description: Telegram message identifier within the chat.
        in: path
        name: message_id
        required: true
        schema:
          description: Telegram message identifier within the chat.
          examples:
          - 123456
          format: int64
          type: integer
      - description: Connected account id from the accounts endpoint used to scope the reaction lookup.
        explode: false
        in: query
        name: account_id
        schema:
          description: Connected account id from the accounts endpoint used to scope the reaction lookup.
          examples:
          - acct_demo_123
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageReactionsEnvelope'
          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
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Too Many Requests
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Gateway
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Service Unavailable
        '504':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Gateway Timeout
      summary: Get detailed Telegram reactions for a message
      tags:
      - Messages
      x-required-scopes:
      - messages.read
    put:
      description: Replaces the authenticated actor's current reaction selection for the target message. Pass an empty array to clear reactions.
      operationId: set-chat-message-reactions
      parameters:
      - description: Canonical Telegram chat identifier.
        in: path
        name: chat_id
        required: true
        schema:
          description: Canonical Telegram chat identifier.
          examples:
          - '-1000001234567'
          type: string
      - description: Telegram message identifier within the chat.
        in: path
        name: message_id
        required: true
        schema:
          description: Telegram message identifier within the chat.
          examples:
          - 123456
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetMessageReactionsBody'
        required: true
      responses:
        '204':
          description: No Content
        '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
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Conflict
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Too Many Requests
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Gateway
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Service Unavailable
        '504':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Gateway Timeout
      summary: Set your Telegram reactions on a message
      tags:
      - Messages
      x-required-scopes:
      - messages.write
  /v1/messages/media/uploads/{upload_id}:
    put:
      description: Uploads the raw binary payload for a previously issued media upload ticket.
      operationId: upload-chat-media-bytes
      parameters:
      - description: Upload identifier returned by the ticket endpoint.
        in: path
        name: upload_id
        required: true
        schema:
          description: Upload identifier returned by the ticket endpoint.
          examples:
          - 9f3b2ab4-1a2b-4b8e-8d12-4d9d2a31c8f8
          type: string
      - description: Connected account id from the accounts endpoint used to authorize the upload.
        explode: false
        in: query
        name: account_id
        schema:
          description: Connected account id from the accounts endpoint used to authorize the upload.
          examples:
          - acct_demo_123
          type: string
      - description: Opaque upload ticket returned by the ticket endpoint.
        in: header
        name: X-Upload-Ticket
        required: true
        schema:
          description: Opaque upload ticket returned by the ticket endpoint.
          type: string
      - description: Optional file name override used for validation and downstream metadata.
        in: header
        name: X-File-Name
        schema:
          description: Optional file name override used for validation and downstream metadata.
          examples:
          - invoice.pdf
          type: string
      - description: Optional original file MIME type metadata.
        in: header
        name: X-File-Content-Type
        schema:
          description: Optional original file MIME type metadata.
          examples:
          - application/pdf
          type: string
      requestBody:
        content:
          application/octet-stream:
            schema:
              contentMediaType: application/octet-stream
              format: binary
              type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaUploadEnvelope'
          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
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Conflict
        '413':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Request Entity Too Large
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Too Many Requests
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Gateway
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Service Unavailable
        '504':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Gateway Timeout
      summary: Upload raw bytes for a reserved media ticket
      tags:
      - Messages
      x-required-scopes:
      - messages.write
components:
  schemas:
    SendResultEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/SendResult'
      required:
      - data
      type: object
    CreateMediaMessageBody:
      additionalProperties: false
      properties:
        accountId:
          description: Connected account id from the accounts endpoint.
          examples:
          - acct_demo_123
          type: string
        idempotencyKey:
          description: Client-supplied idempotency key used to identify retries.
          examples:
          - media-2026-04-16-001
          minLength: 1
          type: string
        parseMode:
          description: Optional Telegram parse mode for the caption.
          examples:
          - Markdown
          type: string
        replyToMessageId:
          description: Optional Telegram message id to reply to.
          examples:
          - 123450
          format: int64
          type: integer
        text:
          description: Optional caption text for the upload batch.
          examples:
          - Please review the attached file.
          type: string
        uploadIds:
          description: Previously uploaded media payload ids to send.
          examples:
          - - 9f3b2ab4-1a2b-4b8e-8d12-4d9d2a31c8f8
          items:
            type: string
          type:
          - array
          - 'null'
      required:
      - accountId
      - uploadIds
      - idempotencyKey
      type: object
    MessageReactionsEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/MessageReactionsResult'
      required:
      - data
      type: object
    HistoryEntity:
      additionalProperties: false
      properties:
        length:
          format: int64
          type: integer
        offset:
          format: int64
          type: integer
        type:
          type: string
        url:
          type: string
        userId:
          type: string
      type: object
    MessageReactionsResult:
      additionalProperties: false
      properties:
        accountId:
          type: string
        chatId:
          type: string
        messageId:
          format: int64
          type: integer
        reactions:
          items:
            $ref: '#/components/schemas/MessageReaction'
          type:
          - array
          - 'null'
        users:
          items:
            $ref: '#/components/schemas/ReactionUser'
          type:
          - array
          - 'null'
      required:
      - accountId
      - chatId
      - messageId
      type: object
    SetMessageReactionsBody:
      additionalProperties: false
      properties:
        accountId:
          description: Connected account id from the accounts endpoint.
          examples:
          - acct_demo_123
          type: string
        reactions:
          description: Full replacement list of reactions to set on the message. Use emoji like 👍 or a custom emoji document id string. Pass an empty array to clear your reactions.
          examples:
          - - 👍
          items:
            type: string
          type:
          - array
          - 'null'
      required:
      - accountId
      - reactions
      type: object
    HistoryReaction:
      additionalProperties: false
      properties:
        count:
          format: int64
          type: integer
        emoji:
          type: string
        mine:
          type: boolean
      type: object
    ForwardMessagesBody:
      additionalProperties: false
      properties:
        accountId:
          description: Connected account id from the accounts endpoint.
          examples:
          - acct_demo_123
          type: string
        dropAuthor:
          description: Hide the original author when Telegram supports it.
          examples:
          - false
          type: boolean
        dropMediaCaptions:
          description: Drop source media captions when Telegram supports it.
          examples:
          - false
          type: boolean
        fromChatId:
          description: Source Telegram chat identifier.
          examples:
          - '-1000007654321'
          type: string
        messageIds:
          description: Telegram message ids to forward.
          examples:
          - - 123456
            - 123457
          items:
            format: int64
            type: integer
          type:
          - array
          - 'null'
        silent:
          description: Forward silently when Telegram supports it.
          examples:
          - false
          type: boolean
      required:
      - accountId
      - fromChatId
      - messageIds
      type: object
    MessageReaction:
      additionalProperties: false
      properties:
        count:
          format: int64
          type: integer
        customEmojiId:
          type: string
        emoji:
          type: string
        mine:
          type: boolean
        type:
          type: string
        users:
          items:
            $ref: '#/components/schemas/ReactionUser'
          type:
          - array
          - 'null'
      type: object
    MessagesPageEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/HistoryPage'
      required:
      - data
      type: object
    HistoryPage:
      additionalProperties: false
      properties:
        accountId:
          type: string
        chatId:
          type: string
        hasMore:
          type: boolean
        items:
          items:
            $ref: '#/components/schemas/Message'
          type:
          - array
          - 'null'
        oldestMessageId:
          format: int64
          type: integer
        readOutboxMaxId:
          format: int64
          type: integer
      required:
      - accountId
      - chatId
      - items
      - hasMore
      type: object
    SendResult:
      additionalProperties: false
      properties:
        chatId:
          type: string
        date:
          format: date-time
          type: string
        idempotencyKey:
          type: string
        localMessageId:
          type: string
        messageIds:
          items:
            format: int64
            type: integer
          type:
          - array
          - 'null'
        text:
          type: string
      required:
      - messageIds
      type: object
    UploadMediaResult:
      additionalProperties: false
      properties:
        expiresAt:
          format: date-time
          type: string
        fileName:
          type: string
        mediaType:
          type: string
        sizeBytes:
          format: int64
          type: integer
        uploadId:
          type: string
      required:
      - uploadId
      - mediaType
      - fileName
      - sizeBytes
      - expiresAt
      type: object
    MediaUploadTicketResult:
      additionalProperties: false
      properties:
        accountId:
          type: string
        chatId:
          type: string
        uploads:
          items:
            $ref: '#/components/schemas/MediaUploadTicket'
          type:
          - array
          - 'null'
      required:
      - accountId
      - chatId
      - uploads
      type: object
    MediaUploadTicket:
      additionalProperties: false
      properties:
        expiresAt:
          format: date-time
          type: string
        maxSizeBytes:
          format: int64
          type: integer
        ticket:
          type: string
        uploadId:
          type: string
      required:
      - uploadId
      - ticket
      - maxSizeBytes
      - expiresAt
      type: object
    HistoryMedia:
      additionalProperties: false
      properties:
        durationSecs:
          format: int64
          type: integer
        fileName:
          type: string
        fileSize:
          format: int64
          type: integer
        height:
          format: int64
          type: integer
        mimeType:
          type: string
        type:
          type: string
        url:
          type: string
        width:
          format: int64
          type: integer
      type: object
    ReactionUser:
      additionalProperties: false
      properties:
        id:
          type: string
        isMe:
          type: boolean
        name:
          type: string
        username:
          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
    MediaUploadEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/UploadMediaResult'
      required:
      - data
      type: object
    UpdateMessageBody:
      additionalProperties: false
      properties:
        accountId:
          description: Connected account id from the accounts endpoint.
          examples:
          - acct_demo_123
          type: string
        parseMode:
          description: Optional Telegram parse mode.
          examples:
          - Markdown
          type: string
        text:
          description: Replacement message text.
          examples:
          - Edited public API message.
          minLength: 1
          type: string
      required:
      - accountId
      - text
      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
    CreateMediaUploadTicketsBody:
      additionalProperties: false
      properties:
        accountId:
          description: Connected account id from the accounts endpoint.
          examples:
          - acct_demo_123
          type: string
        files:
          description: Files to reserve upload tickets for.
          items:
            $ref: '#/components/schemas/MediaUploadFileBody'
          type:
          - array
          - 'null'
      required:
      - accountId
      - files
      type: object
    CreateMessageBody:
      additionalProperties: false
      properties:
        accountId:
          description: Connected account id from the accounts endpoint.
          examples:
          - acct_demo_123
          type: string
        idempotencyKey:
          description: Client-supplied idempotency key used to deduplicate retries.
          examples:
          - msg-2026-04-16-001
          minLength: 1
          type: string
        parseMode:
          description: Optional Telegram parse mode.
          examples:
          - Markdown
          type: string
        replyToMessageId:
          description: Optional Telegram message id to reply to.
          examples:
          - 123450
          format: int64
          type: integer
        text:
          description: Message text to send.
          examples:
          - Hello from the public API.
          minLength: 1
          type: string
      required:
      - accountId
      - text
      - idempotencyKey
      type: object
    Sender:
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        username:
          type: string
      type: object
    MediaUploadFileBody:
      additionalProperties: false
      properties:
        durationSeconds:
          description: Optional duration metadata for video/audio/voice.
          examples:
          - 12.5
          format: double
          minimum: 0
          type: number
        fileName:
          description: Original file name.
          examples:
          - invoice.pdf
          minLength: 1
          type: string
        height:
          description: Optional height metadata for photos/videos.
          examples:
          - 1080
          format: int64
          minimum: 0
          type: integer
        mediaType:
          description: Telegram media bucket for validation and send semantics.
          enum:
          - photo
          - document
          - video
          - audio
          - voice
          - sticker
          - gif
          examples:
          - document
          type: string
        mimeType:
          description: Original client MIME type metadata.
          examples:
          - application/pdf
          type: string
        sizeBytes:
          description: Expected upload size in bytes.
          examples:
          - 20480
          format: int64
          minimum: 1
          type: integer
        width:
          description: Optional width metadata for photos/videos.
          examples:
          - 1920
          format: int64
          minimum: 0
          type: integer
      required:
      - fileName
      - mediaType
      - sizeBytes
      type: object
    MessageEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/Message'
      required:
      - data
      type: object
    Message:
      additionalProperties: false
      properties:
        actionType:
          type: string
        date:
          format: date-time
          type: string
        editDate:
          format: date-time
          type: string
        entities:
          items:
            $ref: '#/components/schemas/HistoryEntity'
          type:
          - array
          - 'null'
        groupedId:
          type: string
        id:
          format: int64
          type: integer
        isEdited:
          type: boolean
        isOut:
          type: boolean
        isRead:
          type: boolean
        media:
          $ref: '#/components/schemas/HistoryMedia'
        messageType:
          type: string
        reactions:
          items:
            $ref: '#/components/schemas/HistoryReaction'
          type:
          - array
          - 'null'
        replyToMessageId:
          format: int64
          type: integer
        sender:
          $ref: '#/components/schemas/Sender'
        text:
          type: string
      required:
      - id
      - date
      - isOut
      type: object
    MediaUploadTicketsEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/MediaUploadTicketResult'
      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