openapi: 3.0.0
info:
  version: 0.0.33
  title: Max Bot API
  license:
    name: Apache 2.0
  description: |-
    # About
    Bot API allows bots to interact with Max. Methods are called by sending HTTPS requests to [platform-api2.max.ru](https://platform-api2.max.ru) domain.
    Bots are third-party applications that use Max features. A bot can legitimately take part in a conversation. It can be achieved through HTTPS requests to the Max Bot API.

    ## Features
    Max bots of the current version are able to:
    - Communicate with users and respond to requests
    - Recommend users complete actions via programmed buttons
    - Request data from users (name, short reference, phone number)
    We'll keep working on expanding bot capabilities in the future.

    ## Examples
    Bots can be used for the following purposes:
    - Providing support, answering frequently asked questions
    - Sending typical information
    - Voting
    - Likes/dislikes
    - Following external links
    - Forwarding a user to a chat/channel

    ## HTTP verbs
    `GET` — getting resources, parameters are transmitted via URL

    `POST` — creation of resources (for example, sending new messages)

    `PUT` — editing resources

    `DELETE` — deleting resources

    `PATCH` — patching resources

    ## HTTP response codes
    `200` — successful operation

    `400` — invalid request

    `401` — authentication error

    `404` — resource not found

    `403` — forbidden

    `405` — method is not allowed

    `429` — the number of requests is exceeded

    `503` — service unavailable

    ## Resources format
    For content requests (PUT and POST) and responses, the API uses the JSON format.
    All strings are UTF-8 encoded.
    Date/time fields are represented as the number of milliseconds that have elapsed since 00:00 January 1, 1970 in the long format. To get it, you can simply multiply the UNIX timestamp by 1000. All date/time fields have a UTC timezone.
    ## Error responses
    In case of an error, the API returns a response with the corresponding HTTP code and JSON with the following fields:

    `code` - the string with the error key

    `message` - a string describing the error </br>

 
    ## Receiving notifications

    Max Bot API supports 2 options of receiving notifications on new events for bots:
    - Push notifications via WebHook (recommended). To receive data via WebHook, you'll have to [add subscription](https://dev.max.ru/docs-api/methods/POST/subscriptions);
    - Notifications upon request via long polling (/getUpdates) API (not recommended). All data can be received via long polling **by default** after creating the bot.      

      Receiving updates via Long Polling is limited in speed and event retention time — this method is not suitable for production environments. We recommend using Webhook at all stages of work.

    Both methods **cannot** be used simultaneously.
    Refer to the response schema of [/updates](https://dev.max.ru/docs-api/methods/GET/updates) method to check all available types of updates.

    ### Webhook
    There is some notes about how we handle webhook subscription:
    1. Sometimes webhook notification cannot be delivered in case when bot server or network is down.

      In such case we well retry delivery in exponentially increasing intervals and will do this until get
      `200 OK` status code from your server, but not longer than **8 hours** (*may change over time*) since update happened.

      We also consider any non `200`-response from server as failed delivery.


     ### Updates
    1. Minimum polling time - 300ms


    ## Message buttons
    You can program buttons for users answering a bot.
    Max supports the following types of buttons:

    `callback` &mdash; sends a notification with payload to a bot (via WebHook or long polling)
    
    `clipboard` &mdash; copies payload data to clipboard
    
    `open_app` &mdash; opens mini app

    `link` &mdash; makes a user to follow a link

    `message` &mdash; send a quick reply, command, or template message. 

    `request_contact` &mdash; requests the user permission to access contact information (phone number, short link, email)

    `request_geo_location` &mdash; asks user to provide current geo location

    To start create buttons (sendMessage) with `InlineKeyboardAttachment`:
    ```json
    {
      "text": "It is message with inline keyboard",
      "attachments": [
        {
          "type": "inline_keyboard",
          "payload": {
            "buttons": [
              [
                {
                  "type": "callback",
                  "text": "Press me!",
                  "payload": "button1 pressed"
                }
              ]
            ]
          }
        }
      ]
    }
    ```
    ## Deep linking
    Max supports deep linking mechanism for bots. It allows passing additional payload to the bot on startup.
    Deep link can contain any data encoded into string up to **128** characters long. Longer strings will be omitted and **not** passed to the bot.

    Each bot has start link that looks like:
    ```
    https://max.ru/<botName>?start=<payload>
    ```
    As soon as user clicks on such link we open dialog with bot and send this payload to bot as part of `bot_started` update:
    ```json
    {
        "update_type": "bot_started",
        "timestamp": 1573226679188,
        "chat_id": 1234567890,
        "user": {
            "user_id": 1234567890,
            "name": "Boris",
            "username": "borisd84"
        },
        "payload": "any data meaningful to bot"
    }
    ```

    Deep linking mechanism is supported for iOS version 2.7.0 and Android 2.9.0 and higher.
    
    ## Text formatting
    
    Message text can be improved with basic formatting such as: **strong**, *emphasis*, ~strikethough~, 
    <ins>underline</ins>, `code` or link. You can use either markdown-like or HTML formatting.
    
    To enable text formatting set the `format` property of NewMessageBody model.

    ### Max flavored Markdown
    To enable [Markdown](https://spec.commonmark.org/0.29/) parsing, set the `format` property of NewMessageBody model to `markdown`.
    
    We currently support only the following syntax:

    `*empasized*` or `_empasized_` for *italic* text
    
    `**strong**` or `__strong__` for __bold__ text
    
    `~~strikethough~~`  for ~strikethough~ text
    
    `++underline++`  for <ins>underlined</ins> text

    ``` `code` ``` or ` ```code``` ` for `monospaced` text

    `^^important^^` for highlighted text (colored in red, by default)
    
    `> quote` for 
    >quoted text

    `[Inline URL](https://dev.max.ru/)` for inline URLs

    `[User mention](max://user/%user_id%)` for user mentions without username
    
    `# Header` for header
    
    ### HTML support
    
    To enable HTML parsing, set the `format` property of NewMessageBody model to `html`.
    
    Only the following HTML tags are supported. All others will be stripped:
    
    Emphasized: `<i>` or `<em>`
    
    Strong: `<b>` or `<strong>`
    
    Strikethrough: `<del>` or `<s>`
    
    Underlined: `<ins>` or `<u>`
    
    Link: `<a href="https://dev.max.ru">Docs</a>`

    Monospaced text: `<pre>` or `<code>`

    Highlighted text: `<mark>`
    
    Quote: `<blockquote>`
    
    Header: `<h1>`

    Text formatting is supported for iOS since version 3.1 and Android since 2.20.0.

    # Libraries
    We have developed the official [Typescript client](https://github.com/max-messenger/max-bot-api-client-ts), [Go client](https://github.com/max-messenger/max-bot-api-client-go) and also [Go framework](https://github.com/max-messenger/maxbot/tree/main) 
servers:
  - url: '/'
security:
  - access_token: [ ]
tags:
  - name: bots
    description: Bot management
  - name: chats
    description: Chat and channel operations
  - name: messages
    description: Message sending and management
  - name: subscriptions
    description: Webhook subscriptions
  - name: upload
    description: File upload endpoints
  - name: user_model
    x-displayName: User
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/User"/>
  - name: user_with_photo_model
    x-displayName: User
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/UserWithPhoto"/>
  - name: bot_info
    x-displayName: BotInfo
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/BotInfo"/>
  - name: chat_model
    x-displayName: Chat
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Chat"/>
  - name: chat_member
    x-displayName: ChatMember
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/ChatMember"/>
  - name: message_model
    x-displayName: Message
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Message"/>
  - name: comment_message_model
    x-displayName: CommentMessage
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/CommentMessage"/>
  - name: new_message_model
    x-displayName: NewMessageBody
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/NewMessageBody"/>
  - name: new_comment_message_model
    x-displayName: NewCommentBody
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/NewCommentBody"/>
  - name: update_model
    x-displayName: Update
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Update"/> 
x-tagGroups:
  - name: Methods
    tags:
      - bots
      - chats
      - comments
      - messages
      - subscriptions
      - upload
  - name: Objects
    tags:
      - user_model
      - user_with_photo_model
      - bot_info
      - chat_member
      - chat_model
      - message_model
      - new_message_model
      - new_comment_message_model
      - update_model
paths:
  /me:
    get:
      tags:
        - bots
      summary: Get current bot info
      operationId: getMyInfo
      description: Returns info about current bot. Current bot can be identified by access token. Method returns bot identifier, name and avatar (if any)
      responses:
        '200':
          description: Bot info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotInfo'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /me/commands:
    patch:
      tags:
        - bots
      summary: Edit current bot commands
      operationId: editMyCommands
      description: Edits current bot Commands.
      responses:
        '200':
          description: Modified bot commands info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotCommandsInfo'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      requestBody:
        description: Bot commands to set
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BotCommandsPatch'
  /chats/{chatId}: 
    get:
      tags:
        - chats
      operationId: getChat
      description: Returns info about chat or channel.
      summary: Get chat
      parameters:
        - name: chatId
          description: Requested chat or channel identifier
          required: true
          in: path
          schema:
            allOf:
              - $ref: '#/components/schemas/ChatId'
            x-pattern: \-?\d+
      responses:
        '200':
          description: Chat or channel information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chat'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    patch: 
      tags:
        - chats
      operationId: editChat
      description: 'Edits chat or channel info: title, icon, etc…'
      summary: Edit chat or channel info
      parameters:
        - name: chatId
          description: Chat or channel identifier
          required: true
          in: path
          schema:
            allOf:
              - $ref: '#/components/schemas/ChatId'
            x-pattern: \-?\d+
      requestBody:
        description: Chat or channel info to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatPatch'
      responses:
        '200':
          description: If success, returns updated chat object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chat'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
  '/chats/{chatId}/actions':
    post:
      tags:
        - chats
      operationId: sendAction
      description: Send bot action to chat.
      summary: Send action
      parameters:
        - name: chatId
          description: Chat identifier
          required: true
          in: path
          schema:
            allOf:
              - $ref: '#/components/schemas/ChatId'
            x-pattern: \-?\d+
      requestBody:
        description: Action to send to chat members
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  '/chats/{chatId}/pin':
    get:
      tags:
        - chats
      operationId: getPinnedMessage
      description: Get pinned message in chat or channel.
      summary: Get pinned message
      parameters:
        - name: chatId
          description: Chat identifier to get its pinned message
          required: true
          in: path
          schema:
            allOf:
              - $ref: '#/components/schemas/ChatId'
            x-pattern: \-?\d+
      responses:
        '200':
          description: Pinned message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPinnedMessageResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      tags:
        - chats
      operationId: pinMessage
      description: Pins message in chat or channel.
      summary: Pin message
      parameters:
        - name: chatId
          description: Chat identifier where message should be pinned
          required: true
          in: path
          schema:
            allOf:
              - $ref: '#/components/schemas/ChatId'
            x-pattern: \-?\d+
      requestBody:
        description: Message to pin in chat
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PinMessageBody'
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags:
        - chats
      operationId: unpinMessage
      description: Unpins message in chat or channel.
      summary: Unpin message
      parameters:
        - name: chatId
          description: Chat identifier to remove pinned message
          required: true
          in: path
          schema:
            allOf:
              - $ref: '#/components/schemas/ChatId'
            x-pattern: \-?\d+
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  '/chats/{chatId}/members/me':
    get:
      tags:
        - chats
      operationId: getMembership
      summary: Get chat or channel membership
      description: Returns chat or channel  membership info for current bot 
      parameters:
        - name: chatId
          description: Chat or channel identifier
          required: true
          in: path
          schema:
            allOf:
              - $ref: '#/components/schemas/ChatId'
            x-pattern: \-?\d+
      responses:
        '200':
          description: Current bot membership info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMember'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete: 
      tags:
        - chats
      operationId: leaveChat
      summary: Leave chat
      description: Removes bot from chat or channel members.
      parameters:
        - name: chatId
          description: Chat or channel identifier
          required: true
          in: path
          schema:
            allOf:
              - $ref: '#/components/schemas/ChatId'
            x-pattern: \-?\d+
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  '/chats/{chatId}/members/admins':
    get:
      tags:
        - chats
      operationId: getAdmins
      summary: Get chat or channel admins
      description: Returns all chat or channel administrators. Bot must be **administrator** in requested chat or channel. 
      parameters:
        - name: chatId
          description: Chat or channel identifier
          required: true
          in: path
          schema:
            allOf:
              - $ref: '#/components/schemas/ChatId'
            x-pattern: \-?\d+
      responses:
        '200':
          description: Administrators list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMembersList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    post: 
      tags:
        - chats
      operationId: postAdmins
      summary: Set chat or channel admins
      description: Returns true if all administrators added. Additional permissions may require
      parameters:
        - name: chatId
          description: Chat or channel identifier
          required: true
          in: path
          schema:
            allOf:
              - $ref: '#/components/schemas/ChatId'
            x-pattern: \-?\d+
      requestBody:
        description: List of administrators to set in chat or channel
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatAdminsList'
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  '/chats/{chatId}/members/admins/{userId}':
    delete: 
      tags:
        - chats
      operationId: deleteAdmins
      summary: Revoke admin rights
      description: Revokes admin rights from a user in the chat or channel by removing their administrative privileges. Additional permissions may require.
      parameters:
        - name: chatId
          description: Chat or channel identifier
          required: true
          in: path
          schema:
            allOf:
              - $ref: '#/components/schemas/ChatId'
            x-pattern: \-?\d+
        - name: userId
          description: User identifier
          required: true
          in: path
          schema:
            allOf:
              - $ref: '#/components/schemas/UserId'
            x-pattern: \d+
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  '/chats/{chatId}/members':
    get:
      tags:
        - chats
      operationId: getMembers
      summary: Get members
      description: Returns users participated in chat or channel. 
      parameters:
        - name: chatId
          description: Chat or channel identifier
          required: true
          in: path
          schema:
            allOf:
              - $ref: '#/components/schemas/ChatId'
            x-pattern: \-?\d+
        - name: user_ids
          description: |-
            Comma-separated list of users identifiers to get their membership. When this parameter is passed, both `count` and `marker` are ignored
          required: false
          in: query
          schema:
            type: array
            uniqueItems: true
            items:
              $ref: '#/components/schemas/UserId'
            nullable: true
          style: form
        - name: marker
          description: Marker
          in: query
          schema:
            type: integer
            format: int64
        - name: count
          description: Count
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Returns members list and pointer to the next data page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMembersList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
        - chats
      operationId: addMembers
      description: Adds members to chat. Additional permissions may require.
      summary: Add members
      parameters:
        - name: chatId
          description: Chat identifier
          required: true
          in: path
          schema:
            allOf:
              - $ref: '#/components/schemas/ChatId'
            x-pattern: \-?\d+
      requestBody:
        description: List of users to add to chat
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserIdsList'
      responses:
        '200':
          description: Result of chat members modification request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModifyMembersResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags:
        - chats
      operationId: removeMember
      description: Removes member from chat or channel. Additional permissions may require. 
      summary: Remove member
      parameters:
        - name: chatId
          description: Chat or channel identifier
          required: true
          in: path
          schema:
            allOf:
              - $ref: '#/components/schemas/ChatId'
            x-pattern: \-?\d+
        - name: user_id
          description: User id to remove from chat or channel
          required: true
          in: query
          schema:
            $ref: '#/components/schemas/UserId'
        - name: block
          description: |-
            Set to `true` if user should be blocked in chat.
            Applicable only for chats that have public or private link. Ignored otherwise
          required: false
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
  /subscriptions:
    get:
      tags:
        - subscriptions
      operationId: getSubscriptions
      description: In case your bot gets data via WebHook, the method returns list of all subscriptions
      summary: Get subscriptions
      responses:
        '200':
          description: As expected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSubscriptionsResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags:
        - subscriptions
      operationId: subscribe
      description: |-
        Subscribes bot to receive updates via WebHook. After calling this method, the bot will receive notifications about new events in chat rooms at the specified URL.

        Your server **must** be listening on port **443**
      summary: Subscribe
      requestBody:
        description: WebHook subscription parameters
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    delete: 
      tags:
        - subscriptions
      operationId: unsubscribe
      description: Unsubscribes bot from receiving updates via WebHook. After calling the method, the bot stops receiving notifications about new events. Notification via the long-poll API becomes available for the bot. Receiving updates via Long Polling is limited in speed and event retention time — this method is not suitable for production environments. We recommend using Webhook at all stages of work
      summary: Unsubscribe
      parameters:
        - name: url
          in: query
          description: URL to remove from WebHook subscriptions
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /uploads:
    post:
      tags:
        - upload
      operationId: getUploadUrl
      description: |-
        Returns the URL for the subsequent file upload.

        For example, you can upload it via curl:

        ```curl -i -X POST
          -H "Content-Type: multipart/form-data"
          -F "data=@movie.mp4" "%UPLOAD_URL%"```

        Two types of an upload are supported:
        - single request upload (multipart request)
        - and resumable upload.

        ##### Multipart upload
        This type of upload is a simpler one but it is less
        reliable and agile. If a `Content-Type`: multipart/form-data header is passed in a request our service indicates
        upload type as a simple single request upload.

        This type of an upload has some restrictions: 

        - image — available formats: JPG, JPEG, PNG, GIF, TIFF, BMP, HEIC; maximum size for a single image: up to 50 MB AND no more than 7680 x 7680 px — both criteria must be met. For example, you cannot upload an image that is 55 MB and has dimensions of 7600 x 7600 px.
        - video — available formats: MP4, MOV, MKV, WEBM; maximum size for a single video: up to 250 MB
        - audio — available formats: MP3, WAV, M4A, and others, maximum size for a single audio file: up to 256 MB OR duration of no more than 60 minutes — both criteria must be met. For example, you cannot send an audio file that is 250 MB and 70 minutes long.
        - file — available formats: TXT, DOC, PDF, and other common formats, maximum size for a single file: up to 4 GB
        - type=photo parameter is no longer supported. If you used type=photo in previously created integrations, please replace it with type=image
        - Only one mediafile per request can be uploaded
        - No possibility to restart stopped / failed upload

        ##### Resumable upload
        If `Content-Type` header value is not equal to `multipart/form-data` our service indicated upload type
        as a resumable upload.
        With a `Content-Range` header current file chunk range and complete file size
        can be passed. If a network error has happened or upload was stopped you can continue to upload a file from
        the last successfully uploaded file chunk. You can request the last known byte of uploaded file from server
        and continue to upload a file.

        ##### Get upload status
        To GET an upload status you simply need to perform HTTPS-GET request to a file upload URL.
        Our service will respond with current upload status,
        complete file size and last known uploaded byte. This data can be used to complete stopped upload
        if something went wrong. If `REQUESTED_RANGE_NOT_SATISFIABLE` or `INTERNAL_SERVER_ERROR` status was returned
        it is a good point to try to restart an upload
      summary: Get upload URL
      parameters:
        - description: 'Uploaded file type: image, audio, video, file'
          name: type
          required: true
          in: query
          schema:
            $ref: '#/components/schemas/UploadType'
      responses:
        '200':
          description: Returns URL to upload attachment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadEndpoint'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /messages:
    get: 
      tags:
        - messages
      operationId: getMessages
      description: 'Returns messages in chat or channel: result page and marker referencing to the next page. Messages traversed in reverse direction so the latest message in chat will be first in result array. Therefore if you use `from` and `to` parameters, `to` must be **less than** `from`'
      summary: Get messages
      parameters:
        - description: Chat or channel identifier to get messages in chat or channel
          name: chat_id
          in: query
          schema:
            $ref: '#/components/schemas/ChatId'
        - description: Comma-separated list of message ids to get
          name: message_ids
          in: query
          style: form
          schema:
            uniqueItems: true
            items:
              type: string
            nullable: true
        - name: from
          description: Start time for requested messages - use after instead
          in: query
          schema:
            $ref: '#/components/schemas/bigint'
          deprecated: true
        - name: to
          description: End time for requested messages  - use before instead
          in: query
          schema:
            $ref: '#/components/schemas/bigint'
          deprecated: true
        - name: before
          description: Messages before timestamp
          in: query
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: after
          description: Messages after timestamp
          in: query
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: count
          description: Maximum amount of messages in response
          in: query
          schema:
            type: integer
            format: int32
            default: 50
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Returns list of messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: This exception happens when user suspended bot or it doesn't have access to chat
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalError'
    post: 
      tags:
        - messages
      operationId: sendMessage
      description: |-
        Sends a message to a chat, channel or dialog. 
        As a result for this method new message identifier returns.
        In the case of a channel, it returns an error if you pass notify=false
        ### Attaching media
        Attaching media to messages is a three-step process.

        At first step, you should obtain a URL to upload your media files.

        At the second, you should upload binary of appropriate format to URL you obtained at the previous step. See [upload section](https://dev.max.ru/docs-api/methods/POST/uploads) in docs for details.

        Finally, if the upload process was successful, you will receive JSON-object in a response body.  Use this object to create attachment. Construct an object with two properties:
        - `type` with the value set to appropriate media type
        - and `payload` filled with the JSON you've got.

        For example, you can attach a video to message this way:

        1. Get URL to upload. Execute following:
        ```shell
        curl -X POST 'https://platform-api2.max.ru/uploads?type=video' -H 'Authorization: %access_token%' 
        ```
        As the result it will return URL for the next step.
        ```json
        {
            "url": "http://omub.okcdn.ru/upload.do…" 
        }
        ```

        2. Use this url to upload your binary:
        ```shell
        curl -i -X POST
          -H "Content-Type: multipart/form-data"
          -F "data=@movie.mp4" "http://omub.okcdn.ru/upload.do…" 
        ```
        As the result it will return JSON you can attach to message:
        ```json
          {
            "token": "_3Rarhcf1PtlMXy8jpgie8Ai_KARnVFYNQTtmIRWNh4"
          }
        ```
        3. Send message with attach:
        ```json
        {
            "text": "Message with video",
            "attachments": [
                {
                    "type": "video",
                    "payload": {
                        "token": "_3Rarhcf1PtlMXy8jpgie8Ai_KARnVFYNQTtmIRWNh4"
                    }
                }
            ]
        }
        ```

        **Important notice**:

        It may take time for the server to process your file (audio/video or any binary).
        While a file is not processed you can't attach it. It means the last step will fail with `400` error.
        Try to send a message again until you'll get a successful result.
      summary: Send message
      parameters:
        - name: user_id
          description: Fill this parameter if you want to send message to user
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/UserId'
        - name: chat_id
          description: Fill this if you send message to chat or channel
          schema:
            $ref: '#/components/schemas/ChatId'
          in: query
          required: false
        - name: disable_link_preview
          description: If `false`, server will not generate media preview for links in text
          in: query
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        description: Message to send
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewMessageBody'
      responses:
        '200':
          description: Returns info about created message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: This exception happens when user suspended bot, bot doesn't have access to chat or channel or forwarded message is prohibited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: chat.denied
                message: Forwarding messages from this chat or channel is prohibited
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      tags:
        - messages
      operationId: editMessage
      description: 'Updated message should be sent as `NewMessageBody` in a request body. In case `attachments` field is `null`, the current message attachments won’t be changed. In case of sending an empty list in this field, all attachments will be deleted.'
      summary: Edit message
      parameters:
        - name: message_id
          description: Editing message identifier
          required: true
          in: query
          schema:
            $ref: '#/components/schemas/MessageId'
      requestBody:
        description: Updated message content
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewMessageBody'
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    delete: 
      tags:
        - messages
      operationId: deleteMessage
      summary: Delete message
      description: Deletes message in a dialog, chat or channel if bot has permission to delete messages.
      parameters:
        - name: message_id
          description: Deleting message identifier
          required: true
          in: query
          schema:
            $ref: '#/components/schemas/MessageId'
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
  /messages/{messageId}:
    get:
      tags:
        - messages
      operationId: getMessageById
      description: Returns single message by its identifier.
      summary: Get message
      parameters:
        - description: Message identifier (`mid`) to get single message in chat or channel
          in: path
          name: messageId
          required: true
          schema:
            allOf:
              - $ref: '#/components/schemas/MessageId'
            pattern: (mid.)?[a-zA-Z0-9_\-]+
      responses:
        '200':
          description: Returns single message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: In case when message is not found or bot has no access to it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalError'
  /messages/{messageId}/comments:
    get: 
      tags:
        - comments
      operationId: getComments
      description: 'Returns comments for a message in channel: result page and marker referencing to the next page. Comments traversed in reverse direction so the latest comment for the message will be first in result array. Additional permissions may require'
      summary: Get comments
      parameters:
        - description: Message identifier (`mid`) of the commented message
          in: path
          name: messageId
          required: true
          schema:
            allOf:
              - $ref: '#/components/schemas/MessageId'
            pattern: (mid.)?[a-zA-Z0-9_\-]+
        - description: Comma-separated list of comment ids to get
          name: comment_ids
          in: query
          style: form
          schema:
            uniqueItems: true
            items:
              $ref: '#/components/schemas/MessageId'
            nullable: true
        - name: before
          description: Comments before timestamp
          in: query
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: after
          description: Comments after timestamp
          in: query
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: count
          description: Maximum amount of comments in response
          in: query
          schema:
            type: integer
            format: int32
            default: 50
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Returns list of comments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentMessageList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    post: 
      tags:
        - comments
      operationId: sendComment
      description: Sends a comment to a message in channel. Attachments are not allowed in comments. Additional permissions may require
      summary: Send comment
      parameters:
        - description: Message identifier (`mid`) of the commented message
          in: path
          name: messageId
          required: true
          schema:
            allOf:
              - $ref: '#/components/schemas/MessageId'
            pattern: (mid.)?[a-zA-Z0-9_\-]+
        - name: disable_link_preview
          description: If `false`, server will not generate media preview for links in text
          in: query
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCommentBody'
      responses:
        '200':
          description: Returns info about created comment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendCommentResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    put: 
      tags:
        - comments
      operationId: editComment
      description: 'Updated comment should be sent as `NewCommentBody` in a request body. Attachments are not allowed in comments. Additional permissions may require'
      summary: Edit comment
      parameters:
        - description: Message identifier (`mid`) of the commented message
          in: path
          name: messageId
          required: true
          schema:
            allOf:
              - $ref: '#/components/schemas/MessageId'
            pattern: (mid.)?[a-zA-Z0-9_\-]+
        - name: comment_id
          description: Editing comment identifier
          required: true
          in: query
          schema:
            $ref: '#/components/schemas/MessageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCommentBody'
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags:
        - comments
      operationId: deleteComment
      summary: Delete comment
      description: Deletes comment for a message in channel if bot has permission to delete messages.
      parameters:
        - description: Message identifier (`mid`) of the commented message
          in: path
          name: messageId
          required: true
          schema:
            allOf:
              - $ref: '#/components/schemas/MessageId'
            pattern: (mid.)?[a-zA-Z0-9_\-]+
        - name: comment_id
          description: Deleting comment identifier
          required: true
          in: query
          schema:
            $ref: '#/components/schemas/MessageId'
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
  /messages/{messageId}/comments/{commentId}:
    get: 
      tags:
        - comments
      operationId: getCommentById
      description: Returns single comment by its identifier. Additional permissions may require
      summary: Get comment
      parameters:
        - description: Message identifier (`mid`) of the commented message
          in: path
          name: messageId
          required: true
          schema:
            allOf:
              - $ref: '#/components/schemas/MessageId'
            pattern: (mid.)?[a-zA-Z0-9_\-]+
        - description: Comment identifier (`mid`) to get single comment in channel
          in: path
          name: commentId
          required: true
          schema:
            allOf:
              - $ref: '#/components/schemas/MessageId'
            pattern: (mid.)?[a-zA-Z0-9_\-]+
      responses:
        '200':
          description: Returns single comment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentMessage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: In case when comment or message is not found or bot has no access to it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalError'
  /videos/{videoToken}:
    get:
      tags:
        - messages
      operationId: getVideoAttachmentDetails
      description: 'Returns detailed information about video attachment: playback URLs and additional metadata.'
      summary: Get video details
      parameters:
        - description: Video attachment token
          in: path
          name: videoToken
          required: true
          schema:
            type: string
            pattern: '[\w-]+'
      responses:
        '200':
          description: Detailed video attachment info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoAttachmentDetails'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: In case when message is not found or bot has no access to it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalError'
  /answers:
    post:
      tags:
        - messages
      operationId: answerOnCallback
      description: This method should be called to send an answer after a user has clicked the button. The answer may be an updated message or/and a one-time user notification.
      summary: Answer on callback
      parameters:
        - name: callback_id
          description: Identifies a button clicked by user. Bot receives this identifier after user pressed button as part of `MessageCallbackUpdate`
          required: true
          in: query
          # not empty string
          schema:
            type: string
            minLength: 1
            pattern: '^\s*\S[\s\S]*$'
        - name: disable_link_preview
          description: If `true`, server will not generate media preview for links in updated message text
          in: query
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        description: Answer to callback button press
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallbackAnswer'
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '405':
          $ref: '#/components/responses/NotAllowed'
        '500':
          $ref: '#/components/responses/InternalError'
  /updates:
    get:
      operationId: getUpdates 
      tags:
        - subscriptions
      description: |-
        Receiving updates via Long Polling is limited in speed and event retention time — this method is not suitable for production environments. We recommend using Webhook at all stages of work.

        You can use this method for getting updates in case your bot is not subscribed to WebHook. The method is based on long polling.

        Every update has its own sequence number. `marker` property in response points to the next upcoming update.

        All previous updates are considered as *committed* after passing `marker` parameter.
        If `marker` parameter is **not passed**, your bot will get all updates happened after the last commitment.
      summary: Get updates
      parameters:
        - name: limit
          description: Maximum number of updates to be retrieved
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - name: timeout
          description: Timeout in seconds for long polling
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 90
            default: 30
        - name: marker
          description: Pass `null` to get updates you didn't get yet
          in: query
          schema:
            type: integer
            format: int64
            nullable: true
        - name: types
          description: Comma separated list of update types your bot want to receive
          in: query
          style: form
          explode: false
          example:
            - message_created
            - message_callback
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
            nullable: true
      responses:
        '200':
          description: List of updates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '405':
          $ref: '#/components/responses/NotAllowed'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  securitySchemes:
    access_token:
      type: apiKey
      name: Authorization
      description: |-
        A token is given to you on https://business.max.ru/ after you have created a bot.
        In all subsequent requests to the Bot API, you **must** pass the received token as an Authorization header in the HTTPS request. 
      in: header
  responses:
    SuccessResponse:
      description: Success or not result
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleQueryResult'
    InternalError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authorization Error. No `access_token` provided or token is invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Access error. You don't have permissions to access this resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Requested resource is not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotAllowed:
      description: Method is not allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    bigint:
      description: 64-bit integer identifier
      type: integer
      format: int64
    UserId:
      description: User identifier
      type: integer
      format: int64
    ChatId:
      description: Chat identifier
      type: integer
      format: int64
    MessageId:
      description: Message identifier
      type: string
      minLength: 1
    Url:
      description: URL string
      type: string
    SubscriptionUrl:
      type: string
      description: URL of HTTPS-endpoint of your bot. Must starts with https://
    User:
      type: object
      description: User object
      properties:
        user_id:
          description: Users identifier
          allOf:
            - $ref: '#/components/schemas/UserId'
        first_name:
          description: Users first name
          type: string
        last_name:
          description: Users last name
          type: string
          nullable: true
          readOnly: false
        username:
          description: Unique public user name. Can be `null` if user is not accessible or it is not set
          type: string
          nullable: true
          readOnly: false
        is_bot:
          description: '`true` if user is bot'
          type: boolean
        last_activity_time:
          description: Time of last user activity in Max (Unix timestamp in milliseconds). Can be outdated if user disabled its "online" status in settings
          type: integer
          format: int64
          nullable: true
          readOnly: false
      required:
        - user_id
        - first_name
        - is_bot
    UserWithPhoto:
      type: object
      description: User with description and avatar URLs
      allOf:
        - $ref: '#/components/schemas/User'
        - properties:
            description:
              description: User description. Can be `null` if user did not fill it out
              maxLength: 16000
              type: string
              nullable: true
              readOnly: false
            avatar_url:
              description: URL of avatar
              type: string
              readOnly: false
              nullable: true
            full_avatar_url:
              description: URL of avatar of a bigger size
              type: string
              readOnly: false
              nullable: true
    BotInfo:
      type: object
      description: Bot information with commands and official status
      allOf:
        - $ref: '#/components/schemas/UserWithPhoto'
        - properties:
            commands:
              description: Commands supported by bot
              type: array
              items:
                $ref: '#/components/schemas/BotCommand'
              maxItems: 32
              readOnly: false
              nullable: true
    BotCommandsInfo:
      type: object
      description: Bot commands information
      properties:
        commands:
          description: Commands supported by bot
          type: array
          items:
            $ref: '#/components/schemas/BotCommand'
          maxItems: 32
          readOnly: false
          nullable: true
    BotCommandsPatch:
      type: object
      description: Patch object for updating bot commands
      properties:
        commands:
          description: Commands supported by bot
          type: array
          items:
            $ref: '#/components/schemas/BotCommand'
          maxItems: 32
          readOnly: false
    BotCommand:
      type: object
      description: Bot command with name and description
      properties:
        name:
          description: Command name
          type: string
          maxLength: 64
          minLength: 1
        description:
          description: Optional command description
          type: string
          minLength: 1
          maxLength: 128
          readOnly: false
          nullable: true
      required:
        - name
    Chat:
      type: object
      description: Chat, channel or dialog object 
      properties:
        chat_id:
          description: Chats identifier
          allOf:
            - $ref: '#/components/schemas/ChatId'
        type:
          description: 'Type of chat. One of: dialog, chat, channel'
          allOf:
            - $ref: '#/components/schemas/ChatType'
        status:
          description: |-
            Chat status. One of:
             - active: bot is active member of chat
             - removed: bot was kicked
             - left: bot intentionally left chat
             - closed: chat was closed
             - suspended: bot was stopped by user. *Only for dialogs*
          allOf:
            - $ref: '#/components/schemas/ChatStatus'
        title:
          description: Visible title of chat. Can be null for dialogs
          type: string
          nullable: true
          readOnly: false
        icon:
          description: Icon of chat
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Image'
          readOnly: false
        last_event_time:
          description: Time of last event occurred in chat
          type: integer
          format: int64
        participants_count:
          description: Number of people in chat. Always 2 for `dialog` chat type
          type: integer
          format: int32
        owner_id:
          description: Identifier of chat owner. Visible only for chat admins
          nullable: true
          allOf:
            - $ref: '#/components/schemas/UserId'
          readOnly: false
        participants:
          description: Participants in chat with time of last activity. Can be *null* when you request list of chats. Visible for chat admins only
          nullable: true
          readOnly: false
          type: object
          additionalProperties:
            type: integer
            format: int64
        is_public:
          description: Is current chat publicly available. Always `false` for dialogs
          type: boolean
        link:
          description: Link on chat
          type: string
          readOnly: false
          nullable: true
        description:
          description: Chat description
          type: string
          nullable: true
          readOnly: false
        dialog_with_user:
          description: Another user in conversation. For `dialog` type chats only
          allOf:
            - $ref: '#/components/schemas/UserWithPhoto'
          nullable: true
          readOnly: false
        messages_count:
          description: Messages count in chat. Only for group chats and channels. **Not available** for dialogs
          nullable: true
          readOnly: false
          type: integer
        pinned_message:
          description: Pinned message in chat or channel. Returned only when single chat is requested
          nullable: true
          readOnly: false
          allOf:
            - $ref: '#/components/schemas/Message'
      required:
        - chat_id
        - type
        - status
        - last_event_time
        - participants_count
        - is_public
    ChatType:
      type: string
      description: Type of chat. Dialog (one-on-one), chat or channel
      enum:
        - dialog
        - chat
        - channel
    ChatStatus:
      type: string
      description: Chat status for current bot
      enum:
        - active
        - removed
        - left
        - closed
        - suspended
    ChatList:
      type: object
      description: Paginated list of chats
      properties:
        chats:
          description: List of requested chats
          type: array
          items:
            $ref: '#/components/schemas/Chat'
        marker:
          description: Reference to the next page of requested chats
          nullable: true
          type: integer
          format: int64
          readOnly: false
      required:
        - chats
    ChatPatch:
      type: object
      description: Patch object for updating chat info
      properties:
        icon:
          readOnly: false
          nullable: true
          allOf:
            - $ref: '#/components/schemas/PhotoAttachmentRequestPayload'
        title:
          type: string
          minLength: 1
          maxLength: 200
          readOnly: false
          nullable: true
        description:
          description: Chat description up to 16k characters long. Pass empty string to remove description
          type: string
          maxLength: 16000
          readOnly: false
          nullable: true
        pin: 
          description: Identifier of message to be pinned in chat. In case you want to remove pin, use /unpin method
          type: string
          readOnly: false
          nullable: true
        notify:
          description: By default, participants will be notified about change with system message in chat/channel
          type: boolean
          default: true
          readOnly: false
          nullable: true
    ChatMember:
      type: object
      description: Chat or channel member with membership info 
      allOf:
        - $ref: '#/components/schemas/UserWithPhoto'
        - properties:
            last_access_time:
              description: User last activity time in chat or channel . Can be outdated for super chats and channels (equals to `join_time`)
              type: integer
              format: int64
            is_owner:
              type: boolean
            is_admin:
              type: boolean
            join_time:
              type: integer
              format: int64
            permissions:
              description: Permissions in chat if member is admin. `null` otherwise
              type: array
              uniqueItems: true
              nullable: true
              items:
                $ref: '#/components/schemas/ChatAdminPermission'
              readOnly: false
            alias:
              description: Alias in chat if member is admin. By default, `null`
              type: string
              nullable: true
              readOnly: false
          required:
            - last_access_time
            - is_owner
            - is_admin
            - join_time
    ChatAdminPermission:
      description: Chat admin permissions
      type: string
      enum:
        - read_all_messages
        - add_remove_members
        - add_admins
        - change_chat_info
        - pin_message
        - edit_link
        - write
        - edit
        - delete
        - can_call
        - view_stats
    ChatMembersList:
      type: object
      description: Paginated list of chat members
      properties:
        members:
          description: Participants in chat with time of last activity
          type: array
          items:
            $ref: '#/components/schemas/ChatMember'
        marker:
          description: Pointer to the next data page
          type: integer
          format: int64
          nullable: true
          readOnly: false
      required:
        - members
    Image:
      type: object
      description: Generic schema describing image object
      properties:
        url:
          description: URL of image
          type: string
      required:
        - url
    Subscription:
      type: object
      description: Schema to describe WebHook subscription
      properties:
        url:
          description: Webhook URL
          type: string
        time:
          description: Unix-time when subscription was created
          type: integer
          format: int64
        update_types:
          description: Update types bot subscribed for
          example: '["message_created", "bot_started"]'
          type: array
          nullable: true
          uniqueItems: true
          items:
            type: string
            minLength: 1
          readOnly: false
      required:
        - url
        - time
    Recipient:
      type: object
      description: New message recipient. Could be user, chat or channel 
      properties:
        chat_id:
          description: Chat or channel identifier
          allOf:
            - $ref: '#/components/schemas/ChatId'
          nullable: true
          readOnly: false
        chat_type:
          description: Chat type
          allOf:
            - $ref: '#/components/schemas/ChatType'
        user_id:
          description: User identifier, if message was sent to user
          allOf:
            - $ref: '#/components/schemas/UserId'
          nullable: true
          readOnly: false
        post_id:
          description: Post identifier for comments
          allOf:
            - $ref: '#/components/schemas/MessageId'
          nullable: true
          readOnly: false
      required:
        - chat_type
    Message:
      type: object
      description: Message in chat
      properties:
        sender:
          description: User who sent this message. Can be `null` if message has been posted on behalf of a channel
          allOf:
            - $ref: '#/components/schemas/User'
          readOnly: false
          nullable: true
        recipient:
          description: Message recipient. Could be user, chat or channel  
          allOf:
            - $ref: '#/components/schemas/Recipient'
        timestamp:
          description: Unix-time when message was created
          type: integer
          format: int64
        link:
          description: Forwarded or replied message
          nullable: true
          readOnly: false
          allOf:
            - $ref: '#/components/schemas/LinkedMessage'
        body:
          description: Body of created message. Text + attachments. Could be null if message contains only forwarded message
          allOf:
            - $ref: '#/components/schemas/MessageBody'
        stat:
          description: 'Message statistics. Available only for channels in getMessages method context'
          allOf:
            - $ref: '#/components/schemas/MessageStat'
          nullable: true
          readOnly: false
        url:
          description: Message public URL. Can be `null` for dialogs or non-public chats/channels
          type: string
          nullable: true
          readOnly: false
      required:
        - recipient
        - body
        - timestamp
    CommentMessage:
      type: object
      description: Comment message in chat. Unlike Message, has no public url and body has no attachments.
      properties:
        sender:
          description: User who sent this comment. Can be `null` if message has been posted on behalf of a channel
          allOf:
            - $ref: '#/components/schemas/User'
          readOnly: false
          nullable: true
        recipient:
          description: Message recipient. Could be user or chat, for comments - only channel
          allOf:
            - $ref: '#/components/schemas/Recipient'
        timestamp:
          description: Unix-time when message was created
          type: integer
          format: int64
        link:
          description: Forwarded or replied message
          nullable: true
          readOnly: false
          allOf:
            - $ref: '#/components/schemas/CommentLinkedMessage'
        body:
          description: Body of created comment. Text only, no attachments.
          allOf:
            - $ref: '#/components/schemas/CommentMessageBody'
        stat:
          description: 'Message statistics. Available only for channels in in getMessages method context'
          allOf:
            - $ref: '#/components/schemas/MessageStat'
          nullable: true
          readOnly: false
      required:
        - recipient
        - body
        - timestamp
    MessageStat:
      type: object
      description: Message statistics
      properties:
        views:
          type: integer
      required:
        - views
    MessageBody:
      description: Schema representing body of message
      type: object
      properties:
        mid:
          description: Unique identifier of message
          allOf:
            - $ref: '#/components/schemas/MessageId'
        seq:
          description: Sequence identifier of message in chat
          type: integer
          format: int64
        text:
          description: Message text
          type: string
          nullable: true
          readOnly: false
        attachments:
          description: Message attachments. Could be one of `Attachment` type. See description of this schema
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Attachment'
          readOnly: false
        markup:
          description: Message text markup. See formatting section in https://dev.max.ru/docs-api for more info
          type: array
          nullable: true
          readOnly: false
          items:
            $ref: '#/components/schemas/MarkupElement'
      required:
        - mid
        - seq
    CommentMessageBody:
      description: Schema representing body of a comment message. Unlike MessageBody, attachments are not allowed.
      type: object
      properties:
        mid:
          description: Unique identifier of message
          allOf:
            - $ref: '#/components/schemas/MessageId'
        seq:
          description: Sequence identifier of message in chat
          type: integer
          format: int64
        text:
          description: Message text
          type: string
          nullable: true
          readOnly: false
        markup:
          description: Message text markup. See Formatting section in https://dev.max.ru/docs-api for more info
          type: array
          nullable: true
          readOnly: false
          items:
            $ref: '#/components/schemas/MarkupElement'
      required:
        - mid
        - seq
    MessageList:
      type: object
      description: Paginated list of messages
      properties:
        messages:
          description: List of messages
          type: array
          items:
            $ref: '#/components/schemas/Message'
      required:
        - messages
    CommentMessageList:
      type: object
      description: Paginated list of comment messages
      properties:
        messages:
          description: List of comment messages
          type: array
          items:
            $ref: '#/components/schemas/CommentMessage'
      required:
        - messages
    TextFormat:
      description: Message text format
      type: string
      enum:
        - markdown
        - html
    NewMessageBody:
      type: object
      description: Body of a new message to send
      properties:
        text:
          description: Message text
          type: string
          maxLength: 4000
          nullable: true
          readOnly: false
        attachments:
          description: Message attachments. See `AttachmentRequest` and it's inheritors for full information
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/AttachmentRequest'
          readOnly: false
        link:
          description: Link to Message
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/NewMessageLink'
          readOnly: false
        notify:
          description: If false, chat participants would not be notified
          type: boolean
          default: true
          readOnly: false
        format:
          description: If set, message text will be formatted according to given markup
          readOnly: false
          nullable: true
          allOf:
            - $ref: '#/components/schemas/TextFormat'
    NewCommentBody:
      type: object
      description: Body of a new comment to send. Unlike NewMessageBody, attachments are not allowed.
      properties:
        text:
          description: Message text
          type: string
          maxLength: 4000
          nullable: true
          readOnly: false
        link:
          description: Link to Message
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/NewMessageLink'
          readOnly: false
        format:
          description: If set, message text will be formatted according to given markup
          readOnly: false
          nullable: true
          allOf:
            - $ref: '#/components/schemas/TextFormat'
    NewMessageLink:
      type: object
      description: Link to a message for reply or forward
      properties:
        type:
          description: Type of message link
          nullable: false
          allOf:
            - $ref: '#/components/schemas/MessageLinkType'
        mid:
          description: Message identifier of original message
          allOf:
            - $ref: '#/components/schemas/MessageId'
          nullable: false
      required:
        - type
        - mid
    LinkedMessage:
      type: object
      description: Forwarded or replied message
      properties:
        type:
          description: Type of linked message
          allOf:
            - $ref: '#/components/schemas/MessageLinkType'
        sender:
          description: User sent this message. Can be `null` if message has been posted on behalf of a channel
          allOf:
            - $ref: '#/components/schemas/User'
          readOnly: false
          nullable: true
        chat_id:
          description: Chat where message has been originally posted
          allOf:
            - $ref: '#/components/schemas/ChatId'
          readOnly: false
        message:
          allOf:
            - $ref: '#/components/schemas/MessageBody'
      required:
        - type
        - message
    CommentLinkedMessage:
      type: object
      description: Forwarded or replied comment. Unlike LinkedMessage, `message` is a CommentMessageBody (no attachments, as comments cannot have them)
      properties:
        type:
          description: Type of linked message
          allOf:
            - $ref: '#/components/schemas/MessageLinkType'
        sender:
          description: User sent this message. Can be `null` if message has been posted on behalf of a channel
          allOf:
            - $ref: '#/components/schemas/User'
          readOnly: false
          nullable: true
        chat_id:
          description: Chat where message has been originally posted
          allOf:
            - $ref: '#/components/schemas/ChatId'
          readOnly: false
        message:
          allOf:
            - $ref: '#/components/schemas/CommentMessageBody'
      required:
        - type
        - message
    SendMessageResult:
      type: object
      description: Result of sending a message
      properties:
        message:
          $ref: '#/components/schemas/Message'
      required:
        - message
    SendCommentResult:
      type: object
      description: Result of sending a comment
      properties:
        message:
          $ref: '#/components/schemas/CommentMessage'
      required:
        - message
    Attachment:
      type: object
      description: Generic schema representing message attachment
      discriminator:
        propertyName: type
        mapping:
          image: '#/components/schemas/PhotoAttachment'
          video: '#/components/schemas/VideoAttachment'
          audio: '#/components/schemas/AudioAttachment'
          file: '#/components/schemas/FileAttachment'
          sticker: '#/components/schemas/StickerAttachment'
          contact: '#/components/schemas/ContactAttachment'
          inline_keyboard: '#/components/schemas/InlineKeyboardAttachment'
          share: '#/components/schemas/ShareAttachment'
          location: '#/components/schemas/LocationAttachment'
      properties:
        type:
          type: string
      required:
        - type
    PhotoAttachment:
      type: object
      description: Image attachment
      allOf:
        - $ref: '#/components/schemas/Attachment'
        - properties:
            payload:
              $ref: '#/components/schemas/PhotoAttachmentPayload'
          required:
            - payload
    PhotoAttachmentPayload:
      type: object
      description: Payload of photo attachment containing image metadata
      properties:
        photo_id:
          description: Unique identifier of this image
          type: integer
          format: int64
        token:
          description: ''
          type: string
        url:
          description: Image URL
          type: string
      required:
        - photo_id
        - url
        - token
    VideoAttachment:
      type: object
      description: Video attachment
      allOf:
        - $ref: '#/components/schemas/Attachment'
        - properties:
            payload:
              $ref: '#/components/schemas/MediaAttachmentPayload'
            thumbnail:
              description: Video thumbnail
              nullable: true
              readOnly: false
              allOf:
                - $ref: '#/components/schemas/VideoThumbnail'
            width:
              description: Video width
              type: integer
              nullable: true
              readOnly: false
            height:
              description: Video height
              type: integer
              nullable: true
              readOnly: false
            duration:
              description: Video duration in seconds
              type: integer
              nullable: true
              readOnly: false
          required:
            - payload
    VideoThumbnail:
      type: object
      description: Video thumbnail image
      properties:
        url:
          description: Image URL
          type: string
      required:
        - url
    VideoUrls:
      type: object
      description: Available video download and streaming URLs by resolution
      properties:
        mp4_1080:
          description: Video URL in 1080p resolution, if available
          type: string
          nullable: true
          readOnly: false
        mp4_720:
          description: Video URL in 720 resolution, if available
          type: string
          nullable: true
          readOnly: false
        mp4_480:
          description: Video URL in 480 resolution, if available
          type: string
          nullable: true
          readOnly: false
        mp4_360:
          description: Video URL in 360 resolution, if available
          type: string
          nullable: true
          readOnly: false
        mp4_240:
          description: Video URL in 240 resolution, if available
          type: string
          nullable: true
          readOnly: false
        mp4_144:
          description: Video URL in 144 resolution, if available
          type: string
          nullable: true
          readOnly: false
        hls:
          description: Live streaming URL, if available
          type: string
          nullable: true
          readOnly: false
    VideoAttachmentDetails:
      type: object
      description: Detailed information about video attachment including direct URLs
      properties:
        token:
          description: Video attachment token
          type: string
        urls:
          description: URLs to download or play video. Can be null if video is unavailable
          nullable: true
          readOnly: false
          allOf:
            - $ref: "#/components/schemas/VideoUrls"
        thumbnail:
          description: Video thumbnail
          nullable: true
          readOnly: false
          allOf:
            - $ref: '#/components/schemas/PhotoAttachmentPayload'
        width:
          description: Video width
          type: integer
        height:
          description: Video height
          type: integer
        duration:
          description: Video duration in seconds
          type: integer
      required:
        - width
        - height
        - duration
        - token
    AudioAttachment:
      type: object
      description: Audio attachment
      allOf:
        - $ref: '#/components/schemas/Attachment'
        - properties:
            payload:
              $ref: '#/components/schemas/MediaAttachmentPayload'
            transcription:
              description: Audio transcription
              type: string
              nullable: true
              readOnly: false
          required:
            - payload
    FileAttachment:
      type: object
      description: File attachment
      allOf:
        - $ref: '#/components/schemas/Attachment'
        - properties:
            payload:
              $ref: '#/components/schemas/FileAttachmentPayload'
            filename:
              description: Uploaded file name
              type: string
            size:
              description: File size in bytes
              type: integer
              format: int64
          required:
            - payload
            - filename
            - size
    AttachmentPayload:
      type: object
      description: Base payload for message attachments containing media URL
      properties:
        url:
          description: |-
            Media attachment URL.
            For video attachments use getVideoAttachmentDetails method to obtain direct links.
          type: string
      required:
        - url
    MediaAttachmentPayload:
      type: object
      description: Payload for media (video/audio) attachments with reuse token
      allOf:
        - $ref: '#/components/schemas/AttachmentPayload'
        - properties:
            token:
              description: Use `token` in case when you are trying to reuse the same attachment in other message
              type: string
          required:
            - token
    FileAttachmentPayload:
      type: object
      description: Payload for file attachments with reuse token
      allOf:
        - $ref: '#/components/schemas/AttachmentPayload'
        - properties:
            token:
              description: Use `token` in case when you are trying to reuse the same attachment in other message
              type: string
          required:
            - token
    ContactAttachment:
      type: object
      description: Contact attachment
      allOf:
        - $ref: '#/components/schemas/Attachment'
        - properties:
            payload:
              $ref: '#/components/schemas/ContactAttachmentPayload'
          required:
            - payload
    ContactAttachmentPayload:
      type: object
      description: Payload of contact attachment containing user contact info
      properties:
        vcf_info:
          description: User info in VCF format
          nullable: true
          readOnly: false
          type: string
        hash:
          description: User info in VCF format hash
          nullable: true
          readOnly: false
          type: string
        max_info:
          description: User info
          nullable: true
          readOnly: false
          allOf:
            - $ref: '#/components/schemas/User'
    StickerAttachmentPayload:
      type: object
      description: Payload of sticker attachment
      allOf:
        - $ref: '#/components/schemas/AttachmentPayload'
        - properties:
            code:
              description: Sticker identifier
              type: string
          required:
            - code
    StickerAttachment:
      type: object
      description: Sticker attachment
      allOf:
        - $ref: '#/components/schemas/Attachment'
        - properties:
            payload:
              $ref: '#/components/schemas/StickerAttachmentPayload'
            width:
              description: Sticker width
              type: integer
            height:
              description: Sticker height
              type: integer
          required:
            - payload
            - width
            - height
    ShareAttachmentPayload:
      type: object
      description: Payload of ShareAttachmentRequest
      properties:
        url:
          description: URL attached to message as media preview
          minLength: 1
          type: string
          nullable: true
          readOnly: false
        token:
          description: Attachment token
          type: string
          nullable: true
          readOnly: false
    ShareAttachment:
      type: object
      description: Link preview attachment with media
      allOf:
        - $ref: '#/components/schemas/Attachment'
        - properties:
            payload:
              $ref: '#/components/schemas/ShareAttachmentPayload'
            title:
              description: Link preview title
              type: string
              readOnly: false
              nullable: true
            description:
              description: Link preview description
              type: string
              readOnly: false
              nullable: true
            image_url:
              description: Link preview image
              type: string
              nullable: true
              readOnly: false
          required:
            - payload
    LocationAttachment:
      type: object
      description: Geographic location attachment
      allOf:
        - $ref: '#/components/schemas/Attachment'
        - properties:
            latitude:
              type: number
              format: double
            longitude:
              type: number
              format: double
          required:
            - latitude
            - longitude
    InlineKeyboardAttachment:
      type: object
      description: Buttons in messages
      allOf:
        - $ref: '#/components/schemas/Attachment'
        - properties:
            payload:
              $ref: '#/components/schemas/Keyboard'
          required:
            - payload
    Keyboard:
      type: object
      description: Keyboard is two-dimension array of buttons
      properties:
        buttons:
          type: array
          items:
            type: array
            items:
              $ref: '#/components/schemas/Button'
      required:
        - buttons
    Button:
      type: object
      description: Inline keyboard button
      properties:
        type:
          type: string
        text:
          description: Visible text of button
          type: string
          minLength: 1
          maxLength: 128
      discriminator:
        propertyName: type
        mapping:
          callback: '#/components/schemas/CallbackButton'
          link: '#/components/schemas/LinkButton'
          request_geo_location: '#/components/schemas/RequestGeoLocationButton'
          request_contact: '#/components/schemas/RequestContactButton'
          message: '#/components/schemas/MessageButton'
          open_app: '#/components/schemas/OpenAppButton'
          clipboard: '#/components/schemas/ClipboardButton'
      required:
        - type
        - text
    CallbackButton:
      type: object
      description: After pressing this type of button client sends to server payload it contains
      allOf:
        - $ref: '#/components/schemas/Button'
        - properties:
            payload:
              description: Button payload
              type: string
              maxLength: 1024
          required:
            - payload
    LinkButton:
      type: object
      description: After pressing this type of button user follows the link it contains
      allOf:
        - $ref: '#/components/schemas/Button'
        - properties:
            url:
              type: string
              maxLength: 2048
          required:
            - url
    MessageButton:
      type: object
      description: After pressing this type of button it sends message from user in chat
      allOf:
        - $ref: '#/components/schemas/Button'
    RequestContactButton:
      type: object
      description: After pressing this type of button client sends new message with attachment of current user contact
      allOf:
        - $ref: '#/components/schemas/Button'
    RequestGeoLocationButton:
      type: object
      description: After pressing this type of button client sends new message with attachment of current user geo location
      allOf:
        - $ref: '#/components/schemas/Button'
        - properties:
            quick:
              description: If *true*, sends location without asking user's confirmation
              readOnly: false
              type: boolean
              default: false
    OpenAppButton:
      type: object
      description: After pressing this type of button client opens mini app
      allOf:
        - $ref: '#/components/schemas/Button'
        - properties:
            payload:
              description: Button payload
              nullable: true
              readOnly: false
              type: string
              pattern: '^[\w-]*$'
              maxLength: 512
            web_app:
              description: Unique public name of the bot wired to the mini app
              type: string
            contact_id:
              description: Unique identifier of the bot wired to the mini app
              nullable: true
              readOnly: false
              allOf:
                - $ref: '#/components/schemas/UserId'
          required:
            - web_app
    ClipboardButton:
      type: object
      description: After pressing this type of button client copies payload data to clipboard
      allOf:
        - $ref: '#/components/schemas/Button'
        - properties:
            payload:
              description: Button payload
              type: string
              maxLength: 1024
          required:
            - payload
    MessageLinkType:
      description: Type of linked message
      type: string
      enum:
        - forward
        - reply
    AttachmentRequest:
      type: object
      description: Request to attach some data to message
      discriminator:
        propertyName: type
        mapping:
          image: '#/components/schemas/PhotoAttachmentRequest'
          video: '#/components/schemas/VideoAttachmentRequest'
          audio: '#/components/schemas/AudioAttachmentRequest'
          file: '#/components/schemas/FileAttachmentRequest'
          sticker: '#/components/schemas/StickerAttachmentRequest'
          contact: '#/components/schemas/ContactAttachmentRequest'
          inline_keyboard: '#/components/schemas/InlineKeyboardAttachmentRequest'
          location: '#/components/schemas/LocationAttachmentRequest'
          share: '#/components/schemas/ShareAttachmentRequest'
      properties:
        type:
          type: string
      required:
        - type
    PhotoAttachmentRequest:
      type: object
      description: Request to attach image to message
      allOf:
        - $ref: '#/components/schemas/AttachmentRequest'
        - properties:
            payload:
              $ref: '#/components/schemas/PhotoAttachmentRequestPayload'
          required:
            - payload
    PhotoAttachmentRequestPayload:
      type: object
      description: Request to attach image. All fields are mutually exclusive
      properties:
        url:
          description: Any external image URL you want to attach
          minLength: 1
          nullable: true
          readOnly: false
          type: string
        token:
          description: Token of any existing attachment
          nullable: true
          readOnly: false
          type: string
        photos:
          description: Tokens were obtained after uploading images
          nullable: true
          readOnly: false
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PhotoToken'
    PhotoToken:
      type: object
      description: Token representing an uploaded image
      properties:
        token:
          description: Encoded information of uploaded image
          type: string
      required:
        - token
    VideoAttachmentRequest:
      type: object
      description: Request to attach video to message
      allOf:
        - $ref: '#/components/schemas/AttachmentRequest'
        - properties:
            payload:
              $ref: '#/components/schemas/UploadedInfo'
          required:
            - payload
    AudioAttachmentRequest:
      type: object
      description: Request to attach audio to message. MUST be the only attachment in message
      allOf:
        - $ref: '#/components/schemas/AttachmentRequest'
        - properties:
            payload:
              $ref: '#/components/schemas/UploadedInfo'
          required:
            - payload
    UploadedInfo:
      type: object
      description: This is information you will receive as soon as audio/video is uploaded
      properties:
        token:
          description: Token is unique uploaded media identifier
          type: string
          readOnly: false
    FileAttachmentRequest:
      type: object
      description: Request to attach file to message. MUST be the only attachment in message
      allOf:
        - $ref: '#/components/schemas/AttachmentRequest'
        - properties:
            payload:
              $ref: '#/components/schemas/UploadedInfo'
          required:
            - payload
    UploadType:
      type: string
      description: Type of file uploading
      enum:
        - image
        - video
        - audio
        - file
    ContactAttachmentRequest:
      type: object
      description: Request to attach contact card to message. MUST be the only attachment in message
      allOf:
        - $ref: '#/components/schemas/AttachmentRequest'
        - properties:
            payload:
              $ref: '#/components/schemas/ContactAttachmentRequestPayload'
          required:
            - payload
    ContactAttachmentRequestPayload:
      type: object
      description: Payload for contact attachment request
      properties:
        name:
          description: Contact name
          nullable: true
          type: string
          readOnly: false
        contact_id:
          description: Contact identifier if it is registered Max user
          nullable: true
          readOnly: false
          allOf:
            - $ref: '#/components/schemas/UserId'
        vcf_info:
          description: Full information about contact in VCF format
          nullable: true
          readOnly: false
          type: string
        vcf_phone:
          description: Contact phone in VCF format
          readOnly: false
          nullable: true
          type: string
    StickerAttachmentRequest:
      type: object
      description: Request to attach sticker. MUST be the only attachment request in message
      allOf:
        - $ref: '#/components/schemas/AttachmentRequest'
        - properties:
            payload:
              $ref: '#/components/schemas/StickerAttachmentRequestPayload'
          required:
            - payload
    StickerAttachmentRequestPayload:
      type: object
      description: Payload for sticker attachment request
      properties:
        code:
          description: Sticker code
          type: string
      required:
        - code
    InlineKeyboardAttachmentRequest:
      type: object
      description: Request to attach keyboard to message
      allOf:
        - $ref: '#/components/schemas/AttachmentRequest'
        - properties:
            payload:
              $ref: '#/components/schemas/InlineKeyboardAttachmentRequestPayload'
          required:
            - payload
    InlineKeyboardAttachmentRequestPayload:
      type: object
      description: Payload for inline keyboard attachment request
      properties:
        buttons:
          description: Two-dimensional array of buttons
          type: array
          minItems: 1
          items:
            type: array
            items:
              $ref: '#/components/schemas/Button'
      required:
        - buttons
    LocationAttachmentRequest:
      type: object
      description: Request to attach geographic location to message
      allOf:
        - $ref: '#/components/schemas/AttachmentRequest'
        - properties:
            latitude:
              type: number
              format: double
            longitude:
              type: number
              format: double
          required:
            - latitude
            - longitude
    ShareAttachmentRequest:
      type: object
      description: Request to attach media preview of any external URL
      allOf:
        - $ref: '#/components/schemas/AttachmentRequest'
        - properties:
            payload:
              $ref: '#/components/schemas/ShareAttachmentPayload'
          required:
            - payload
    MarkupElement:
      type: object
      description: Base type for text markup (formatting) elements
      properties:
        type:
          description: Type of the markup element.
            Can be **strong**,
            *emphasized*, ~strikethrough~, ++underline++, `monospaced`, highlighted, link, quote, header or user_mention 
          type: string
        from:
          description: Element start index (zero-based) in text
          type: integer
          format: int32
        length:
          description: Length of the markup element
          type: integer
          format: int32
      discriminator:
        propertyName: type
        mapping:
          strong: '#/components/schemas/StrongMarkup'
          emphasized: '#/components/schemas/EmphasizedMarkup'
          monospaced: '#/components/schemas/MonospacedMarkup'
          link: '#/components/schemas/LinkMarkup'
          strikethrough: '#/components/schemas/StrikethroughMarkup'
          underline: '#/components/schemas/UnderlineMarkup'
          user_mention: '#/components/schemas/UserMentionMarkup'
          heading: '#/components/schemas/HeadingMarkup'
          highlighted: '#/components/schemas/HighlightedMarkup'
          quote: '#/components/schemas/QuoteMarkup'
      required:
        - type
        - from
        - length
    StrongMarkup:
      type: object
      description: Represents **bold** in text
      allOf:
        - $ref: '#/components/schemas/MarkupElement'
    EmphasizedMarkup:
      type: object
      description: Represents *italic* in text
      allOf:
        - $ref: '#/components/schemas/MarkupElement'
    MonospacedMarkup:
      type: object
      description: Represents `monospaced` or ```code``` block in text
      allOf:
        - $ref: '#/components/schemas/MarkupElement'
    LinkMarkup:
      type: object
      description: Represents link in text
      allOf:
        - $ref: '#/components/schemas/MarkupElement'
        - properties:
            url:
              description: Link's URL
              type: string
              minLength: 1
              maxLength: 2048
          required:
            - url
    StrikethroughMarkup:
      type: object
      description: Represents ~strikethrough~ block in text
      allOf:
        - $ref: '#/components/schemas/MarkupElement'
    UnderlineMarkup:
      type: object
      description: Represents ++underlined++ part of the text
      allOf:
        - $ref: '#/components/schemas/MarkupElement'
    HeadingMarkup:
      type: object
      description: Represents header part of the text
      allOf:
        - $ref: '#/components/schemas/MarkupElement'
    UserMentionMarkup:
      type: object
      description: Represents user mention in text. Mention can be both by user's username or ID if user doesn't have username
      allOf:
        - $ref: '#/components/schemas/MarkupElement'
        - properties:
            user_link:
              description: '`@username` of mentioned user'
              type: string
              nullable: true
              readOnly: false
            user_id:
              description: Identifier of mentioned user without username
              allOf:
                - $ref: '#/components/schemas/UserId'
              nullable: true
              readOnly: false
    HighlightedMarkup:
      type: object
      description: Represents a highlighted piece of text
      allOf:
        - $ref: '#/components/schemas/MarkupElement'
    QuoteMarkup:
      type: object
      description: Represents quote block in text
      allOf:
        - $ref: '#/components/schemas/MarkupElement'
    SubscriptionRequestBody:
      type: object
      description: Request to set up WebHook subscription
      properties:
        url:
          $ref: '#/components/schemas/SubscriptionUrl'
        secret:
          description: A secret to be sent in a header “X-Max-Bot-Api-Secret” in every webhook request, 5-256 characters. Only characters A-Z, a-z, 0-9, _ and - are allowed. The header is useful to ensure that the request comes from a webhook set by you.
          type: string
          pattern: '^[\w-]+$'
          minLength: 5
          maxLength: 256
          readOnly: false
        update_types:
          description: List of update types your bot want to receive. See `Update` object for a complete list of types
          example: '["message_created", "bot_started"]'
          type: array
          uniqueItems: true
          items:
            type: string
          readOnly: false
      required:
        - url
    GetSubscriptionsResult:
      type: object
      description: List of all WebHook subscriptions
      properties:
        subscriptions:
          description: Current subscriptions
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
      required:
        - subscriptions
    SimpleQueryResult:
      type: object
      description: Simple response to request
      properties:
        success:
          description: '`true` if request was successful. `false` otherwise'
          type: boolean
        message:
          description: Explanatory message if the result is not successful
          type: string
          readOnly: false
      required:
        - success
    PinMessageBody:
      type: object
      description: Request body for pinning a message in chat
      properties:
        message_id:
          description: Identifier of message to be pinned in chat
          allOf:
            - $ref: '#/components/schemas/MessageId'
        notify:
          description: If `true`, participants will be notified with system message in chat/channel
          type: boolean
          default: true
          readOnly: false
          nullable: true
      required:
        - message_id
    GetPinnedMessageResult:
      type: object
      description: Result of getting pinned message in chat
      properties:
        message:
          description: Pinned message. Can be `null` if no message pinned in chat
          readOnly: false
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Message'
    Callback:
      type: object
      description: Object sent to bot when user presses button
      properties:
        timestamp:
          description: Unix-time when user pressed the button
          type: integer
          format: int64
        callback_id:
          description: Current keyboard identifier
          type: string
        payload:
          description: Button payload
          type: string
          readOnly: false
        user:
          description: User pressed the button
          allOf:
            - $ref: '#/components/schemas/User'
      required:
        - timestamp
        - callback_id
        - user
    CallbackAnswer:
      type: object
      description: Send this object when your bot wants to react to when a button is pressed
      properties:
        message:
          description: Fill this if you want to modify current message
          nullable: true
          readOnly: false
          allOf:
            - $ref: '#/components/schemas/NewMessageBody'
        notification:
          description: Fill this if you just want to send one-time notification to user
          nullable: true
          readOnly: false
          type: string
    Error:
      type: object
      description: Server returns this if there was an exception to your request
      properties:
        error: 
          description: Error
          type: string
        code:
          description: Error code
          type: string
        message:
          description: Human-readable description
          type: string
      required:
        - code
        - message
    UploadEndpoint:
      description: Endpoint you should upload to your binaries
      type: object
      properties:
        url:
          description: URL to upload
          type: string
        token:
          description: Video or audio token for send message
          type: string
          readOnly: false
          nullable: true
      required:
        - url
    UserIdsList:
      type: object
      description: List of user identifiers
      properties:
        user_ids:
          items:
            $ref: '#/components/schemas/UserId'
          maxItems: 100
      required:
        - user_ids
    ActionRequestBody:
      type: object
      description: Request body for sending action to chat
      properties:
        action:
          $ref: '#/components/schemas/SenderAction'
      required:
        - action
    ChatAdminsList:
      type: object
      description: List of chat administrators with permissions
      properties:
        admins:
          type: array
          items:
            $ref: '#/components/schemas/ChatAdmin'
      required:
        - admins
    ChatAdmin:
      type: object
      description: Administrator id with permissions
      properties:
        user_id:
          $ref: '#/components/schemas/UserId'
        permissions:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ChatAdminPermission'
        alias:
          description: Alias of the admin in chat. By default, `null`
          type: string
          readOnly: false
          nullable: true
      required:
        - user_id
        - permissions
    SenderAction:
      type: string
      description: Different actions to send to chat members
      enum:
        - typing_on
        - sending_photo
        - sending_video
        - sending_audio
        - sending_file
        - mark_seen
    UpdateList:
      type: object
      description: List of all updates in chats your bot participated in
      properties:
        updates:
          description: Page of updates
          type: array
          items:
            $ref: '#/components/schemas/Update'
        marker:
          description: Pointer to the next data page
          type: integer
          format: int64
          nullable: true
          readOnly: false
      required:
        - updates
    Update:
      type: object
      description: '`Update` object represents different types of events that happened in chat. See its inheritors'
      discriminator:
        propertyName: update_type
        mapping:
          message_created: '#/components/schemas/MessageCreatedUpdate'
          message_callback: '#/components/schemas/MessageCallbackUpdate'
          message_edited: '#/components/schemas/MessageEditedUpdate'
          message_removed: '#/components/schemas/MessageRemovedUpdate'
          comment_created: '#/components/schemas/CommentCreatedUpdate'
          comment_edited: '#/components/schemas/CommentEditedUpdate'
          comment_removed: '#/components/schemas/CommentRemovedUpdate'
          bot_added: '#/components/schemas/BotAddedToChatUpdate'
          bot_removed: '#/components/schemas/BotRemovedFromChatUpdate'
          user_added: '#/components/schemas/UserAddedToChatUpdate'
          user_removed: '#/components/schemas/UserRemovedFromChatUpdate'
          bot_started: '#/components/schemas/BotStartedUpdate'
          bot_stopped: '#/components/schemas/BotStoppedUpdate'
          dialog_cleared: '#/components/schemas/DialogClearedUpdate'
          dialog_removed: '#/components/schemas/DialogRemovedUpdate'
          dialog_muted: '#/components/schemas/DialogMutedUpdate'
          dialog_unmuted: '#/components/schemas/DialogUnmutedUpdate'
          chat_title_changed: '#/components/schemas/ChatTitleChangedUpdate'
          bot_admin_permissions_changed: '#/components/schemas/BotAdminPermissionsChangedUpdate'
      properties:
        update_type:
          type: string
        timestamp:
          description: Unix-time when event has occurred
          type: integer
          format: int64
      required:
        - update_type
        - timestamp
    MessageCallbackUpdate:
      type: object
      description: You will get this `update` as soon as user presses button
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            callback:
              description: ''
              allOf:
                - $ref: '#/components/schemas/Callback'
            message:
              description: Original message containing inline keyboard. Can be `null` in case it had been deleted by the moment a bot got this update
              nullable: true
              allOf:
                - $ref: '#/components/schemas/Message'
              readOnly: false
            user_locale:
              description: Current user locale in IETF BCP 47 format
              type: string
              nullable: true
              readOnly: false
          required:
            - callback
    MessageCreatedUpdate:
      type: object
      description: You will get this `update` as soon as message is created. In group chats bot receives this update only if it is administrator with `read_all_messages` permission
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            message:
              description: Newly created message
              allOf:
                - $ref: '#/components/schemas/Message'
            user_locale:
              description: Current user locale in IETF BCP 47 format. Available only in dialogs
              type: string
              readOnly: false
              nullable: true
          required:
            - message
    MessageRemovedUpdate:
      type: object
      description: You will get this `update` as soon as message is removed. In group chats bot receives this update only if it is administrator with `read_all_messages` permission
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            message_id:
              description: Identifier of removed message
              allOf:
                - $ref: '#/components/schemas/MessageId'
            chat_id:
              description: Chat identifier where message has been deleted
              allOf:
                - $ref: '#/components/schemas/ChatId'
            user_id:
              description: User who deleted this message
              allOf:
                - $ref: '#/components/schemas/UserId'
          required:
            - message_id
            - chat_id
            - user_id
    MessageEditedUpdate:
      type: object
      description: You will get this `update` as soon as message is edited. In group chats bot receives this update only if it is administrator with `read_all_messages` permission
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            message:
              description: Edited message
              allOf:
                - $ref: '#/components/schemas/Message'
          required:
            - message
    CommentCreatedUpdate:
      type: object
      description: You will get this `update` as soon as comment is created. Bot receives this update only if it is administrator of the channel with `read_all_messages` permission
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            message:
              description: Newly created comment
              allOf:
                - $ref: '#/components/schemas/Message'
          required:
            - message
    CommentRemovedUpdate:
      type: object
      description: You will get this `update` as soon as comment is removed. Bot receives this update only if it is administrator of the channel with `read_all_messages` permission
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            message_id:
              description: Identifier of removed comment
              allOf:
                - $ref: '#/components/schemas/MessageId'
            chat_id:
              description: Chat identifier where comment has been deleted
              allOf:
                - $ref: '#/components/schemas/ChatId'
            user_id:
              description: User who deleted this comment
              allOf:
                - $ref: '#/components/schemas/UserId'
            post_id:
              description: Post identifier
              allOf:
                - $ref: '#/components/schemas/MessageId'
          required:
            - message_id
            - chat_id
            - user_id
            - post_id
    CommentEditedUpdate:
      type: object
      description: You will get this `update` as soon as comment is edited. Bot receives this update only if it is administrator of the channel with `read_all_messages` permission
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            message:
              description: Edited comment
              allOf:
                - $ref: '#/components/schemas/Message'
          required:
            - message
    BotAddedToChatUpdate:
      type: object
      description: You will receive this update when bot has been added to chat
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            chat_id:
              description: Chat id where bot was added
              allOf:
                - $ref: '#/components/schemas/ChatId'
            user:
              description: User who added bot to chat
              allOf:
                - $ref: '#/components/schemas/User'
            is_channel:
              description: Indicates whether bot has been added to channel or not
              type: boolean
          required:
            - chat_id
            - user
            - is_channel
    BotRemovedFromChatUpdate:
      type: object
      description: You will receive this update when bot has been removed from chat
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            chat_id:
              description: Chat identifier bot removed from
              allOf:
                - $ref: '#/components/schemas/ChatId'
            user:
              description: User who removed bot from chat
              allOf:
                - $ref: '#/components/schemas/User'
            is_channel:
              description: Indicates whether bot has been removed from channel or not
              type: boolean
          required:
            - chat_id
            - user
            - is_channel
    UserAddedToChatUpdate:
      type: object
      description: You will receive this update when user has been added to chat where bot is administrator with `read_all_messages` permission
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            chat_id:
              description: Chat identifier where event has occurred
              allOf:
                - $ref: '#/components/schemas/ChatId'
            user:
              description: User added to chat
              allOf:
                - $ref: '#/components/schemas/User'
            inviter_id:
              description: User who added user to chat. Can be `null` in case when user joined chat by link
              allOf:
                - $ref: '#/components/schemas/UserId'
              readOnly: false
              nullable: true
            is_channel:
              description: Indicates whether user has been added to channel or not
              type: boolean
          required:
            - chat_id
            - user
            - is_channel
    UserRemovedFromChatUpdate:
      type: object
      description: You will receive this update when user has been removed from chat where bot is administrator with `read_all_messages` permission
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            chat_id:
              description: Chat identifier where event has occurred
              allOf:
                - $ref: '#/components/schemas/ChatId'
            user:
              description: User removed from chat
              allOf:
                - $ref: '#/components/schemas/User'
            admin_id:
              description: Administrator who removed user from chat. Can be `null` in case when user left chat
              allOf:
                - $ref: '#/components/schemas/UserId'
              readOnly: false
            is_channel:
              description: Indicates whether user has been removed from channel or not
              type: boolean
          required:
            - chat_id
            - user
            - is_channel
    BotStartedUpdate:
      type: object
      description: Bot gets this type of update as soon as user pressed `Start` button
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            chat_id:
              description: Dialog identifier where event has occurred
              allOf:
                - $ref: '#/components/schemas/ChatId'
            user:
              description: User pressed the 'Start' button
              allOf:
                - $ref: '#/components/schemas/User'
            payload:
              description: Additional data from deep-link passed on bot startup
              type: string
              maxLength: 512
              nullable: true
              readOnly: false
            user_locale:
              description: Current user locale in IETF BCP 47 format
              type: string
              readOnly: false
          required:
            - chat_id
            - user
    BotStoppedUpdate:
      type: object
      description: Bot gets this type of update as soon as bot has been stopped
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            chat_id:
              description: Dialog identifier where event has occurred
              allOf:
                - $ref: '#/components/schemas/ChatId'
            user:
              description: User who stopped the bot
              allOf:
                - $ref: '#/components/schemas/User'
            user_locale:
              description: Current user locale in IETF BCP 47 format
              type: string
              readOnly: false
          required:
            - chat_id
            - user
    DialogClearedUpdate:
      type: object
      description: Bot gets this type of update as soon as dialog history has been cleared
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            chat_id:
              description: Dialog identifier where event has occurred
              allOf:
                - $ref: '#/components/schemas/ChatId'
            user:
              description: User who cleared the dialog
              allOf:
                - $ref: '#/components/schemas/User'
            user_locale:
              description: Current user locale in IETF BCP 47 format
              type: string
              readOnly: false
          required:
            - chat_id
            - user
    DialogRemovedUpdate:
      type: object
      description: Bot gets this type of update as soon as dialog has been removed
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            chat_id:
              description: Dialog identifier where event has occurred
              allOf:
                - $ref: '#/components/schemas/ChatId'
            user:
              description: User who removed the dialog
              allOf:
                - $ref: '#/components/schemas/User'
            user_locale:
              description: Current user locale in IETF BCP 47 format
              type: string
              readOnly: false
          required:
            - chat_id
            - user
    DialogMutedUpdate:
      type: object
      description: Bot gets this type of update as soon as dialog has been muted
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            chat_id:
              description: Dialog identifier where event has occurred
              allOf:
                - $ref: '#/components/schemas/ChatId'
            user:
              description: User who muted the dialog
              allOf:
                - $ref: '#/components/schemas/User'
            muted_until:
              description: Unix-time until which the dialog was muted
              type: integer
              format: int64
            user_locale:
              description: Current user locale in IETF BCP 47 format
              type: string
              readOnly: false
          required:
            - chat_id
            - user
            - muted_until
    DialogUnmutedUpdate:
      type: object
      description: Bot gets this type of update as soon as dialog has been unmuted
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            chat_id:
              description: Dialog identifier where event has occurred
              allOf:
                - $ref: '#/components/schemas/ChatId'
            user:
              description: User who unmuted the dialog
              allOf:
                - $ref: '#/components/schemas/User'
            user_locale:
              description: Current user locale in IETF BCP 47 format
              type: string
              readOnly: false
          required:
            - chat_id
            - user
    ChatTitleChangedUpdate:
      type: object
      description: Bot gets this type of update as soon as title has been changed in chat
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            chat_id:
              description: Chat identifier where event has occurred
              allOf:
                - $ref: '#/components/schemas/ChatId'
            user:
              description: User who changed title
              allOf:
                - $ref: '#/components/schemas/User'
            title:
              description: New title
              type: string
          required:
            - chat_id
            - user
            - title
    BotAdminPermissionsChangedUpdate:
      type: object
      description: Bot will get this update when bot admin permissions changed
      allOf:
        - $ref: '#/components/schemas/Update'
        - properties:
            chat_id:
              description: Chat identifier where event has occurred
              allOf:
                - $ref: '#/components/schemas/ChatId'
            user_id:
              description: User or bot who changed bot admin permissions
              allOf:
                - $ref: '#/components/schemas/UserId'
            bot_id:
              description: Bot that admin permissions changed
              allOf:
                - $ref: '#/components/schemas/UserId'
            is_channel:
              description: Indicates whether bot admin permissions has been changed in channel or not
              type: boolean
            is_admin:
              description: Indicates whether bot is admin in chat/channel or not
              type: boolean
            permissions:
              type: array
              uniqueItems: true
              nullable: true
              items:
                $ref: '#/components/schemas/ChatAdminPermission'
              readOnly: false
          required:
            - chat_id
            - user_id
            - bot_id
            - is_channel
            - is_admin
    ModifyMembersResult:
      type: object
      description: Result of members list modification request
      allOf:
        - $ref: '#/components/schemas/SimpleQueryResult'
        - properties:
            failed_user_ids:
              description: List of user IDs failed to add or delete
              type: array
              items:
                $ref: '#/components/schemas/UserId'
              nullable: true
              readOnly: false
              uniqueItems: true
            failed_user_details:
              type: array
              items:
                $ref: '#/components/schemas/FailedUserDetails'
              nullable: true
              readOnly: false
    FailedUserDetails:
      type: object
      description: Detailed info about why a user cannot be added to the chat.
      properties:
        error_code:
          description: Code add.participant.privacy - Privacy errors while add participants. Code add.participant.not.found - Users to add not found
          type: string
        user_ids:
          description: List of user IDs failed to add
          type: array
          items:
            $ref: '#/components/schemas/UserId'
          nullable: false
      required:
        - error_code
        - user_ids