diff --git a/docs/schema.yaml b/docs/schema.yaml index 9424006..ebcab1d 100644 --- a/docs/schema.yaml +++ b/docs/schema.yaml @@ -1,19 +1,19 @@ openapi: 3.0.0 info: - version: 0.0.6 + 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 [botapi.max.ru](https://botapi.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 HTTP requests to the Max Bot API. + 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 personal data from users (name, short reference, phone number) + - Request data from users (name, short reference, phone number) We'll keep working on expanding bot capabilities in the future. ## Examples @@ -25,10 +25,6 @@ info: - Following external links - Forwarding a user to a chat/channel - ## @MasterBot - [MasterBot](https://max.ru/MasterBot) is the main bot in Max, all bots creator. Use MasterBot to create and edit - your bots. Feel free to contact us for any questions, [@support](https://max.ru/support) or [help@max.ru](mailto:help@max.ru). - ## HTTP verbs `GET` — getting resources, parameters are transmitted via URL @@ -49,6 +45,8 @@ info: `404` — resource not found + `403` — forbidden + `405` — method is not allowed `429` — the number of requests is exceeded @@ -66,47 +64,30 @@ info: `message` - a string describing the error
- For example: - ```bash - > http https://botapi.max.ru/chats?access_token={EXAMPLE_TOKEN} - HTTP / 1.1 403 Forbidden - Cache-Control: no-cache - Connection: Keep-Alive - Content-Length: 57 - Content-Type: application / json; charset = utf-8 - Set-Cookie: web_ui_lang = ru; Path = /; Domain = .max.ru; Expires = 2019-03-24T11: 45: 36.500Z - { - "code": "verify.token", - "message": "Invalid access_token" - } - ``` + ## Receiving notifications + Max Bot API supports 2 options of receiving notifications on new events for bots: - - Push notifications via WebHook. To receive data via WebHook, you'll have to [add subscription](https://dev.max.ru/#operation/subscribe); - - Notifications upon request via [long polling](#operation/getUpdates) API. All data can be received via long polling **by default** after creating the bot. + - 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/#operation/getUpdates) method to check all available types of updates. + 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 a short period of time (from 30 to 60 seconds) and will do this until get + 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. - 2. To protect your bot from unexpected high load we send **no more than 100** notifications per second by default. - If you want increase this limit, contact us at [@support](https://max.ru/support). - - It should be from one of the following subnets: - ``` - 5.101.42.200/31 - 31.177.104.200/31 - 89.221.230.200/31 - ``` + ### Updates + 1. Minimum polling time - 300ms ## Message buttons @@ -114,16 +95,20 @@ info: Max supports the following types of buttons: `callback` — sends a notification with payload to a bot (via WebHook or long polling) + + `clipboard` — copies payload data to clipboard + + `open_app` — opens mini app `link` — makes a user to follow a link + `message` — send a quick reply, command, or template message. + `request_contact` — requests the user permission to access contact information (phone number, short link, email) `request_geo_location` — asks user to provide current geo location - `chat` — creates chat associated with message - - To start create buttons [send message](#operation/sendMessage) with `InlineKeyboardAttachment`: + To start create buttons (sendMessage) with `InlineKeyboardAttachment`: ```json { "text": "It is message with inline keyboard", @@ -138,13 +123,6 @@ info: "text": "Press me!", "payload": "button1 pressed" } - ], - [ - { - "type": "chat", - "text": "Discuss", - "chat_title": "Message discussion" - } ] ] } @@ -152,25 +130,13 @@ info: ] } ``` - ### Chat button - Chat button is a button that starts chat assosiated with the current message. It will be **private** chat with a link, bot will be added as administrator by default. - - Chat will be created as soon as the first user taps on button. Bot will receive `message_chat_created` update. - - Bot can set title and description of new chat by setting `chat_title` and `chat_description` properties. - - Whereas keyboard can contain several `chat`-buttons there is `uuid` property to distinct them between each other. - In case you do not pass `uuid` we will generate it. If you edit message, pass `uuid` so we know that this button starts the same chat as before. - - Chat button also can contain `start_payload` that will be sent to bot as part of `message_chat_created` update. - ## 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/%BOT_USERNAME%/start/%PAYLOAD% + https://max.ru/?start= ``` 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 @@ -194,10 +160,10 @@ info: Message text can be improved with basic formatting such as: **strong**, *emphasis*, ~strikethough~, underline, `code` or link. You can use either markdown-like or HTML formatting. - To enable text formatting set the `format` property of [NewMessageBody](#tag/new_message_model). + 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](#tag/new_message_model) to `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: @@ -212,6 +178,9 @@ info: ``` `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 @@ -221,7 +190,7 @@ info: ### HTML support - To enable HTML parsing, set the `format` property of [NewMessageBody](#tag/new_message_model) to `html`. + 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: @@ -239,58 +208,88 @@ info: Highlighted text: `` + Quote: `
` + Header: `

` Text formatting is supported for iOS since version 3.1 and Android since 2.20.0. - # Versioning - API models and interface may change over time. To make sure your bot will get the right info, we strongly recommend adding API version number to each request. You can add it as `v` parameter to each HTTP-request. For instance, `v=0.1.2`. - To specify the data model version you are getting through WebHook subscription, use the `version` property in the request body of the [subscribe](https://dev.max.ru/#operation/subscribe) request. - # Libraries - We have developed the official [Java client](https://github.com/max-messenger/max-bot-api-client-java) and [SDK](https://github.com/max-messenger/max-bot-sdk-java). - - # Changelog - To see changelog for older versions visit our [GitHub](https://github.com/max-messenger/max-bot-api-schema/releases). + 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: 'https://botapi.max.ru' + - url: '/' security: - - access_token: [] + - 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: | + - name: user_with_photo_model + x-displayName: User + description: | + + - name: bot_info + x-displayName: BotInfo + description: | + - name: chat_model x-displayName: Chat description: | + - name: chat_member + x-displayName: ChatMember + description: | + - name: message_model x-displayName: Message description: | + - name: comment_message_model + x-displayName: CommentMessage + description: | + - name: new_message_model - x-displayName: New message + x-displayName: NewMessageBody description: | + - name: new_comment_message_model + x-displayName: NewCommentBody + description: | + - name: update_model x-displayName: Update description: | - + 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: @@ -299,7 +298,7 @@ paths: - 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)' + 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 @@ -311,111 +310,50 @@ paths: $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' + /me/commands: patch: tags: - bots - summary: Edit current bot info - operationId: editMyInfo - description: Edits current bot info. Fill only the fields you want to update. All remaining fields will stay untouched + summary: Edit current bot commands + operationId: editMyCommands + description: Edits current bot Commands. responses: '200': - description: Modified bot info + description: Modified bot commands info content: application/json: schema: - $ref: '#/components/schemas/BotInfo' + $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/BotPatch' - /chats: + $ref: '#/components/schemas/BotCommandsPatch' + /chats/{chatId}: get: tags: - chats - operationId: getChats - description: 'Returns information about chats that bot participated in: a result list and marker points to the next page' - summary: Get all chats - parameters: - - description: Number of chats requested - name: count - in: query - schema: - type: integer - format: int32 - minimum: 1 - maximum: 100 - default: 50 - - description: Points to next data page. `null` for the first page - name: marker - in: query - schema: - $ref: '#/components/schemas/bigint' - responses: - '200': - description: Returns paginated response of chats - content: - application/json: - schema: - $ref: '#/components/schemas/ChatList' - '401': - $ref: '#/components/responses/Unauthorized' - '500': - $ref: '#/components/responses/InternalError' - '/chats/{chatLink}': - get: - tags: - - chats - x-opGroup: chat - operationId: getChatByLink - description: Returns chat/channel information by its public link or dialog with user by username - summary: Get chat by link - parameters: - - name: chatLink - description: Public chat link or username - required: true - in: path - schema: - type: string - pattern: '@?[a-zA-Z]+[a-zA-Z0-9-_]*' - responses: - '200': - description: Chat information - content: - application/json: - schema: - $ref: '#/components/schemas/Chat' - '401': - $ref: '#/components/responses/Unauthorized' - '404': - $ref: '#/components/responses/NotFound' - '500': - $ref: '#/components/responses/InternalError' - '/chats/{chatId}': - get: - tags: - - chats - x-opGroup: chat operationId: getChat - description: Returns info about chat. + description: Returns info about chat or channel. summary: Get chat parameters: - name: chatId - description: Requested chat identifier + description: Requested chat or channel identifier required: true in: path schema: - type: integer - format: int64 - pattern: \-?\d+ + allOf: + - $ref: '#/components/schemas/ChatId' + x-pattern: \-?\d+ responses: '200': - description: Chat information + description: Chat or channel information content: application/json: schema: @@ -424,23 +362,23 @@ paths: $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' - patch: + patch: tags: - chats - x-opGroup: chat operationId: editChat - description: 'Edits chat info: title, icon, etc…' - summary: Edit chat info + description: 'Edits chat or channel info: title, icon, etc…' + summary: Edit chat or channel info parameters: - name: chatId - description: Chat identifier + description: Chat or channel identifier required: true in: path schema: - type: integer - format: int64 - pattern: \-?\d+ + allOf: + - $ref: '#/components/schemas/ChatId' + x-pattern: \-?\d+ requestBody: + description: Chat or channel info to update required: true content: application/json: @@ -448,7 +386,7 @@ paths: $ref: '#/components/schemas/ChatPatch' responses: '200': - description: 'If success, returns updated chat object' + description: If success, returns updated chat object content: application/json: schema: @@ -459,28 +397,6 @@ paths: $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalError' - delete: - tags: - - chats - operationId: deleteChat - description: Deletes chat for all participants. - summary: Delete chat - parameters: - - name: chatId - description: Chat identifier - required: true - in: path - schema: - type: integer - format: int64 - pattern: \-?\d+ - responses: - '200': - $ref: '#/components/responses/SuccessResponse' - '401': - $ref: '#/components/responses/Unauthorized' - '500': - $ref: '#/components/responses/InternalError' '/chats/{chatId}/actions': post: tags: @@ -494,10 +410,11 @@ paths: required: true in: path schema: - type: integer - format: int64 - pattern: \-?\d+ + allOf: + - $ref: '#/components/schemas/ChatId' + x-pattern: \-?\d+ requestBody: + description: Action to send to chat members required: true content: application/json: @@ -523,9 +440,9 @@ paths: required: true in: path schema: - type: integer - format: int64 - pattern: \-?\d+ + allOf: + - $ref: '#/components/schemas/ChatId' + x-pattern: \-?\d+ responses: '200': description: Pinned message @@ -553,10 +470,11 @@ paths: required: true in: path schema: - type: integer - format: int64 - pattern: \-?\d+ + allOf: + - $ref: '#/components/schemas/ChatId' + x-pattern: \-?\d+ requestBody: + description: Message to pin in chat required: true content: application/json: @@ -585,9 +503,9 @@ paths: required: true in: path schema: - type: integer - format: int64 - pattern: \-?\d+ + allOf: + - $ref: '#/components/schemas/ChatId' + x-pattern: \-?\d+ responses: '200': $ref: '#/components/responses/SuccessResponse' @@ -603,19 +521,18 @@ paths: get: tags: - chats - x-opGroup: myMembership operationId: getMembership - summary: Get chat membership - description: Returns chat membership info for current bot + summary: Get chat or channel membership + description: Returns chat or channel membership info for current bot parameters: - name: chatId - description: Chat identifier + description: Chat or channel identifier required: true in: path schema: - type: integer - format: int64 - pattern: \-?\d+ + allOf: + - $ref: '#/components/schemas/ChatId' + x-pattern: \-?\d+ responses: '200': description: Current bot membership info @@ -631,22 +548,21 @@ paths: $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' - delete: + delete: tags: - chats operationId: leaveChat - x-opGroup: myMembership summary: Leave chat - description: Removes bot from chat members. + description: Removes bot from chat or channel members. parameters: - name: chatId - description: Chat identifier + description: Chat or channel identifier required: true in: path schema: - type: integer - format: int64 - pattern: \-?\d+ + allOf: + - $ref: '#/components/schemas/ChatId' + x-pattern: \-?\d+ responses: '200': $ref: '#/components/responses/SuccessResponse' @@ -663,17 +579,17 @@ paths: tags: - chats operationId: getAdmins - summary: Get chat admins - description: Returns all chat administrators. Bot must be **administrator** in requested chat. + 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 identifier + description: Chat or channel identifier required: true in: path schema: - type: integer - format: int64 - pattern: \-?\d+ + allOf: + - $ref: '#/components/schemas/ChatId' + x-pattern: \-?\d+ responses: '200': description: Administrators list @@ -689,22 +605,23 @@ paths: $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' - post: + post: tags: - chats operationId: postAdmins - summary: Set chat admins - description: Returns true if all administrators added. + summary: Set chat or channel admins + description: Returns true if all administrators added. Additional permissions may require parameters: - name: chatId - description: Chat identifier + description: Chat or channel identifier required: true in: path schema: - type: integer - format: int64 - pattern: \-?\d+ + allOf: + - $ref: '#/components/schemas/ChatId' + x-pattern: \-?\d+ requestBody: + description: List of administrators to set in chat or channel required: true content: application/json: @@ -722,29 +639,29 @@ paths: '500': $ref: '#/components/responses/InternalError' '/chats/{chatId}/members/admins/{userId}': - delete: + delete: tags: - chats operationId: deleteAdmins summary: Revoke admin rights - description: Revokes admin rights from a user in the chat by removing their administrative privileges + 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 identifier + description: Chat or channel identifier required: true in: path schema: - type: integer - format: int64 - pattern: \-?\d+ + allOf: + - $ref: '#/components/schemas/ChatId' + x-pattern: \-?\d+ - name: userId description: User identifier required: true in: path schema: - type: integer - format: int64 - pattern: \-?\d+ + allOf: + - $ref: '#/components/schemas/UserId' + x-pattern: \d+ responses: '200': $ref: '#/components/responses/SuccessResponse' @@ -758,20 +675,18 @@ paths: - chats operationId: getMembers summary: Get members - description: Returns users participated in chat. + description: Returns users participated in chat or channel. parameters: - name: chatId - description: Chat identifier + description: Chat or channel identifier required: true in: path schema: - type: integer - format: int64 - pattern: \-?\d+ + allOf: + - $ref: '#/components/schemas/ChatId' + x-pattern: \-?\d+ - name: user_ids description: |- - *Since* version [0.1.4](#section/About/Changelog). - 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 @@ -779,10 +694,9 @@ paths: type: array uniqueItems: true items: - type: integer - format: int64 + $ref: '#/components/schemas/UserId' nullable: true - style: simple + style: form - name: marker description: Marker in: query @@ -796,7 +710,7 @@ paths: type: integer minimum: 1 maximum: 100 - default: '20' + default: 20 responses: '200': description: Returns members list and pointer to the next data page @@ -824,10 +738,11 @@ paths: required: true in: path schema: - type: integer - format: int64 - pattern: \-?\d+ + allOf: + - $ref: '#/components/schemas/ChatId' + x-pattern: \-?\d+ requestBody: + description: List of users to add to chat required: true content: application/json: @@ -835,7 +750,11 @@ paths: $ref: '#/components/schemas/UserIdsList' responses: '200': - $ref: '#/components/responses/SuccessResponse' + description: Result of chat members modification request + content: + application/json: + schema: + $ref: '#/components/schemas/ModifyMembersResult' '401': $ref: '#/components/responses/Unauthorized' '403': @@ -848,24 +767,23 @@ paths: tags: - chats operationId: removeMember - description: Removes member from chat. Additional permissions may require. + description: Removes member from chat or channel. Additional permissions may require. summary: Remove member parameters: - name: chatId - description: Chat identifier + description: Chat or channel identifier required: true in: path schema: - type: integer - format: int64 - pattern: \-?\d+ + allOf: + - $ref: '#/components/schemas/ChatId' + x-pattern: \-?\d+ - name: user_id - description: User id to remove from chat + description: User id to remove from chat or channel required: true in: query schema: - type: integer - format: int64 + $ref: '#/components/schemas/UserId' - name: block description: |- Set to `true` if user should be blocked in chat. @@ -889,7 +807,7 @@ paths: tags: - subscriptions operationId: getSubscriptions - description: 'In case your bot gets data via WebHook, the method returns list of all subscriptions' + description: In case your bot gets data via WebHook, the method returns list of all subscriptions summary: Get subscriptions responses: '200': @@ -909,9 +827,10 @@ paths: 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 one of the following ports: **80, 8080, 443, 8443, 16384-32383** + Your server **must** be listening on port **443** summary: Subscribe requestBody: + description: WebHook subscription parameters required: true content: application/json: @@ -924,11 +843,11 @@ paths: $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' - delete: + 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' + 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 @@ -967,10 +886,14 @@ paths: 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: + This type of an upload has some restrictions: - - Max. file size - 2 Gb - - Only one file per request can be uploaded + - 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 @@ -982,14 +905,14 @@ paths: and continue to upload a file. ##### Get upload status - To GET an upload status you simply need to perform HTTP-GET request to a file upload URL. + 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: photo, audio, video, file' + - description: 'Uploaded file type: image, audio, video, file' name: type required: true in: query @@ -1007,37 +930,53 @@ paths: '500': $ref: '#/components/responses/InternalError' /messages: - get: + get: tags: - messages operationId: getMessages - description: 'Returns messages in chat: 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`' + 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 identifier to get messages in chat + - description: Chat or channel identifier to get messages in chat or channel name: chat_id in: query schema: - $ref: '#/components/schemas/bigint' + $ref: '#/components/schemas/ChatId' - description: Comma-separated list of message ids to get name: message_ids in: query - style: simple + style: form schema: uniqueItems: true items: type: string nullable: true - name: from - description: Start time for requested messages + 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 + 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 @@ -1064,19 +1003,20 @@ paths: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalError' - post: + post: tags: - messages operationId: sendMessage description: |- - Sends a message to a chat. + 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](#operation/getUploadUrl) your media files. + 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](https://dev.max.ru/#operation/getUploadUrl) section for details. + 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 @@ -1086,12 +1026,12 @@ paths: 1. Get URL to upload. Execute following: ```shell - curl -X POST 'https://botapi.max.ru/uploads?access_token=%access_token%&type=video' + 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://vu.mycdn.me/upload.do…" + "url": "http://omub.okcdn.ru/upload.do…" } ``` @@ -1099,7 +1039,7 @@ paths: ```shell curl -i -X POST -H "Content-Type: multipart/form-data" - -F "data=@movie.mp4" "http://vu.mycdn.me/upload.do…" + -F "data=@movie.mp4" "http://omub.okcdn.ru/upload.do…" ``` As the result it will return JSON you can attach to message: ```json @@ -1134,23 +1074,22 @@ paths: in: query required: false schema: - type: integer - format: int64 + $ref: '#/components/schemas/UserId' - name: chat_id - description: Fill this if you send message to chat + description: Fill this if you send message to chat or channel schema: - type: integer - format: int64 + $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" + 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: @@ -1165,6 +1104,15 @@ paths: $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: @@ -1179,9 +1127,9 @@ paths: required: true in: query schema: - type: string - minLength: 1 + $ref: '#/components/schemas/MessageId' requestBody: + description: Updated message content required: true content: application/json: @@ -1194,20 +1142,19 @@ paths: $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' - delete: + delete: tags: - messages operationId: deleteMessage summary: Delete message - description: Deletes message in a dialog or in a chat if bot has permission to delete messages. + 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: - type: string - minLength: 1 + $ref: '#/components/schemas/MessageId' responses: '200': $ref: '#/components/responses/SuccessResponse' @@ -1225,13 +1172,14 @@ paths: description: Returns single message by its identifier. summary: Get message parameters: - - description: Message identifier (`mid`) to get single message in chat + - description: Message identifier (`mid`) to get single message in chat or channel in: path name: messageId required: true schema: - type: string - pattern: '[a-zA-Z0-9_\-]+' + allOf: + - $ref: '#/components/schemas/MessageId' + pattern: (mid.)?[a-zA-Z0-9_\-]+ responses: '200': description: Returns single message @@ -1249,6 +1197,209 @@ paths: $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: @@ -1263,7 +1414,7 @@ paths: required: true schema: type: string - pattern: '[a-zA-Z0-9_\-]+' + pattern: '[\w-]+' responses: '200': description: Detailed video attachment info @@ -1299,8 +1450,16 @@ paths: schema: type: string minLength: 1 - pattern: ^(?!\s*$).+ + 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: @@ -1317,10 +1476,12 @@ paths: $ref: '#/components/responses/InternalError' /updates: get: - operationId: getUpdates + 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. @@ -1355,14 +1516,17 @@ paths: - name: types description: Comma separated list of update types your bot want to receive in: query - example: 'types=message_created,message_callback' + style: form + explode: false + example: + - message_created + - message_callback schema: type: array uniqueItems: true items: type: string nullable: true - style: simple responses: '200': description: List of updates @@ -1380,15 +1544,11 @@ components: securitySchemes: access_token: type: apiKey - name: access_token + name: Authorization description: |- - A token is given to you by [MasterBot](https://max.ru/MasterBot) after you have created a bot. - In all subsequent requests to the Bot API, you **must** pass the received token as an `access_token` parameter to the HTTP request. - - - If [Terms and Conditions of Max usage](https://team.max.ru/en/terms/) have been violated, the Max administration may withdraw tokens by aborting user sessions. - If your token has been compromised, you can request a new one by sending a `/revoke` command to **[MasterBot](https://max.ru/MasterBot)**. - in: query + 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 @@ -1428,20 +1588,35 @@ components: $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 - type: integer - format: int64 - name: - description: Users visible name - type: string - nullable: true - readOnly: false - deprecated: true + allOf: + - $ref: '#/components/schemas/UserId' first_name: description: Users first name type: string @@ -1449,10 +1624,12 @@ components: 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 @@ -1460,14 +1637,15 @@ components: 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 - - last_name - - username - is_bot - - last_activity_time UserWithPhoto: + type: object + description: User with description and avatar URLs allOf: - $ref: '#/components/schemas/User' - properties: @@ -1481,11 +1659,15 @@ components: 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: @@ -1497,37 +1679,32 @@ components: maxItems: 32 readOnly: false nullable: true - BotPatch: + BotCommandsInfo: + type: object + description: Bot commands information properties: - name: - description: Visible name of bot - type: string - maxLength: 64 - minLength: 1 - readOnly: false - nullable: true - description: - description: Bot description up to 16k characters long - type: string - minLength: 1 - maxLength: 16000 - readOnly: false - nullable: true commands: - description: Commands supported by bot. Pass empty list if you want to remove commands + description: Commands supported by bot type: array items: $ref: '#/components/schemas/BotCommand' maxItems: 32 readOnly: false nullable: true - photo: - description: Request to set bot photo - allOf: - - $ref: '#/components/schemas/PhotoAttachmentRequestPayload' + 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 - nullable: true BotCommand: + type: object + description: Bot command with name and description properties: name: description: Command name @@ -1544,11 +1721,13 @@ components: required: - name Chat: + type: object + description: Chat, channel or dialog object properties: chat_id: description: Chats identifier - type: integer - format: int64 + allOf: + - $ref: '#/components/schemas/ChatId' type: description: 'Type of chat. One of: dialog, chat, channel' allOf: @@ -1567,11 +1746,13 @@ components: 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 @@ -1583,8 +1764,8 @@ components: owner_id: description: Identifier of chat owner. Visible only for chat admins nullable: true - type: integer - format: int64 + 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 @@ -1606,6 +1787,7 @@ components: description: Chat description type: string nullable: true + readOnly: false dialog_with_user: description: Another user in conversation. For `dialog` type chats only allOf: @@ -1617,11 +1799,6 @@ components: nullable: true readOnly: false type: integer - chat_message_id: - description: Identifier of message that contains `chat` button initialized chat - nullable: true - readOnly: false - type: string pinned_message: description: Pinned message in chat or channel. Returned only when single chat is requested nullable: true @@ -1632,19 +1809,18 @@ components: - chat_id - type - status - - title - last_event_time - participants_count - - icon - is_public - - description ChatType: - description: 'Type of chat. Dialog (one-on-one), chat or channel' + 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 @@ -1653,6 +1829,8 @@ components: - closed - suspended ChatList: + type: object + description: Paginated list of chats properties: chats: description: List of requested chats @@ -1664,10 +1842,12 @@ components: nullable: true type: integer format: int64 + readOnly: false required: - chats - - marker ChatPatch: + type: object + description: Patch object for updating chat info properties: icon: readOnly: false @@ -1680,8 +1860,14 @@ components: maxLength: 200 readOnly: false nullable: true - pin: - description: Identifier of message to be pinned in chat. In case you want to remove pin, use [unpin](#operation/unpinMessage) method + 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 @@ -1692,11 +1878,13 @@ components: 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. Can be outdated for super chats and channels (equals to `join_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: @@ -1712,13 +1900,17 @@ components: uniqueItems: true nullable: true items: - allOf: - - $ref: '#/components/schemas/ChatAdminPermission' + $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 - - permissions - join_time ChatAdminPermission: description: Chat admin permissions @@ -1729,11 +1921,18 @@ components: - 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. Visible only for chat admins + description: Participants in chat with time of last activity type: array items: $ref: '#/components/schemas/ChatMember' @@ -1746,6 +1945,7 @@ components: required: - members Image: + type: object description: Generic schema describing image object properties: url: @@ -1754,6 +1954,7 @@ components: required: - url Subscription: + type: object description: Schema to describe WebHook subscription properties: url: @@ -1772,37 +1973,40 @@ components: items: type: string minLength: 1 - version: - type: string - nullable: true - pattern: '[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}' + readOnly: false required: - url - time - - update_types - - version Recipient: - description: New message recipient. Could be user or chat + type: object + description: New message recipient. Could be user, chat or channel properties: chat_id: - description: Chat identifier - type: integer - format: int64 + 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' - type: integer - format: int64 + 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_id - chat_type - - user_id Message: + type: object description: Message in chat properties: sender: @@ -1810,8 +2014,9 @@ components: allOf: - $ref: '#/components/schemas/User' readOnly: false + nullable: true recipient: - description: Message recipient. Could be user or chat + description: Message recipient. Could be user, chat or channel allOf: - $ref: '#/components/schemas/Recipient' timestamp: @@ -1829,7 +2034,7 @@ components: allOf: - $ref: '#/components/schemas/MessageBody' stat: - description: 'Message statistics. Available only for channels in [GET:/messages](#operation/getMessages) context' + description: 'Message statistics. Available only for channels in getMessages method context' allOf: - $ref: '#/components/schemas/MessageStat' nullable: true @@ -1843,7 +2048,46 @@ components: - 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: @@ -1856,7 +2100,8 @@ components: properties: mid: description: Unique identifier of message - type: string + allOf: + - $ref: '#/components/schemas/MessageId' seq: description: Sequence identifier of message in chat type: integer @@ -1865,14 +2110,43 @@ components: 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/About/Text-formatting) section for more info + 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 @@ -1881,10 +2155,8 @@ components: required: - mid - seq - - text - - attachments - - link MessageList: + type: object description: Paginated list of messages properties: messages: @@ -1894,6 +2166,17 @@ components: $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 @@ -1901,40 +2184,66 @@ components: - 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' + description: If false, chat participants would not be notified type: boolean default: true readOnly: false format: - description: 'If set, message text will be formated according to given markup' + 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' - required: - - text - - attachments - - link NewMessageLink: + type: object + description: Link to a message for reply or forward properties: type: description: Type of message link @@ -1943,12 +2252,15 @@ components: - $ref: '#/components/schemas/MessageLinkType' mid: description: Message identifier of original message - type: string + 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 @@ -1959,10 +2271,11 @@ components: allOf: - $ref: '#/components/schemas/User' readOnly: false + nullable: true chat_id: - description: Chat where message has been originally posted. For forwarded messages only - type: integer - format: int64 + description: Chat where message has been originally posted + allOf: + - $ref: '#/components/schemas/ChatId' readOnly: false message: allOf: @@ -1970,13 +2283,49 @@ components: 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 @@ -1988,27 +2337,26 @@ components: sticker: '#/components/schemas/StickerAttachment' contact: '#/components/schemas/ContactAttachment' inline_keyboard: '#/components/schemas/InlineKeyboardAttachment' - reply_keyboard: '#/components/schemas/ReplyKeyboardAttachment' share: '#/components/schemas/ShareAttachment' location: '#/components/schemas/LocationAttachment' - data: '#/components/schemas/DataAttachment' properties: type: type: string required: - type PhotoAttachment: + type: object description: Image attachment allOf: - $ref: '#/components/schemas/Attachment' - properties: payload: - type: object - allOf: - - $ref: '#/components/schemas/PhotoAttachmentPayload' + $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 @@ -2025,16 +2373,15 @@ components: - url - token VideoAttachment: + type: object + description: Video attachment allOf: - $ref: '#/components/schemas/Attachment' - properties: payload: - type: object - allOf: - - $ref: '#/components/schemas/MediaAttachmentPayload' + $ref: '#/components/schemas/MediaAttachmentPayload' thumbnail: description: Video thumbnail - type: string nullable: true readOnly: false allOf: @@ -2057,6 +2404,8 @@ components: required: - payload VideoThumbnail: + type: object + description: Video thumbnail image properties: url: description: Image URL @@ -2064,6 +2413,8 @@ components: 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 @@ -2101,6 +2452,8 @@ components: nullable: true readOnly: false VideoAttachmentDetails: + type: object + description: Detailed information about video attachment including direct URLs properties: token: description: Video attachment token @@ -2132,13 +2485,13 @@ components: - duration - token AudioAttachment: + type: object + description: Audio attachment allOf: - $ref: '#/components/schemas/Attachment' - properties: payload: - type: object - allOf: - - $ref: '#/components/schemas/MediaAttachmentPayload' + $ref: '#/components/schemas/MediaAttachmentPayload' transcription: description: Audio transcription type: string @@ -2147,13 +2500,13 @@ components: required: - payload FileAttachment: + type: object + description: File attachment allOf: - $ref: '#/components/schemas/Attachment' - properties: payload: - type: object - allOf: - - $ref: '#/components/schemas/FileAttachmentPayload' + $ref: '#/components/schemas/FileAttachmentPayload' filename: description: Uploaded file name type: string @@ -2166,15 +2519,19 @@ components: - 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](#operation/getVideoAttachmentDetails) method to obtain direct links. + 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: @@ -2184,6 +2541,8 @@ components: required: - token FileAttachmentPayload: + type: object + description: Payload for file attachments with reuse token allOf: - $ref: '#/components/schemas/AttachmentPayload' - properties: @@ -2193,22 +2552,29 @@ components: required: - token ContactAttachment: + type: object + description: Contact attachment allOf: - $ref: '#/components/schemas/Attachment' - properties: payload: - type: object - allOf: - - $ref: '#/components/schemas/ContactAttachmentPayload' + $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 @@ -2216,6 +2582,8 @@ components: allOf: - $ref: '#/components/schemas/User' StickerAttachmentPayload: + type: object + description: Payload of sticker attachment allOf: - $ref: '#/components/schemas/AttachmentPayload' - properties: @@ -2225,13 +2593,13 @@ components: required: - code StickerAttachment: + type: object + description: Sticker attachment allOf: - $ref: '#/components/schemas/Attachment' - properties: payload: - type: object - allOf: - - $ref: '#/components/schemas/StickerAttachmentPayload' + $ref: '#/components/schemas/StickerAttachmentPayload' width: description: Sticker width type: integer @@ -2243,6 +2611,7 @@ components: - width - height ShareAttachmentPayload: + type: object description: Payload of ShareAttachmentRequest properties: url: @@ -2257,13 +2626,13 @@ components: nullable: true readOnly: false ShareAttachment: + type: object + description: Link preview attachment with media allOf: - $ref: '#/components/schemas/Attachment' - properties: payload: - type: object - allOf: - - $ref: '#/components/schemas/ShareAttachmentPayload' + $ref: '#/components/schemas/ShareAttachmentPayload' title: description: Link preview title type: string @@ -2282,6 +2651,8 @@ components: required: - payload LocationAttachment: + type: object + description: Geographic location attachment allOf: - $ref: '#/components/schemas/Attachment' - properties: @@ -2295,39 +2666,17 @@ components: - latitude - longitude InlineKeyboardAttachment: + type: object description: Buttons in messages allOf: - $ref: '#/components/schemas/Attachment' - properties: payload: - type: object - allOf: - - $ref: '#/components/schemas/Keyboard' + $ref: '#/components/schemas/Keyboard' required: - payload - ReplyKeyboardAttachment: - description: Custom reply keyboard in message - allOf: - - $ref: '#/components/schemas/Attachment' - - properties: - buttons: - type: array - items: - type: array - items: - $ref: '#/components/schemas/ReplyButton' - required: - - buttons - DataAttachment: - description: Attachment contains payload sent through `SendMessageButton` - allOf: - - $ref: '#/components/schemas/Attachment' - - properties: - data: - type: string - required: - - data Keyboard: + type: object description: Keyboard is two-dimension array of buttons properties: buttons: @@ -2339,6 +2688,8 @@ components: required: - buttons Button: + type: object + description: Inline keyboard button properties: type: type: string @@ -2354,11 +2705,14 @@ components: link: '#/components/schemas/LinkButton' request_geo_location: '#/components/schemas/RequestGeoLocationButton' request_contact: '#/components/schemas/RequestContactButton' - chat: '#/components/schemas/ChatButton' + 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' @@ -2367,15 +2721,10 @@ components: description: Button payload type: string maxLength: 1024 - intent: - description: Intent of button. Affects clients representation - readOnly: false - default: default - allOf: - - $ref: '#/components/schemas/Intent' required: - payload LinkButton: + type: object description: After pressing this type of button user follows the link it contains allOf: - $ref: '#/components/schemas/Button' @@ -2385,109 +2734,63 @@ components: 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' + description: If *true*, sends location without asking user's confirmation readOnly: false type: boolean default: false - ChatButton: - description: |- - Button that creates new chat as soon as the first user clicked on it. - Bot will be added to chat participants as administrator. - Message author will be owner of the chat. + OpenAppButton: + type: object + description: After pressing this type of button client opens mini app allOf: - $ref: '#/components/schemas/Button' - properties: - chat_title: - description: 'Title of chat to be created' - type: string - maxLength: 200 - chat_description: - description: 'Chat description' - readOnly: false + payload: + description: Button payload nullable: true - type: string - maxLength: 400 - start_payload: - description: 'Start payload will be sent to bot as soon as chat created' readOnly: false - nullable: true type: string + pattern: '^[\w-]*$' maxLength: 512 - uuid: - description: |- - Unique button identifier across all chat buttons in keyboard. - If `uuid` changed, new chat will be created on the next click. - Server will generate it at the time when button initially posted. - Reuse it when you edit the message.' - readOnly: false + 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 - type: integer - required: - - chat_title - Intent: - description: Intent of button - type: string - enum: - - positive - - negative - - default - ReplyButton: - description: After pressing this type of button client will send a message on behalf of user with given payload - properties: - text: - description: Visible text of button - type: string - minLength: 1 - maxLength: 128 - payload: - description: Button payload - type: string - maxLength: 1024 - readOnly: false - nullable: true - discriminator: - propertyName: type - mapping: - message: '#/components/schemas/SendMessageButton' - user_geo_location: '#/components/schemas/SendGeoLocationButton' - user_contact: '#/components/schemas/SendContactButton' - required: - - text - SendMessageButton: - description: After pressing this type of button client will send a message on behalf of user with given payload - allOf: - - $ref: '#/components/schemas/ReplyButton' - - properties: - intent: - description: Intent of button. Affects clients representation readOnly: false - default: default allOf: - - $ref: '#/components/schemas/Intent' - SendGeoLocationButton: - description: After pressing this type of button client sends new message with attachment of current user geo location + - $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/ReplyButton' + - $ref: '#/components/schemas/Button' - properties: - quick: - description: "If *true*, sends location without asking user's confirmation" - readOnly: false - type: boolean - default: false - SendContactButton: - description: After pressing this type of button client sends new message with attachment of current user contact - allOf: - - $ref: '#/components/schemas/ReplyButton' + payload: + description: Button payload + type: string + maxLength: 1024 + required: + - payload MessageLinkType: description: Type of linked message type: string @@ -2495,6 +2798,7 @@ components: - forward - reply AttachmentRequest: + type: object description: Request to attach some data to message discriminator: propertyName: type @@ -2506,7 +2810,6 @@ components: sticker: '#/components/schemas/StickerAttachmentRequest' contact: '#/components/schemas/ContactAttachmentRequest' inline_keyboard: '#/components/schemas/InlineKeyboardAttachmentRequest' - reply_keyboard: '#/components/schemas/ReplyKeyboardAttachmentRequest' location: '#/components/schemas/LocationAttachmentRequest' share: '#/components/schemas/ShareAttachmentRequest' properties: @@ -2515,15 +2818,17 @@ components: required: - type PhotoAttachmentRequest: + type: object + description: Request to attach image to message allOf: - $ref: '#/components/schemas/AttachmentRequest' - properties: payload: - allOf: - - $ref: '#/components/schemas/PhotoAttachmentRequestPayload' + $ref: '#/components/schemas/PhotoAttachmentRequestPayload' required: - payload PhotoAttachmentRequestPayload: + type: object description: Request to attach image. All fields are mutually exclusive properties: url: @@ -2545,42 +2850,36 @@ components: 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 - PhotoTokens: - description: This is information you will receive as soon as an image uploaded - properties: - photos: - type: object - additionalProperties: - $ref: '#/components/schemas/PhotoToken' - required: - - photos VideoAttachmentRequest: + type: object description: Request to attach video to message allOf: - $ref: '#/components/schemas/AttachmentRequest' - properties: payload: - allOf: - - $ref: '#/components/schemas/UploadedInfo' + $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: - allOf: - - $ref: '#/components/schemas/UploadedInfo' + $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: @@ -2588,16 +2887,17 @@ components: 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: - allOf: - - $ref: '#/components/schemas/UploadedInfo' + $ref: '#/components/schemas/UploadedInfo' required: - payload UploadType: + type: string description: Type of file uploading enum: - image @@ -2605,27 +2905,30 @@ components: - 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: - allOf: - - $ref: '#/components/schemas/ContactAttachmentRequestPayload' + $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 - type: integer - format: int64 + allOf: + - $ref: '#/components/schemas/UserId' vcf_info: description: Full information about contact in VCF format nullable: true @@ -2636,19 +2939,19 @@ components: readOnly: false nullable: true type: string - required: - - name StickerAttachmentRequest: + type: object description: Request to attach sticker. MUST be the only attachment request in message allOf: - $ref: '#/components/schemas/AttachmentRequest' - properties: payload: - allOf: - - $ref: '#/components/schemas/StickerAttachmentRequestPayload' + $ref: '#/components/schemas/StickerAttachmentRequestPayload' required: - payload StickerAttachmentRequestPayload: + type: object + description: Payload for sticker attachment request properties: code: description: Sticker code @@ -2656,56 +2959,32 @@ components: required: - code InlineKeyboardAttachmentRequest: + type: object description: Request to attach keyboard to message allOf: - $ref: '#/components/schemas/AttachmentRequest' - properties: payload: - type: object - allOf: - - $ref: '#/components/schemas/InlineKeyboardAttachmentRequestPayload' + $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 - minLength: 1 + minItems: 1 items: type: array items: $ref: '#/components/schemas/Button' required: - buttons - ReplyKeyboardAttachmentRequest: - description: Request to attach reply keyboard to message - allOf: - - $ref: '#/components/schemas/AttachmentRequest' - - properties: - direct: - description: Applicable only for chats. If `true` keyboard will be shown only for user bot mentioned or replied - type: boolean - default: false - readOnly: false - direct_user_id: - description: If set to `true`, reply keyboard will only be shown to this participant in chat - type: integer - format: int64 - nullable: true - readOnly: false - buttons: - description: Two-dimensional array of buttons - type: array - minLength: 1 - items: - type: array - items: - $ref: '#/components/schemas/ReplyButton' - required: - - buttons LocationAttachmentRequest: - description: Request to attach keyboard to message + type: object + description: Request to attach geographic location to message allOf: - $ref: '#/components/schemas/AttachmentRequest' - properties: @@ -2719,21 +2998,23 @@ components: - latitude - longitude ShareAttachmentRequest: + type: object description: Request to attach media preview of any external URL allOf: - $ref: '#/components/schemas/AttachmentRequest' - properties: payload: - allOf: - - $ref: '#/components/schemas/ShareAttachmentPayload' + $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`, link or user_mention" + 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 @@ -2755,23 +3036,28 @@ components: 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' @@ -2784,47 +3070,59 @@ components: 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" + description: '`@username` of mentioned user' type: string nullable: true readOnly: false user_id: description: Identifier of mentioned user without username - type: integer - format: int64 + 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: - description: 'URL of HTTP(S)-endpoint of your bot. Must starts with http(s)://' - type: string + $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.' + 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: '^[a-zA-Z0-9_-]{5,256}$' + 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 @@ -2834,13 +3132,10 @@ components: items: type: string readOnly: false - version: - description: Version of API. Affects model representation - type: string - readOnly: false required: - url GetSubscriptionsResult: + type: object description: List of all WebHook subscriptions properties: subscriptions: @@ -2851,6 +3146,7 @@ components: required: - subscriptions SimpleQueryResult: + type: object description: Simple response to request properties: success: @@ -2863,10 +3159,13 @@ components: 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 - type: string + allOf: + - $ref: '#/components/schemas/MessageId' notify: description: If `true`, participants will be notified with system message in chat/channel type: boolean @@ -2876,6 +3175,8 @@ components: 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 @@ -2884,6 +3185,7 @@ components: allOf: - $ref: '#/components/schemas/Message' Callback: + type: object description: Object sent to bot when user presses button properties: timestamp: @@ -2906,6 +3208,7 @@ components: - callback_id - user CallbackAnswer: + type: object description: Send this object when your bot wants to react to when a button is pressed properties: message: @@ -2920,9 +3223,10 @@ components: readOnly: false type: string Error: + type: object description: Server returns this if there was an exception to your request properties: - error: + error: description: Error type: string code: @@ -2949,20 +3253,26 @@ components: required: - url UserIdsList: + type: object + description: List of user identifiers properties: user_ids: items: - type: integer - format: int64 + $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 @@ -2971,21 +3281,26 @@ components: required: - admins ChatAdmin: + type: object description: Administrator id with permissions properties: user_id: - type: integer - format: int64 + $ref: '#/components/schemas/UserId' permissions: type: array uniqueItems: true items: - allOf: - - $ref: '#/components/schemas/ChatAdminPermission' + $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 @@ -2995,6 +3310,7 @@ components: - sending_file - mark_seen UpdateList: + type: object description: List of all updates in chats your bot participated in properties: updates: @@ -3007,10 +3323,11 @@ components: type: integer format: int64 nullable: true + readOnly: false required: - updates - - marker Update: + type: object description: '`Update` object represents different types of events that happened in chat. See its inheritors' discriminator: propertyName: update_type @@ -3019,13 +3336,21 @@ components: 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' - message_chat_created: '#/components/schemas/MessageChatCreatedUpdate' + bot_admin_permissions_changed: '#/components/schemas/BotAdminPermissionsChangedUpdate' properties: update_type: type: string @@ -3037,6 +3362,7 @@ components: - update_type - timestamp MessageCallbackUpdate: + type: object description: You will get this `update` as soon as user presses button allOf: - $ref: '#/components/schemas/Update' @@ -3050,6 +3376,7 @@ components: nullable: true allOf: - $ref: '#/components/schemas/Message' + readOnly: false user_locale: description: Current user locale in IETF BCP 47 format type: string @@ -3057,9 +3384,9 @@ components: readOnly: false required: - callback - - message MessageCreatedUpdate: - description: You will get this `update` as soon as message is created + 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: @@ -3075,27 +3402,30 @@ components: required: - message MessageRemovedUpdate: - description: You will get this `update` as soon as message is removed + 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 - type: string + allOf: + - $ref: '#/components/schemas/MessageId' chat_id: description: Chat identifier where message has been deleted - type: integer - format: int64 + allOf: + - $ref: '#/components/schemas/ChatId' user_id: description: User who deleted this message - type: integer - format: int64 + allOf: + - $ref: '#/components/schemas/UserId' required: - message_id - chat_id - user_id MessageEditedUpdate: - description: You will get this `update` as soon as message is edited + 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: @@ -3105,15 +3435,67 @@ components: - $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 - type: integer - format: int64 + allOf: + - $ref: '#/components/schemas/ChatId' user: description: User who added bot to chat allOf: @@ -3126,14 +3508,15 @@ components: - 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 - type: integer - format: int64 + allOf: + - $ref: '#/components/schemas/ChatId' user: description: User who removed bot from chat allOf: @@ -3146,22 +3529,23 @@ components: - user - is_channel UserAddedToChatUpdate: - description: You will receive this update when user has been added to chat where bot is administrator + 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 - type: integer - format: int64 + 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 - type: integer - format: int64 + allOf: + - $ref: '#/components/schemas/UserId' readOnly: false nullable: true is_channel: @@ -3172,22 +3556,23 @@ components: - user - is_channel UserRemovedFromChatUpdate: - description: You will receive this update when user has been removed from chat where bot is administrator + 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 - type: integer - format: int64 + 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 - type: integer - format: int64 + allOf: + - $ref: '#/components/schemas/UserId' readOnly: false is_channel: description: Indicates whether user has been removed from channel or not @@ -3197,14 +3582,15 @@ components: - 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 - type: integer - format: int64 + allOf: + - $ref: '#/components/schemas/ChatId' user: description: User pressed the 'Start' button allOf: @@ -3222,15 +3608,126 @@ components: 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 - type: integer - format: int64 + allOf: + - $ref: '#/components/schemas/ChatId' user: description: User who changed title allOf: @@ -3242,23 +3739,76 @@ components: - chat_id - user - title - MessageChatCreatedUpdate: - description: Bot will get this update when chat has been created as soon as first user clicked chat button + BotAdminPermissionsChangedUpdate: + type: object + description: Bot will get this update when bot admin permissions changed allOf: - $ref: '#/components/schemas/Update' - properties: - chat: - description: Created chat + chat_id: + description: Chat identifier where event has occurred allOf: - - $ref: '#/components/schemas/Chat' - message_id: - description: Message identifier where the button has been clicked - type: string - start_payload: - description: Payload from chat button - type: string + - $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: - - message_id - - chat + - 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 diff --git a/docs/swagger.json b/docs/swagger.json index a33ea0a..b4e115d 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -1,16 +1,16 @@ { "openapi": "3.0.0", "info": { - "version": "0.0.1", + "version": "0.0.33", "title": "Max Bot API", "license": { "name": "Apache 2.0" }, - "description": "# About\nBot API allows bots to interact with Max. Methods are called by sending HTTPS requests to [platform-api.max.ru](https://platform-api.max.ru) domain.\nBots are third-party applications that use Max features. A bot can legitimately take part in a conversation. It can be achieved through HTTP requests to the Max Bot API.\n\n## Features\nMax bots of the current version are able to:\n- Communicate with users and respond to requests\n- Recommend users complete actions via programmed buttons\n- Request personal data from users (name, short reference, phone number)\nWe'll keep working on expanding bot capabilities in the future.\n\n## Examples\nBots can be used for the following purposes:\n- Providing support, answering frequently asked questions\n- Sending typical information\n- Voting\n- Likes/dislikes\n- Following external links\n- Forwarding a user to a chat/channel\n\n## HTTP verbs\n`GET` — getting resources, parameters are transmitted via URL\n\n`POST` — creation of resources (for example, sending new messages)\n\n`PUT` — editing resources\n\n`DELETE` — deleting resources\n\n`PATCH` — patching resources\n\n## HTTP response codes\n`200` — successful operation\n\n`400` — invalid request\n\n`401` — authentication error\n\n`404` — resource not found\n\n`405` — method is not allowed\n\n`429` — the number of requests is exceeded\n\n`503` — service unavailable\n\n## Resources format\nFor content requests (PUT and POST) and responses, the API uses the JSON format.\nAll strings are UTF-8 encoded.\nDate/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.\n## Error responses\nIn case of an error, the API returns a response with the corresponding HTTP code and JSON with the following fields:\n\n`code` - the string with the error key\n\n`message` - a string describing the error
\n\nFor example:\n```bash\n> http https://platform-api.max.ru/chats?access_token={EXAMPLE_TOKEN}\nHTTP / 1.1 403 Forbidden\nCache-Control: no-cache\nConnection: Keep-Alive\nContent-Length: 57\nContent-Type: application / json; charset = utf-8\nSet-Cookie: web_ui_lang = ru; Path = /; Domain = .max.ru; Expires = 2019-03-24T11: 45: 36.500Z\n{\n \"code\": \"verify.token\",\n \"message\": \"Invalid access_token\"\n}\n```\n## Receiving notifications\nMax Bot API supports 2 options of receiving notifications on new events for bots:\n- Push notifications via WebHook. To receive data via WebHook, you'll have to [add subscription](https://dev.max.ru/docs-api/methods/POST/subscriptions);\n- Notifications upon request via [long polling](/docs-api/methods/GET/updates) API. All data can be received via long polling **by default** after creating the bot.\n\nBoth methods **cannot** be used simultaneously.\nRefer to the response schema of [GET:/updates](https://dev.max.ru/docs-api/methods/GET/updates) method to check all available types of updates.\n\n### Webhook\nThere is some notes about how we handle webhook subscription:\n1. Sometimes webhook notification cannot be delivered in case when bot server or network is down.\n\n In such case we well retry delivery in a short period of time (from 30 to 60 seconds) and will do this until get\n `200 OK` status code from your server, but not longer than **8 hours** (*may change over time*) since update happened.\n\n We also consider any non `200`-response from server as failed delivery.\n\n2. To protect your bot from unexpected high load we send **no more than 100** notifications per second by default.\n If you want increase this limit, contact us at [@support](https://max.ru/support).\n\n\nIt should be from one of the following subnets:\n```\n185.16.150.0/30\n185.16.150.84/30\n185.16.150.152/30\n185.16.150.192/30\n```\n\n\n## Message buttons\nYou can program buttons for users answering a bot.\nMax supports the following types of buttons:\n\n`callback` — sends a notification with payload to a bot (via WebHook or long polling)\n\n`link` — makes a user to follow a link\n\n`request_contact` — requests the user permission to access contact information (phone number, short link, email)\n\n`request_geo_location` — asks user to provide current geo location\n\n`chat` — creates chat associated with message\n\nTo start create buttons [send message](/docs-api/methods/POST/messages) with `InlineKeyboardAttachment`:\n```json\n{\n \"text\": \"It is message with inline keyboard\",\n \"attachments\": [\n {\n \"type\": \"inline_keyboard\",\n \"payload\": {\n \"buttons\": [\n [\n {\n \"type\": \"callback\",\n \"text\": \"Press me!\",\n \"payload\": \"button1 pressed\"\n }\n ],\n [\n {\n \"type\": \"chat\",\n \"text\": \"Discuss\",\n \"chat_title\": \"Message discussion\"\n }\n ]\n ]\n }\n }\n ]\n}\n```\n### Chat button\nChat button is a button that starts chat assosiated with the current message. It will be **private** chat with a link, bot will be added as administrator by default.\n\nChat will be created as soon as the first user taps on button. Bot will receive `message_chat_created` update.\n\nBot can set title and description of new chat by setting `chat_title` and `chat_description` properties.\n\nWhereas keyboard can contain several `chat`-buttons there is `uuid` property to distinct them between each other.\nIn case you do not pass `uuid` we will generate it. If you edit message, pass `uuid` so we know that this button starts the same chat as before.\n\nChat button also can contain `start_payload` that will be sent to bot as part of `message_chat_created` update.\n\n## Deep linking\nMax supports deep linking mechanism for bots. It allows passing additional payload to the bot on startup.\nDeep link can contain any data encoded into string up to **512** characters long. Longer strings will be omitted and **not** passed to the bot.\n\nEach bot has start link that looks like:\n```\nhttps://max.ru/?start=\n```\nAs soon as user clicks on such link we open dialog with bot and send this payload to bot as part of `bot_started` update:\n```json\n{\n \"update_type\": \"bot_started\",\n \"timestamp\": 1573226679188,\n \"chat_id\": 1234567890,\n \"user\": {\n \"user_id\": 1234567890,\n \"name\": \"Boris\",\n \"username\": \"borisd84\"\n },\n \"payload\": \"any data meaningful to bot\"\n}\n```\n\nDeep linking mechanism is supported for iOS version 2.7.0 and Android 2.9.0 and higher.\n\n## Text formatting\n\nMessage text can be improved with basic formatting such as: **strong**, *emphasis*, ~strikethough~, \nunderline, `code` or link. You can use either markdown-like or HTML formatting.\n\nTo enable text formatting set the `format` property of [NewMessageBody](#tag/new_message_model).\n\n### Max flavored Markdown\nTo enable [Markdown](https://spec.commonmark.org/0.29/) parsing, set the `format` property of [NewMessageBody](#tag/new_message_model) to `markdown`.\n\nWe currently support only the following syntax:\n\n`*empasized*` or `_empasized_` for *italic* text\n\n`**strong**` or `__strong__` for __bold__ text\n\n`~~strikethough~~` for ~strikethough~ text\n\n`++underline++` for underlined text\n\n``` `code` ``` or ` ```code``` ` for `monospaced` text\n\n`^^important^^` for highlighted text (colored in red, by default)\n\n`[Inline URL](https://dev.max.ru/)` for inline URLs\n\n`[User mention](max://user/%user_id%)` for user mentions without username\n\n`# Header` for header\n\n### HTML support\n\nTo enable HTML parsing, set the `format` property of [NewMessageBody](#tag/new_message_model) to `html`.\n \nOnly the following HTML tags are supported. All others will be stripped:\n\nEmphasized: `` or ``\n\nStrong: `` or ``\n\nStrikethrough: `` or ``\n\nUnderlined: `` or ``\n\nLink: `Docs`\n\nMonospaced text: `
` or ``\n\nHighlighted text: ``\n\nHeader: `
`\n\nText formatting is supported for iOS since version 3.1 and Android since 2.20.0.\n\n# Versioning\nAPI models and interface may change over time. To make sure your bot will get the right info, we strongly recommend adding API version number to each request. You can add it as `v` parameter to each HTTP-request. For instance, `v=0.1.2`.\nTo specify the data model version you are getting through WebHook subscription, use the `version` property in the request body of the [subscribe](https://dev.max.ru/docs-api/methods/POST/subscriptions) request.\n\n# Libraries\nWe have developed the official [Java client](https://github.com/tamtam-chat/tamtam-bot-api) and [SDK](https://github.com/tamtam-chat/tamtam-bot-sdk).\n\n# Changelog\nTo see changelog for older versions visit our [GitHub](https://github.com/tamtam-chat/tamtam-bot-api-schema/releases)."
+    "description": "# About\nBot 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.\nBots 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.\n\n## Features\nMax bots of the current version are able to:\n- Communicate with users and respond to requests\n- Recommend users complete actions via programmed buttons\n- Request data from users (name, short reference, phone number)\nWe'll keep working on expanding bot capabilities in the future.\n\n## Examples\nBots can be used for the following purposes:\n- Providing support, answering frequently asked questions\n- Sending typical information\n- Voting\n- Likes/dislikes\n- Following external links\n- Forwarding a user to a chat/channel\n\n## HTTP verbs\n`GET` — getting resources, parameters are transmitted via URL\n\n`POST` — creation of resources (for example, sending new messages)\n\n`PUT` — editing resources\n\n`DELETE` — deleting resources\n\n`PATCH` — patching resources\n\n## HTTP response codes\n`200` — successful operation\n\n`400` — invalid request\n\n`401` — authentication error\n\n`404` — resource not found\n\n`403` — forbidden\n\n`405` — method is not allowed\n\n`429` — the number of requests is exceeded\n\n`503` — service unavailable\n\n## Resources format\nFor content requests (PUT and POST) and responses, the API uses the JSON format.\nAll strings are UTF-8 encoded.\nDate/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.\n## Error responses\nIn case of an error, the API returns a response with the corresponding HTTP code and JSON with the following fields:\n\n`code` - the string with the error key\n\n`message` - a string describing the error 
\n\n\n## Receiving notifications\n\nMax Bot API supports 2 options of receiving notifications on new events for bots:\n- 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);\n- Notifications upon request via long polling (/getUpdates) API (not recommended). All data can be received via long polling **by default** after creating the bot.      \n\n  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.\n\nBoth methods **cannot** be used simultaneously.\nRefer to the response schema of [/updates](https://dev.max.ru/docs-api/methods/GET/updates) method to check all available types of updates.\n\n### Webhook\nThere is some notes about how we handle webhook subscription:\n1. Sometimes webhook notification cannot be delivered in case when bot server or network is down.\n\n  In such case we well retry delivery in exponentially increasing intervals and will do this until get\n  `200 OK` status code from your server, but not longer than **8 hours** (*may change over time*) since update happened.\n\n  We also consider any non `200`-response from server as failed delivery.\n\n\n ### Updates\n1. Minimum polling time - 300ms\n\n\n## Message buttons\nYou can program buttons for users answering a bot.\nMax supports the following types of buttons:\n\n`callback` — sends a notification with payload to a bot (via WebHook or long polling)\n\n`clipboard` — copies payload data to clipboard\n\n`open_app` — opens mini app\n\n`link` — makes a user to follow a link\n\n`message` — send a quick reply, command, or template message. \n\n`request_contact` — requests the user permission to access contact information (phone number, short link, email)\n\n`request_geo_location` — asks user to provide current geo location\n\nTo start create buttons (sendMessage) with `InlineKeyboardAttachment`:\n```json\n{\n  \"text\": \"It is message with inline keyboard\",\n  \"attachments\": [\n    {\n      \"type\": \"inline_keyboard\",\n      \"payload\": {\n        \"buttons\": [\n          [\n            {\n              \"type\": \"callback\",\n              \"text\": \"Press me!\",\n              \"payload\": \"button1 pressed\"\n            }\n          ]\n        ]\n      }\n    }\n  ]\n}\n```\n## Deep linking\nMax supports deep linking mechanism for bots. It allows passing additional payload to the bot on startup.\nDeep link can contain any data encoded into string up to **128** characters long. Longer strings will be omitted and **not** passed to the bot.\n\nEach bot has start link that looks like:\n```\nhttps://max.ru/?start=\n```\nAs soon as user clicks on such link we open dialog with bot and send this payload to bot as part of `bot_started` update:\n```json\n{\n    \"update_type\": \"bot_started\",\n    \"timestamp\": 1573226679188,\n    \"chat_id\": 1234567890,\n    \"user\": {\n        \"user_id\": 1234567890,\n        \"name\": \"Boris\",\n        \"username\": \"borisd84\"\n    },\n    \"payload\": \"any data meaningful to bot\"\n}\n```\n\nDeep linking mechanism is supported for iOS version 2.7.0 and Android 2.9.0 and higher.\n\n## Text formatting\n\nMessage text can be improved with basic formatting such as: **strong**, *emphasis*, ~strikethough~, \nunderline, `code` or link. You can use either markdown-like or HTML formatting.\n\nTo enable text formatting set the `format` property of NewMessageBody model.\n\n### Max flavored Markdown\nTo enable [Markdown](https://spec.commonmark.org/0.29/) parsing, set the `format` property of NewMessageBody model to `markdown`.\n\nWe currently support only the following syntax:\n\n`*empasized*` or `_empasized_` for *italic* text\n\n`**strong**` or `__strong__` for __bold__ text\n\n`~~strikethough~~`  for ~strikethough~ text\n\n`++underline++`  for underlined text\n\n``` `code` ``` or ` ```code``` ` for `monospaced` text\n\n`^^important^^` for highlighted text (colored in red, by default)\n\n`> quote` for \n>quoted text\n\n`[Inline URL](https://dev.max.ru/)` for inline URLs\n\n`[User mention](max://user/%user_id%)` for user mentions without username\n\n`# Header` for header\n\n### HTML support\n\nTo enable HTML parsing, set the `format` property of NewMessageBody model to `html`.\n\nOnly the following HTML tags are supported. All others will be stripped:\n\nEmphasized: `` or ``\n\nStrong: `` or ``\n\nStrikethrough: `` or ``\n\nUnderlined: `` or ``\n\nLink: `Docs`\n\nMonospaced text: `
` or ``\n\nHighlighted text: ``\n\nQuote: `
`\n\nHeader: `
`\n\nText formatting is supported for iOS since version 3.1 and Android since 2.20.0.\n\n# Libraries\nWe 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": "https://platform-api.max.ru"
+      "url": "/"
     }
   ],
   "security": [
@@ -19,35 +19,75 @@
     }
   ],
   "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": "\n"
     },
     {
-      "name": "bot_command_model",
-      "x-displayName": "BotCommand",
-      "description": "\n"
+      "name": "user_with_photo_model",
+      "x-displayName": "User",
+      "description": "\n"
+    },
+    {
+      "name": "bot_info",
+      "x-displayName": "BotInfo",
+      "description": "\n"
     },
     {
       "name": "chat_model",
       "x-displayName": "Chat",
       "description": "\n"
     },
+    {
+      "name": "chat_member",
+      "x-displayName": "ChatMember",
+      "description": "\n"
+    },
     {
       "name": "message_model",
       "x-displayName": "Message",
       "description": "\n"
     },
+    {
+      "name": "comment_message_model",
+      "x-displayName": "CommentMessage",
+      "description": "\n"
+    },
     {
       "name": "new_message_model",
       "x-displayName": "NewMessageBody",
       "description": "\n"
     },
+    {
+      "name": "new_comment_message_model",
+      "x-displayName": "NewCommentBody",
+      "description": "\n"
+    },
     {
       "name": "update_model",
       "x-displayName": "Update",
-      "description": "\n"
+      "description": " \n"
     }
   ],
   "x-tagGroups": [
@@ -56,6 +96,7 @@
       "tags": [
         "bots",
         "chats",
+        "comments",
         "messages",
         "subscriptions",
         "upload"
@@ -65,9 +106,13 @@
       "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"
       ]
     }
@@ -78,12 +123,12 @@
         "tags": [
           "bots"
         ],
-        "summary": "Получение информации о текущем боте",
+        "summary": "Get current bot info",
         "operationId": "getMyInfo",
-        "description": "Возвращает информацию о текущем боте, который идентифицируется с помощью токена доступа. Метод возвращает ID бота, его имя и аватар (если есть)\n\nПример запроса:\n```bash\ncurl -X GET \"https://platform-api.max.ru/me\" \\\n  -H \"Authorization: {access_token}\"\n```",
+        "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": "Информация о боте",
+            "description": "Bot info",
             "content": {
               "application/json": {
                 "schema": {
@@ -101,43 +146,21 @@
         }
       }
     },
-    "/chats": {
-      "get": {
+    "/me/commands": {
+      "patch": {
         "tags": [
-          "chats"
-        ],
-        "operationId": "getChats",
-        "description": "Возвращает список групповых чатов, в которых участвовал бот, информацию о каждом чате и маркер для перехода к следующей странице списка\n\nПример запроса:\n```bash\ncurl -X GET \"https://platform-api.max.ru/chats\" \\\n  -H \"Authorization: {access_token}\"\n```",
-        "summary": "Получение списка всех групповых чатов",
-        "parameters": [
-          {
-            "description": "Количество запрашиваемых чатов",
-            "name": "count",
-            "in": "query",
-            "schema": {
-              "type": "integer",
-              "format": "int32",
-              "minimum": 1,
-              "maximum": 100,
-              "default": 50
-            }
-          },
-          {
-            "description": "Указатель на следующую страницу данных. Для первой страницы передайте `null`",
-            "name": "marker",
-            "in": "query",
-            "schema": {
-              "$ref": "#/components/schemas/bigint"
-            }
-          }
+          "bots"
         ],
+        "summary": "Edit current bot commands",
+        "operationId": "editMyCommands",
+        "description": "Edits current bot Commands.",
         "responses": {
           "200": {
-            "description": "В ответе с пагинацией возвращаются чаты",
+            "description": "Modified bot commands info",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ChatList"
+                  "$ref": "#/components/schemas/BotCommandsInfo"
                 }
               }
             }
@@ -148,49 +171,16 @@
           "500": {
             "$ref": "#/components/responses/InternalError"
           }
-        }
-      }
-    },
-    "/chats/{chatLink}": {
-      "get": {
-        "tags": [
-          "chats"
-        ],
-        "x-opGroup": "chat",
-        "operationId": "getChatByLink",
-        "description": "Возвращает информацию о групповом чате по его идентификатору из пригласительной ссылки. Символ @ опционален — можно передать `mychat` или `@mychat`\n\nПример запроса:\n```bash\ncurl -X GET \"https://platform-api.max.ru/chats/mychat\" \\\n  -H \"Authorization: {access_token}\"\n```",
-        "summary": "Получение группового чата по ссылке",
-        "parameters": [
-          {
-            "name": "chatLink",
-            "description": "Уникальный идентификатор чата из пригласительной ссылки. Может начинаться с `@`, содержит латиницу, цифры, `_` и `-`",
-            "required": true,
-            "in": "path",
-            "schema": {
-              "type": "string",
-              "pattern": "@?[a-zA-Z]+[a-zA-Z0-9-_]*"
-            }
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Информация о чате",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Chat"
-                }
+        },
+        "requestBody": {
+          "description": "Bot commands to set",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BotCommandsPatch"
               }
             }
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
-          },
-          "500": {
-            "$ref": "#/components/responses/InternalError"
           }
         }
       }
@@ -200,26 +190,28 @@
         "tags": [
           "chats"
         ],
-        "x-opGroup": "chat",
         "operationId": "getChat",
-        "description": "Возвращает информацию о групповом чате по его ID\n\nПример запроса:\n```bash\ncurl -X GET \"https://platform-api.max.ru/chats/{chatId}\" \\\n  -H \"Authorization: {access_token}\"\n```",
-        "summary": "Получение информации о групповом чате",
+        "description": "Returns info about chat or channel.",
+        "summary": "Get chat",
         "parameters": [
           {
             "name": "chatId",
-            "description": "ID запрашиваемого чата",
+            "description": "Requested chat or channel identifier",
             "required": true,
             "in": "path",
             "schema": {
-              "type": "integer",
-              "format": "int64",
-              "pattern": "\\-?\\d+"
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/ChatId"
+                }
+              ],
+              "x-pattern": "\\-?\\d+"
             }
           }
         ],
         "responses": {
           "200": {
-            "description": "Информация о чате",
+            "description": "Chat or channel information",
             "content": {
               "application/json": {
                 "schema": {
@@ -240,24 +232,27 @@
         "tags": [
           "chats"
         ],
-        "x-opGroup": "chat",
         "operationId": "editChat",
-        "description": "Позволяет редактировать информацию о групповом чате, включая название, иконку и закреплённое сообщение\n\nПример запроса:\n```bash\ncurl -X PATCH \"https://platform-api.max.ru/chats/{chatId}\" \\\n  -H \"Authorization: {access_token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"icon\": { \"url\": \"https://example.com/image.jpg\" },\n  \"title\": \"Название чата\",\n  \"notify\": true\n}'\n```",
-        "summary": "Изменение информации о групповом чате",
+        "description": "Edits chat or channel info: title, icon, etc…",
+        "summary": "Edit chat or channel info",
         "parameters": [
           {
             "name": "chatId",
-            "description": "ID чата",
+            "description": "Chat or channel identifier",
             "required": true,
             "in": "path",
             "schema": {
-              "type": "integer",
-              "format": "int64",
-              "pattern": "\\-?\\d+"
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/ChatId"
+                }
+              ],
+              "x-pattern": "\\-?\\d+"
             }
           }
         ],
         "requestBody": {
+          "description": "Chat or channel info to update",
           "required": true,
           "content": {
             "application/json": {
@@ -288,42 +283,6 @@
             "$ref": "#/components/responses/InternalError"
           }
         }
-      },
-      "delete": {
-        "tags": [
-          "chats"
-        ],
-        "x-opGroup": "chat",
-        "operationId": "deleteChat",
-        "description": "Удаляет групповой чат для всех участников\n\nПример запроса:\n```bash\ncurl -X DELETE \"https://platform-api.max.ru/chats/{chatId}\" \\\n  -H \"Authorization: {access_token}\"\n```",
-        "summary": "Удаление группового чата",
-        "parameters": [
-          {
-            "name": "chatId",
-            "description": "ID чата",
-            "required": true,
-            "in": "path",
-            "schema": {
-              "type": "integer",
-              "format": "int64",
-              "pattern": "\\-?\\d+"
-            }
-          }
-        ],
-        "responses": {
-          "200": {
-            "$ref": "#/components/responses/SuccessResponse"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
-          },
-          "500": {
-            "$ref": "#/components/responses/InternalError"
-          }
-        }
       }
     },
     "/chats/{chatId}/actions": {
@@ -332,22 +291,26 @@
           "chats"
         ],
         "operationId": "sendAction",
-        "description": "Позволяет отправлять в групповой чат такие действия бота, как например: «набор текста» или «отправка фото»\n\nПример запроса:\n```bash\ncurl -X POST \"https://platform-api.max.ru/chats/{chatId}/actions\" \\\n  -H \"Authorization: {access_token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"action\": \"typing_on\"\n}'\n```",
-        "summary": "Отправка действия бота в групповой чат",
+        "description": "Send bot action to chat.",
+        "summary": "Send action",
         "parameters": [
           {
             "name": "chatId",
-            "description": "ID чата",
+            "description": "Chat identifier",
             "required": true,
             "in": "path",
             "schema": {
-              "type": "integer",
-              "format": "int64",
-              "pattern": "\\-?\\d+"
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/ChatId"
+                }
+              ],
+              "x-pattern": "\\-?\\d+"
             }
           }
         ],
         "requestBody": {
+          "description": "Action to send to chat members",
           "required": true,
           "content": {
             "application/json": {
@@ -376,24 +339,27 @@
           "chats"
         ],
         "operationId": "getPinnedMessage",
-        "description": "Возвращает закреплённое сообщение в групповом чате\n\nПример запроса:\n```bash\ncurl -X GET \"https://platform-api.max.ru/chats/{chatId}/pin\" \\\n  -H \"Authorization: {access_token}\"\n```",
-        "summary": "Получение закреплённого сообщения в групповом чате",
+        "description": "Get pinned message in chat or channel.",
+        "summary": "Get pinned message",
         "parameters": [
           {
             "name": "chatId",
-            "description": "ID чата",
+            "description": "Chat identifier to get its pinned message",
             "required": true,
             "in": "path",
             "schema": {
-              "type": "integer",
-              "format": "int64",
-              "pattern": "\\-?\\d+"
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/ChatId"
+                }
+              ],
+              "x-pattern": "\\-?\\d+"
             }
           }
         ],
         "responses": {
           "200": {
-            "description": "Закреплённое сообщение",
+            "description": "Pinned message",
             "content": {
               "application/json": {
                 "schema": {
@@ -421,22 +387,26 @@
           "chats"
         ],
         "operationId": "pinMessage",
-        "description": "Закрепляет сообщение в групповом чате\n\nПример запроса:\n```bash\ncurl -X PUT \"https://platform-api.max.ru/chats/{chatId}/pin\" \\\n  -H \"Authorization: {access_token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"message_id\": \"{message_id}\",\n  \"notify\": true\n}'\n```",
-        "summary": "Закрепление сообщения в групповом чате",
+        "description": "Pins message in chat or channel.",
+        "summary": "Pin message",
         "parameters": [
           {
             "name": "chatId",
-            "description": "ID чата, где должно быть закреплено сообщение",
+            "description": "Chat identifier where message should be pinned",
             "required": true,
             "in": "path",
             "schema": {
-              "type": "integer",
-              "format": "int64",
-              "pattern": "\\-?\\d+"
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/ChatId"
+                }
+              ],
+              "x-pattern": "\\-?\\d+"
             }
           }
         ],
         "requestBody": {
+          "description": "Message to pin in chat",
           "required": true,
           "content": {
             "application/json": {
@@ -469,18 +439,21 @@
           "chats"
         ],
         "operationId": "unpinMessage",
-        "description": "Удаляет закреплённое сообщение в групповом чате\n\nПример запроса:\n```bash\ncurl -X DELETE \"https://platform-api.max.ru/chats/{chatId}/pin\" \\\n  -H \"Authorization: {access_token}\"\n```",
-        "summary": "Удаление закреплённого сообщения в групповом чате",
+        "description": "Unpins message in chat or channel.",
+        "summary": "Unpin message",
         "parameters": [
           {
             "name": "chatId",
-            "description": "ID чата, из которого нужно удалить закреплённое сообщение",
+            "description": "Chat identifier to remove pinned message",
             "required": true,
             "in": "path",
             "schema": {
-              "type": "integer",
-              "format": "int64",
-              "pattern": "\\-?\\d+"
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/ChatId"
+                }
+              ],
+              "x-pattern": "\\-?\\d+"
             }
           }
         ],
@@ -508,26 +481,28 @@
         "tags": [
           "chats"
         ],
-        "x-opGroup": "myMembership",
         "operationId": "getMembership",
-        "summary": "Получение информации о членстве бота в групповом чате",
-        "description": "Возвращает информацию о членстве текущего бота в групповом чате. Бот идентифицируется с помощью токена доступа\n\nПример запроса:\n```bash\ncurl -X GET \"https://platform-api.max.ru/chats/{chatId}/members/me\" \\\n  -H \"Authorization: {access_token}\"\n```",
+        "summary": "Get chat or channel membership",
+        "description": "Returns chat or channel  membership info for current bot",
         "parameters": [
           {
             "name": "chatId",
-            "description": "ID чата",
+            "description": "Chat or channel identifier",
             "required": true,
             "in": "path",
             "schema": {
-              "type": "integer",
-              "format": "int64",
-              "pattern": "\\-?\\d+"
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/ChatId"
+                }
+              ],
+              "x-pattern": "\\-?\\d+"
             }
           }
         ],
         "responses": {
           "200": {
-            "description": "Текущаяя информация о членстве бота",
+            "description": "Current bot membership info",
             "content": {
               "application/json": {
                 "schema": {
@@ -555,19 +530,21 @@
           "chats"
         ],
         "operationId": "leaveChat",
-        "x-opGroup": "myMembership",
-        "summary": "Удаление бота из группового чата",
-        "description": "Удаляет бота из участников группового чата\n\nПример запроса:\n```bash\ncurl -X DELETE \"https://platform-api.max.ru/chats/{chatId}/members/me\" \\\n  -H \"Authorization: {access_token}\"\n```",
+        "summary": "Leave chat",
+        "description": "Removes bot from chat or channel members.",
         "parameters": [
           {
             "name": "chatId",
-            "description": "ID чата",
+            "description": "Chat or channel identifier",
             "required": true,
             "in": "path",
             "schema": {
-              "type": "integer",
-              "format": "int64",
-              "pattern": "\\-?\\d+"
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/ChatId"
+                }
+              ],
+              "x-pattern": "\\-?\\d+"
             }
           }
         ],
@@ -596,24 +573,27 @@
           "chats"
         ],
         "operationId": "getAdmins",
-        "summary": "Получение списка администраторов группового чата",
-        "description": "Возвращает список всех администраторов группового чата. Бот должен быть администратором в запрашиваемом чате\n\nПример запроса:\n```bash\ncurl -X GET \"https://platform-api.max.ru/chats/{chatId}/members/admins\" \\\n  -H \"Authorization: {access_token}\"\n```",
+        "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": "ID чата",
+            "description": "Chat or channel identifier",
             "required": true,
             "in": "path",
             "schema": {
-              "type": "integer",
-              "format": "int64",
-              "pattern": "\\-?\\d+"
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/ChatId"
+                }
+              ],
+              "x-pattern": "\\-?\\d+"
             }
           }
         ],
         "responses": {
           "200": {
-            "description": "Список администраторов",
+            "description": "Administrators list",
             "content": {
               "application/json": {
                 "schema": {
@@ -640,23 +620,27 @@
         "tags": [
           "chats"
         ],
-        "operationId": "setAdmins",
-        "description": "Возвращает значение `true`, если в групповой чат добавлены все администраторы \n\nПример запроса:\n```bash\ncurl -X POST \"https://platform-api.max.ru/chats/{chatId}/members/admins\" \\\n  -H \"Authorization: {access_token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"admins\": [\n    {\n      \"user_id\": \"{user_id}\",\n      \"permissions\": [\n        \"read_all_messages\",\n        \"add_remove_members\",\n        \"add_admins\",\n        \"change_chat_info\",\n        \"pin_message\",\n        \"write\"\n      ],\n      \"alias\": \"Admin\"\n    }\n  ]\n}'\n```",
-        "summary": "Назначить администратора группового чата",
+        "operationId": "postAdmins",
+        "summary": "Set chat or channel admins",
+        "description": "Returns true if all administrators added. Additional permissions may require",
         "parameters": [
           {
             "name": "chatId",
-            "description": "ID чата",
+            "description": "Chat or channel identifier",
             "required": true,
             "in": "path",
             "schema": {
-              "type": "integer",
-              "format": "int64",
-              "pattern": "\\-?\\d+"
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/ChatId"
+                }
+              ],
+              "x-pattern": "\\-?\\d+"
             }
           }
         ],
         "requestBody": {
+          "description": "List of administrators to set in chat or channel",
           "required": true,
           "content": {
             "application/json": {
@@ -673,6 +657,12 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
           "500": {
             "$ref": "#/components/responses/InternalError"
           }
@@ -684,29 +674,36 @@
         "tags": [
           "chats"
         ],
-        "operationId": "deleteAdmin",
-        "description": "Отменяет права администратора у пользователя в групповом чате, лишая его административных привилегий\n\nПример запроса:\n```bash\ncurl -X DELETE \"https://platform-api.max.ru/chats/{chatId}/members/admins/{userId}\" \\\n  -H \"Authorization: {access_token}\"\n```",
-        "summary": "Отменить права администратора в групповом чате",
+        "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": "ID чата",
+            "description": "Chat or channel identifier",
             "required": true,
             "in": "path",
             "schema": {
-              "type": "integer",
-              "format": "int64",
-              "pattern": "\\-?\\d+"
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/ChatId"
+                }
+              ],
+              "x-pattern": "\\-?\\d+"
             }
           },
           {
             "name": "userId",
-            "description": "Идентификатор пользователя",
+            "description": "User identifier",
             "required": true,
             "in": "path",
             "schema": {
-              "type": "integer",
-              "format": "int64"
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/UserId"
+                }
+              ],
+              "x-pattern": "\\d+"
             }
           }
         ],
@@ -729,39 +726,41 @@
           "chats"
         ],
         "operationId": "getMembers",
-        "summary": "Получение участников группового чата",
-        "description": "Возвращает список участников группового чата\n\nПример запроса:\n```bash\ncurl -X GET \"https://platform-api.max.ru/chats/{chatId}/members\" \\\n  -H \"Authorization: {access_token}\"\n```",
+        "summary": "Get members",
+        "description": "Returns users participated in chat or channel.",
         "parameters": [
           {
             "name": "chatId",
-            "description": "ID чата",
+            "description": "Chat or channel identifier",
             "required": true,
             "in": "path",
             "schema": {
-              "type": "integer",
-              "format": "int64",
-              "pattern": "\\-?\\d+"
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/ChatId"
+                }
+              ],
+              "x-pattern": "\\-?\\d+"
             }
           },
           {
             "name": "user_ids",
-            "description": "Список ID пользователей, чье членство нужно получить. Когда этот параметр передан, параметры `count` и `marker` игнорируются",
+            "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": {
-                "type": "integer",
-                "format": "int64"
+                "$ref": "#/components/schemas/UserId"
               },
               "nullable": true
             },
-            "style": "simple"
+            "style": "form"
           },
           {
             "name": "marker",
-            "description": "Указатель на следующую страницу данных",
+            "description": "Marker",
             "in": "query",
             "schema": {
               "type": "integer",
@@ -770,19 +769,19 @@
           },
           {
             "name": "count",
-            "description": "Количество участников, которых нужно вернуть",
+            "description": "Count",
             "in": "query",
             "schema": {
               "type": "integer",
               "minimum": 1,
               "maximum": 100,
-              "default": "20"
+              "default": 20
             }
           }
         ],
         "responses": {
           "200": {
-            "description": "Возвращает список участников и указатель на следующую страницу данных.",
+            "description": "Returns members list and pointer to the next data page",
             "content": {
               "application/json": {
                 "schema": {
@@ -810,22 +809,26 @@
           "chats"
         ],
         "operationId": "addMembers",
-        "description": "Добавляет участников в групповой чат. Для этого могут потребоваться дополнительные права\n\nПример запроса:\n```bash\ncurl -X POST \"https://platform-api.max.ru/chats/{chatId}/members\" \\\n  -H \"Authorization: {access_token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"user_ids\": [\"{user_id_1}\", \"{user_id_2}\"]\n}'\n```",
-        "summary": "Добавление участников в групповой чат",
+        "description": "Adds members to chat. Additional permissions may require.",
+        "summary": "Add members",
         "parameters": [
           {
             "name": "chatId",
-            "description": "ID чата",
+            "description": "Chat identifier",
             "required": true,
             "in": "path",
             "schema": {
-              "type": "integer",
-              "format": "int64",
-              "pattern": "\\-?\\d+"
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/ChatId"
+                }
+              ],
+              "x-pattern": "\\-?\\d+"
             }
           }
         ],
         "requestBody": {
+          "description": "List of users to add to chat",
           "required": true,
           "content": {
             "application/json": {
@@ -837,7 +840,14 @@
         },
         "responses": {
           "200": {
-            "$ref": "#/components/responses/SuccessResponse"
+            "description": "Result of chat members modification request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ModifyMembersResult"
+                }
+              }
+            }
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
@@ -858,33 +868,35 @@
           "chats"
         ],
         "operationId": "removeMember",
-        "description": "Удаляет участника из группового чата. Для этого могут потребоваться дополнительные права\n\nПример запроса:\n```bash\ncurl -X DELETE \"https://platform-api.max.ru/chats/{chatId}/members/{user_id}?block=true\" \\\n  -H \"Authorization: {access_token}\"\n```",
-        "summary": "Удаление участника из группового чата",
+        "description": "Removes member from chat or channel. Additional permissions may require.",
+        "summary": "Remove member",
         "parameters": [
           {
             "name": "chatId",
-            "description": "ID чата",
+            "description": "Chat or channel identifier",
             "required": true,
             "in": "path",
             "schema": {
-              "type": "integer",
-              "format": "int64",
-              "pattern": "\\-?\\d+"
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/ChatId"
+                }
+              ],
+              "x-pattern": "\\-?\\d+"
             }
           },
           {
             "name": "user_id",
-            "description": " ID пользователя, которого нужно удалить из чата",
+            "description": "User id to remove from chat or channel",
             "required": true,
             "in": "query",
             "schema": {
-              "type": "integer",
-              "format": "int64"
+              "$ref": "#/components/schemas/UserId"
             }
           },
           {
             "name": "block",
-            "description": "Если установлено в `true`, пользователь будет заблокирован в чате. Применяется только для чатов с публичной или приватной ссылкой. Игнорируется в остальных случаях",
+            "description": "Set to `true` if user should be blocked in chat.\nApplicable only for chats that have public or private link. Ignored otherwise",
             "required": false,
             "in": "query",
             "schema": {
@@ -915,11 +927,11 @@
           "subscriptions"
         ],
         "operationId": "getSubscriptions",
-        "description": "Если ваш бот получает данные через WebHook, этот метод возвращает список всех подписок\n\n>Обратите внимание: для отправки вебхуков поддерживается только протокол HTTPS, включая самоподписанные сертификаты. HTTP не поддерживается\n\nПример запроса:\n```bash\ncurl -X GET \"https://platform-api.max.ru/subscriptions\" \\\n  -H \"Authorization: {access_token}\"\n```",
-        "summary": "Получение подписок",
+        "description": "In case your bot gets data via WebHook, the method returns list of all subscriptions",
+        "summary": "Get subscriptions",
         "responses": {
           "200": {
-            "description": "Ожидаемый результат",
+            "description": "As expected",
             "content": {
               "application/json": {
                 "schema": {
@@ -941,9 +953,10 @@
           "subscriptions"
         ],
         "operationId": "subscribe",
-        "description": "Подписывает бота на получение обновлений через WebHook. После вызова этого метода бот будет получать уведомления о новых событиях в чатах на указанный URL.\nВаш сервер **должен** прослушивать один из следующих портов: `80`, `8080`, `443`, `8443`, `16384`-`32383`\n\nПример запроса:\n```bash\ncurl -X POST \"https://platform-api.max.ru/subscriptions\" \\\n  -H \"Authorization: {access_token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"url\": \"https://your-domain.com/webhook\",\n  \"update_types\": [\"message_created\", \"bot_started\"],\n  \"secret\": \"your_secret\"\n}'\n```",
-        "summary": "Подписка на обновления",
+        "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.\n\nYour server **must** be listening on port **443**",
+        "summary": "Subscribe",
         "requestBody": {
+          "description": "WebHook subscription parameters",
           "required": true,
           "content": {
             "application/json": {
@@ -970,13 +983,13 @@
           "subscriptions"
         ],
         "operationId": "unsubscribe",
-        "description": "Отписывает бота от получения обновлений через WebHook. После вызова этого метода бот перестаёт получать уведомления о новых событиях, и становится доступна доставка уведомлений через API с длительным опросом\n\nПример запроса:\n```bash\ncurl -X DELETE \"https://platform-api.max.ru/subscriptions?url=https://your-domain.com/webhook\" \\\n  -H \"Authorization: {access_token}\"\n```",
-        "summary": "Отписка от обновлений",
+        "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, который нужно удалить из подписок на WebHook",
+            "description": "URL to remove from WebHook subscriptions",
             "required": true,
             "schema": {
               "type": "string"
@@ -1002,11 +1015,11 @@
           "upload"
         ],
         "operationId": "getUploadUrl",
-        "description": "Возвращает URL для последующей загрузки файла\n\nПоддерживаются два типа загрузки:\n- **Multipart upload** — более простой, но менее надёжный способ. В этом случае используется заголовок `Content-Type: multipart/form-data`. Этот способ имеет ограничения:\n    - Максимальный размер файла: 4 ГБ\n    - Можно загружать только один файл за раз\n    - Невозможно перезапустить загрузку, если она была остановлена\n\n    \n- **Resumable upload** — более надёжный способ, если заголовок `Content-Type` не равен `multipart/form-data`. Этот способ позволяет загружать файл частями и возобновить загрузку с последней успешно загруженной части в случае ошибок\n\nПример получения ссылки для загрузки:\n\n```bash\ncurl -X POST \"https://platform-api.max.ru/uploads?type=file\" \\\n  -H \"Authorization: {access_token}\"\n```\n\nПример загрузки файла по полученному URL:\n\n```bash\ncurl -X POST \"%UPLOAD_URL%\" \\\n  -H \"Authorization: {access_token}\" \\\n  -F \"data=@example.mp4\"\n```\n\nПример использования cURL для загрузки файла (вариант multipart upload):\n\n```shell\ncurl -i -X POST \\\n  -H \"Content-Type: multipart/form-data\" \\\n  -F \"data=@movie.pdf\" \"%UPLOAD_URL%\"\n```\n\nГде `%UPLOAD_URL%` — это URL из результата метода в примере cURL запроса\n\n**Для загрузки видео и аудио:**\n\n1. Когда получаем ссылку на загрузку видео или аудио (`POST /uploads` с `type` = `video` или `type` = `audio`), вместе с `url` в ответе приходит `token`, который нужно использовать в сообщении (когда формируете `body` с `attachments`) в `POST /messages`.\n\n2. После загрузки видео или аудио (по `url` из шага выше) сервер возвращает `retval`\n\n3. C этого момента можно использовать `token`, чтобы прикреплять вложение в сообщение бота\n\nМеханика отличается от `type` = `image` | `file`, где `token` возвращается в ответе на загрузку изображения или файла\n\n## Прикрепление медиа\nМедиафайлы прикрепляются к сообщениям поэтапно:\n\n1. Получите URL для загрузки медиафайлов\n2. Загрузите файл по полученному URL\n3. После успешной загрузки получите JSON-объект в ответе. Используйте этот объект для создания вложения. Структура вложения:\n    - `type`: тип медиа (например, `\"video\"`)\n    - `payload`: JSON-объект, который вы получили\n\nПример для видео:\n1. Получите URL для загрузки:\n```bash\ncurl -X POST \"https://platform-api.max.ru/uploads?type=video\" \\\n  -H \"Authorization: {access_token}\"\n```\n\nОтвет:\n```json\n{\n    \"url\": \"https://vu.mycdn.me/upload.do…\"\n}\n```\n\n2. Загрузите видео по URL:\n\n```bash\ncurl -X POST \\\n  -H \"Content-Type: multipart/form-data\" \\\n  -F \"data=@movie.mp4\" \\\n  \"https://vu.mycdn.me/upload.do?sig={signature}&expires={timestamp}\"\n```\n\nОтвет:\n```json\n{\n    \"token\": \"_3Rarhcf1PtlMXy8jpgie8Ai_KARnVFYNQTtmIRWNh4\"\n}\n```\n\n3. Отправьте сообщение с вложением:\n\n```json\n{\n    \"text\": \"Message with video\",\n    \"attachments\": [\n        {\n            \"type\": \"video\",\n            \"payload\": {\n                \"token\": \"_3Rarhcf1PtlMXy8jpgie8Ai_KARnVFYNQTtmIRWNh4\"\n            }\n        }\n    ]\n}\n```\n\n",
-        "summary": "Загрузка файлов",
+        "description": "Returns the URL for the subsequent file upload.\n\nFor example, you can upload it via curl:\n\n```curl -i -X POST\n  -H \"Content-Type: multipart/form-data\"\n  -F \"data=@movie.mp4\" \"%UPLOAD_URL%\"```\n\nTwo types of an upload are supported:\n- single request upload (multipart request)\n- and resumable upload.\n\n##### Multipart upload\nThis type of upload is a simpler one but it is less\nreliable and agile. If a `Content-Type`: multipart/form-data header is passed in a request our service indicates\nupload type as a simple single request upload.\n\nThis type of an upload has some restrictions: \n\n- 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.\n- video — available formats: MP4, MOV, MKV, WEBM; maximum size for a single video: up to 250 MB\n- 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.\n- file — available formats: TXT, DOC, PDF, and other common formats, maximum size for a single file: up to 4 GB\n- type=photo parameter is no longer supported. If you used type=photo in previously created integrations, please replace it with type=image\n- Only one mediafile per request can be uploaded\n- No possibility to restart stopped / failed upload\n\n##### Resumable upload\nIf `Content-Type` header value is not equal to `multipart/form-data` our service indicated upload type\nas a resumable upload.\nWith a `Content-Range` header current file chunk range and complete file size\ncan be passed. If a network error has happened or upload was stopped you can continue to upload a file from\nthe last successfully uploaded file chunk. You can request the last known byte of uploaded file from server\nand continue to upload a file.\n\n##### Get upload status\nTo GET an upload status you simply need to perform HTTPS-GET request to a file upload URL.\nOur service will respond with current upload status,\ncomplete file size and last known uploaded byte. This data can be used to complete stopped upload\nif something went wrong. If `REQUESTED_RANGE_NOT_SATISFIABLE` or `INTERNAL_SERVER_ERROR` status was returned\nit is a good point to try to restart an upload",
+        "summary": "Get upload URL",
         "parameters": [
           {
-            "description": "Тип загружаемого файла. Возможные значения: `\"image\"`, `\"video\"`, `\"audio\"`, `\"file\"`",
+            "description": "Uploaded file type: image, audio, video, file",
             "name": "type",
             "required": true,
             "in": "query",
@@ -1017,7 +1030,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Возвращает URL для загрузки вложения.",
+            "description": "Returns URL to upload attachment",
             "content": {
               "application/json": {
                 "schema": {
@@ -1041,22 +1054,22 @@
           "messages"
         ],
         "operationId": "getMessages",
-        "description": "Возвращает сообщения в чате: страницу с результатами и маркер, указывающий на следующую страницу. Сообщения возвращаются в обратном порядке, то есть последние сообщения в чате будут первыми в массиве. Поэтому, если вы используете параметры `from` и `to`, то `to` должно быть **меньше**, чем `from`. Для выполнения запроса нужно указать один из двух параметров: `chat_id` — если нужно получить сообщения из чата, или `message_ids` — если нужны конкретные сообщения по их ID\n\nПример запроса с использованием `chat_id`:\n```bash\ncurl -X GET \"https://platform-api.max.ru/messages?chat_id={chat_id}\" \\\n  -H \"Authorization: {access_token}\"\n```\n\nПример запроса с использованием `message_Ids`:\n```bash\ncurl -X GET \"https://platform-api.max.ru/messages?message_ids={message_id1},{message_id2}\" \\\n  -H \"Authorization: {access_token}\"\n```",
-        "summary": "Получение сообщений",
+        "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": " ID чата, чтобы получить сообщения из определённого чата. Обязательный параметр, если не указан message_ids",
+            "description": "Chat or channel identifier to get messages in chat or channel",
             "name": "chat_id",
             "in": "query",
             "schema": {
-              "$ref": "#/components/schemas/bigint"
+              "$ref": "#/components/schemas/ChatId"
             }
           },
           {
-            "description": "Список ID сообщений, которые нужно получить (через запятую). Обязательный параметр, если не указан chat_id",
+            "description": "Comma-separated list of message ids to get",
             "name": "message_ids",
             "in": "query",
-            "style": "simple",
+            "style": "form",
             "schema": {
               "uniqueItems": true,
               "items": {
@@ -1067,23 +1080,45 @@
           },
           {
             "name": "from",
-            "description": "Время начала для запрашиваемых сообщений (в формате Unix timestamp)",
+            "description": "Start time for requested messages - use after instead",
             "in": "query",
             "schema": {
               "$ref": "#/components/schemas/bigint"
-            }
+            },
+            "deprecated": true
           },
           {
             "name": "to",
-            "description": "Время окончания для запрашиваемых сообщений (в формате Unix timestamp)",
+            "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": "Максимальное количество сообщений в ответе",
+            "description": "Maximum amount of messages in response",
             "in": "query",
             "schema": {
               "type": "integer",
@@ -1096,7 +1131,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Возвращает список сообщений",
+            "description": "Returns list of messages",
             "content": {
               "application/json": {
                 "schema": {
@@ -1109,7 +1144,7 @@
             "$ref": "#/components/responses/Unauthorized"
           },
           "403": {
-            "description": "Это исключение возникает, когда пользователь приостановил бота или у него нет доступа к чату",
+            "description": "This exception happens when user suspended bot or it doesn't have access to chat",
             "content": {
               "application/json": {
                 "schema": {
@@ -1128,32 +1163,30 @@
           "messages"
         ],
         "operationId": "sendMessage",
-        "description": "Отправляет сообщение в чат\n\nПример запроса:\n````bash\ncurl -X POST \"https://platform-api.max.ru/messages?user_id={user_id}\" \\\n  -H \"Authorization: {access_token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"text\": \"Это сообщение с кнопкой-ссылкой\",\n  \"attachments\": [\n    {\n      \"type\": \"inline_keyboard\",\n      \"payload\": {\n        \"buttons\": [\n          [\n            {\n              \"type\": \"link\",\n              \"text\": \"Откройте сайт\",\n              \"url\": \"https://example.com\"\n            }\n          ]\n        ]\n      }\n    }\n  ]\n}'",
-        "summary": "Отправить сообщение",
+        "description": "Sends a message to a chat, channel or dialog. \nAs a result for this method new message identifier returns.\nIn the case of a channel, it returns an error if you pass notify=false\n### Attaching media\nAttaching media to messages is a three-step process.\n\nAt first step, you should obtain a URL to upload your media files.\n\nAt 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.\n\nFinally, 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:\n- `type` with the value set to appropriate media type\n- and `payload` filled with the JSON you've got.\n\nFor example, you can attach a video to message this way:\n\n1. Get URL to upload. Execute following:\n```shell\ncurl -X POST 'https://platform-api2.max.ru/uploads?type=video' -H 'Authorization: %access_token%' \n```\nAs the result it will return URL for the next step.\n```json\n{\n    \"url\": \"http://omub.okcdn.ru/upload.do…\" \n}\n```\n\n2. Use this url to upload your binary:\n```shell\ncurl -i -X POST\n  -H \"Content-Type: multipart/form-data\"\n  -F \"data=@movie.mp4\" \"http://omub.okcdn.ru/upload.do…\" \n```\nAs the result it will return JSON you can attach to message:\n```json\n  {\n    \"token\": \"_3Rarhcf1PtlMXy8jpgie8Ai_KARnVFYNQTtmIRWNh4\"\n  }\n```\n3. Send message with attach:\n```json\n{\n    \"text\": \"Message with video\",\n    \"attachments\": [\n        {\n            \"type\": \"video\",\n            \"payload\": {\n                \"token\": \"_3Rarhcf1PtlMXy8jpgie8Ai_KARnVFYNQTtmIRWNh4\"\n            }\n        }\n    ]\n}\n```\n\n**Important notice**:\n\nIt may take time for the server to process your file (audio/video or any binary).\nWhile a file is not processed you can't attach it. It means the last step will fail with `400` error.\nTry to send a message again until you'll get a successful result.",
+        "summary": "Send message",
         "parameters": [
           {
             "name": "user_id",
-            "description": "Если вы хотите отправить сообщение пользователю, укажите его ID",
+            "description": "Fill this parameter if you want to send message to user",
             "in": "query",
             "required": false,
             "schema": {
-              "type": "integer",
-              "format": "int64"
+              "$ref": "#/components/schemas/UserId"
             }
           },
           {
             "name": "chat_id",
-            "description": "Если сообщение отправляется в чат, укажите его ID",
+            "description": "Fill this if you send message to chat or channel",
             "schema": {
-              "type": "integer",
-              "format": "int64"
+              "$ref": "#/components/schemas/ChatId"
             },
             "in": "query",
             "required": false
           },
           {
             "name": "disable_link_preview",
-            "description": " Если `false`, сервер не будет генерировать превью для ссылок в тексте сообщения",
+            "description": "If `false`, server will not generate media preview for links in text",
             "in": "query",
             "required": false,
             "schema": {
@@ -1163,6 +1196,7 @@
           }
         ],
         "requestBody": {
+          "description": "Message to send",
           "required": true,
           "content": {
             "application/json": {
@@ -1174,7 +1208,7 @@
         },
         "responses": {
           "200": {
-            "description": "Возвращает информацию о созданном сообщении",
+            "description": "Returns info about created message",
             "content": {
               "application/json": {
                 "schema": {
@@ -1186,6 +1220,20 @@
           "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"
           }
@@ -1196,21 +1244,21 @@
           "messages"
         ],
         "operationId": "editMessage",
-        "description": "Редактирует сообщение в чате. Если поле `attachments` равно `null`, вложения текущего сообщения не изменяются. Если в этом поле передан пустой список, все вложения будут удалены\n\nПример запроса:\n```bash\ncurl -X PUT \"https://platform-api.max.ru/messages\" \\\n  -H \"Authorization: {access_token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"message_id\": \"{message_id}\",\n  \"text\": \"Изменённый текст сообщения\"\n}'\n```",
-        "summary": "Редактировать сообщение",
+        "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": "ID редактируемого сообщения",
+            "description": "Editing message identifier",
             "required": true,
             "in": "query",
             "schema": {
-              "type": "string",
-              "minLength": 1
+              "$ref": "#/components/schemas/MessageId"
             }
           }
         ],
         "requestBody": {
+          "description": "Updated message content",
           "required": true,
           "content": {
             "application/json": {
@@ -1237,17 +1285,16 @@
           "messages"
         ],
         "operationId": "deleteMessage",
-        "summary": "Удалить сообщение",
-        "description": "Удаляет сообщение в диалоге или чате, если бот имеет разрешение на удаление сообщений\n\nПример запроса:\n```bash\ncurl -X DELETE \"https://platform-api.max.ru/messages?message_id={message_id}\" \\\n  -H \"Authorization: {access_token}\"\n```",
+        "summary": "Delete message",
+        "description": "Deletes message in a dialog, chat or channel if bot has permission to delete messages.",
         "parameters": [
           {
             "name": "message_id",
-            "description": "ID удаляемого сообщения",
+            "description": "Deleting message identifier",
             "required": true,
             "in": "query",
             "schema": {
-              "type": "string",
-              "minLength": 1
+              "$ref": "#/components/schemas/MessageId"
             }
           }
         ],
@@ -1273,23 +1320,27 @@
           "messages"
         ],
         "operationId": "getMessageById",
-        "description": "Возвращает сообщение по его ID\n\nПример запроса:\n```bash\ncurl -X GET \"https://platform-api.max.ru/messages/{messageId}\" \\\n  -H \"Authorization: {access_token}\"\n```",
-        "summary": "Получить сообщение",
+        "description": "Returns single message by its identifier.",
+        "summary": "Get message",
         "parameters": [
           {
-            "description": "ID сообщения (`mid`), чтобы получить одно сообщение в чате",
+            "description": "Message identifier (`mid`) to get single message in chat or channel",
             "in": "path",
             "name": "messageId",
             "required": true,
             "schema": {
-              "type": "string",
-              "pattern": "[a-zA-Z0-9_\\-]+"
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/MessageId"
+                }
+              ],
+              "pattern": "(mid.)?[a-zA-Z0-9_\\-]+"
             }
           }
         ],
         "responses": {
           "200": {
-            "description": "Возвращает одно сообщение",
+            "description": "Returns single message",
             "content": {
               "application/json": {
                 "schema": {
@@ -1302,7 +1353,327 @@
             "$ref": "#/components/responses/Unauthorized"
           },
           "404": {
-            "description": "В случае, если сообщение не найдено или бот не имеет доступа к нему",
+            "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": {
@@ -1323,17 +1694,17 @@
           "messages"
         ],
         "operationId": "getVideoAttachmentDetails",
-        "description": "Возвращает подробную информацию о прикреплённом видео. URL-адреса воспроизведения и дополнительные метаданные\n\nПример запроса:\n```bash\ncurl -X GET \"https://platform-api.max.ru/videos/{video_token}\" \\\n  -H \"Authorization: {access_token}\"",
-        "summary": "Получить информацио о видео",
+        "description": "Returns detailed information about video attachment: playback URLs and additional metadata.",
+        "summary": "Get video details",
         "parameters": [
           {
-            "description": "Токен видео-вложения",
+            "description": "Video attachment token",
             "in": "path",
             "name": "videoToken",
             "required": true,
             "schema": {
               "type": "string",
-              "pattern": "[a-zA-Z0-9_\\-]+"
+              "pattern": "[\\w-]+"
             }
           }
         ],
@@ -1355,7 +1726,7 @@
             "$ref": "#/components/responses/Forbidden"
           },
           "404": {
-            "description": "В случае, если сообщение не найдено или бот не имеет доступа к нему",
+            "description": "In case when message is not found or bot has no access to it",
             "content": {
               "application/json": {
                 "schema": {
@@ -1376,22 +1747,33 @@
           "messages"
         ],
         "operationId": "answerOnCallback",
-        "description": "Этот метод используется для отправки ответа после того, как пользователь нажал на кнопку. Ответом может быть обновленное сообщение и/или одноразовое уведомление для пользователя\n\nПример запроса:\n```bash\ncurl -X POST \"https://platform-api.max.ru/answers\" \\\n  -H \"Authorization: Bearer {access_token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"callback_id\": \"123\",\n    \"message\": {\n      \"text\": \"Спасибо за ваш ответ!\",\n      \"attachments\": [\n        {\n          \"type\": \"photo\",\n          \"payload\": {\n            \"url\": \"https://example.com/photo.jpg\"\n          }\n        }\n      ],\n      \"notify\": true,\n      \"format\": \"markdown\"\n    },\n    \"notification\": \"Успешно\"\n  }'\n```",
-        "summary": "Ответ на callback",
+        "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": "Идентификатор кнопки, по которой пользователь кликнул. Бот получает идентификатор как часть [Update](/docs-api/objects/Update) с типом`message_callback`.\n\nМожно получить из [GET:/updates](/docs-api/methods/GET/updates) через поле `updates[i].callback.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",
             "schema": {
               "type": "string",
               "minLength": 1,
-              "pattern": "^(?!\\s*$).+"
+              "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": {
@@ -1423,12 +1805,12 @@
         "tags": [
           "subscriptions"
         ],
-        "description": "Этот метод можно использовать для получения обновлений, если ваш бот не подписан на WebHook. Метод использует долгий опрос (long polling).\n\nКаждое обновление имеет свой номер последовательности. Свойство `marker` в ответе указывает на следующее ожидаемое обновление.\n\nВсе предыдущие обновления считаются завершёнными после прохождения параметра `marker`. Если параметр `marker` **не передан**, бот получит все обновления, произошедшие после последнего подтверждения\n\nПример запроса:\n```bash\ncurl -X GET \"https://platform-api.max.ru/updates\" \\\n  -H \"Authorization: {access_token}\"\n```",
-        "summary": "Получение обновлений",
+        "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.\n\nYou can use this method for getting updates in case your bot is not subscribed to WebHook. The method is based on long polling.\n\nEvery update has its own sequence number. `marker` property in response points to the next upcoming update.\n\nAll previous updates are considered as *committed* after passing `marker` parameter.\nIf `marker` parameter is **not passed**, your bot will get all updates happened after the last commitment.",
+        "summary": "Get updates",
         "parameters": [
           {
             "name": "limit",
-            "description": "Максимальное количество обновлений для получения",
+            "description": "Maximum number of updates to be retrieved",
             "in": "query",
             "schema": {
               "type": "integer",
@@ -1439,7 +1821,7 @@
           },
           {
             "name": "timeout",
-            "description": "Тайм-аут в секундах для долгого опроса",
+            "description": "Timeout in seconds for long polling",
             "in": "query",
             "schema": {
               "type": "integer",
@@ -1450,7 +1832,7 @@
           },
           {
             "name": "marker",
-            "description": "Если передан, бот получит обновления, которые еще не были получены. Если не передан, получит все новые обновления",
+            "description": "Pass `null` to get updates you didn't get yet",
             "in": "query",
             "schema": {
               "type": "integer",
@@ -1460,9 +1842,14 @@
           },
           {
             "name": "types",
-            "description": "Список типов обновлений, которые бот хочет получить (например, `message_created`, `message_callback`)",
+            "description": "Comma separated list of update types your bot want to receive",
             "in": "query",
-            "example": "types=message_created,message_callback",
+            "style": "form",
+            "explode": false,
+            "example": [
+              "message_created",
+              "message_callback"
+            ],
             "schema": {
               "type": "array",
               "uniqueItems": true,
@@ -1470,13 +1857,12 @@
                 "type": "string"
               },
               "nullable": true
-            },
-            "style": "simple"
+            }
           }
         ],
         "responses": {
           "200": {
-            "description": "Список обновлений",
+            "description": "List of updates",
             "content": {
               "application/json": {
                 "schema": {
@@ -1502,14 +1888,14 @@
     "securitySchemes": {
       "access_token": {
         "type": "apiKey",
-        "name": "access_token",
-        "description": "A token is given to you by [MasterBot](https://tt.me/MasterBot) after you have created a bot.\nIn all subsequent requests to the Bot API, you **must** pass the received token as an `access_token` parameter to the HTTP request.\n\n\nIf [Terms and Conditions of Max usage](https://team.max.ru/en/terms/) have been violated, the Max administration may withdraw tokens by aborting user sessions.\nIf your token has been compromised, you can request a new one by sending a `/revoke` command to **[MasterBot](https://tt.me/MasterBot)**.",
-        "in": "query"
+        "name": "Authorization",
+        "description": "A token is given to you on https://business.max.ru/ after you have created a bot.\nIn 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": "Успешный или неуспешный результат",
+        "description": "Success or not result",
         "content": {
           "application/json": {
             "schema": {
@@ -1519,7 +1905,7 @@
         }
       },
       "InternalError": {
-        "description": "Внутренняя ошибка сервера",
+        "description": "Internal Server Error",
         "content": {
           "application/json": {
             "schema": {
@@ -1529,7 +1915,7 @@
         }
       },
       "Unauthorized": {
-        "description": "Ошибка авторизации. Не предоставлен `access_token` или токен недействителен",
+        "description": "Authorization Error. No `access_token` provided or token is invalid",
         "content": {
           "application/json": {
             "schema": {
@@ -1539,7 +1925,7 @@
         }
       },
       "Forbidden": {
-        "description": "Ошибка доступа. У вас нет прав на доступ к этому ресурсу",
+        "description": "Access error. You don't have permissions to access this resource",
         "content": {
           "application/json": {
             "schema": {
@@ -1549,7 +1935,7 @@
         }
       },
       "NotFound": {
-        "description": "Запрашиваемый ресурс не найден",
+        "description": "Requested resource is not found",
         "content": {
           "application/json": {
             "schema": {
@@ -1559,7 +1945,7 @@
         }
       },
       "NotAllowed": {
-        "description": "Метод не разрешен",
+        "description": "Method is not allowed",
         "content": {
           "application/json": {
             "schema": {
@@ -1571,58 +1957,82 @@
     },
     "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": {
-        "description": "Объект, описывающий пользователя. Имеет несколько вариаций (наследований):\n\n- [`User`](/docs-api/objects/User)\n- [`UserWithPhoto`](/docs-api/objects/UserWithPhoto)\n- [`BotInfo`](/docs-api/objects/BotInfo)\n- [`ChatMember`](/docs-api/objects/ChatMember)",
+        "type": "object",
+        "description": "User object",
         "properties": {
           "user_id": {
-            "description": "ID пользователя",
-            "type": "integer",
-            "format": "int64"
+            "description": "Users identifier",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/UserId"
+              }
+            ]
           },
           "first_name": {
-            "description": "Отображаемое имя пользователя",
+            "description": "Users first name",
             "type": "string"
           },
           "last_name": {
-            "description": "Отображаемая фамилия пользователя",
+            "description": "Users last name",
             "type": "string",
-            "nullable": true
-          },
-          "name": {
-            "description": "_Устаревшее поле, скоро будет удалено_",
-            "type": "string",
-            "readOnly": false,
-            "nullable": true
+            "nullable": true,
+            "readOnly": false
           },
           "username": {
-            "description": "Уникальное публичное имя пользователя. Может быть `null`, если пользователь недоступен или имя не задано",
+            "description": "Unique public user name. Can be `null` if user is not accessible or it is not set",
             "type": "string",
-            "nullable": true
+            "nullable": true,
+            "readOnly": false
           },
           "is_bot": {
-            "description": "`true`,  если пользователь является ботом",
+            "description": "`true` if user is bot",
             "type": "boolean"
           },
           "last_activity_time": {
-            "description": "Время последней активности пользователя в MAX (Unix-время в миллисекундах). Может быть неактуальным, если пользователь отключил статус \"онлайн\" в настройках.",
+            "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"
+            "format": "int64",
+            "nullable": true,
+            "readOnly": false
           }
         },
         "required": [
           "user_id",
           "first_name",
-          "last_name",
-          "username",
-          "is_bot",
-          "last_activity_time"
+          "is_bot"
         ]
       },
       "UserWithPhoto": {
-        "description": "Объект пользователя с фотографией",
+        "type": "object",
+        "description": "User with description and avatar URLs",
         "allOf": [
           {
             "$ref": "#/components/schemas/User"
@@ -1630,28 +2040,31 @@
           {
             "properties": {
               "description": {
-                "description": "Описание пользователя. Может быть `null`, если пользователь его не заполнил",
+                "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 аватара",
+                "description": "URL of avatar",
                 "type": "string",
-                "readOnly": false
+                "readOnly": false,
+                "nullable": true
               },
               "full_avatar_url": {
-                "description": "URL аватара большего размера",
+                "description": "URL of avatar of a bigger size",
                 "type": "string",
-                "readOnly": false
+                "readOnly": false,
+                "nullable": true
               }
             }
           }
         ]
       },
       "BotInfo": {
-        "description": "Объект, описывающий информацию о боте",
+        "type": "object",
+        "description": "Bot information with commands and official status",
         "allOf": [
           {
             "$ref": "#/components/schemas/UserWithPhoto"
@@ -1659,7 +2072,7 @@
           {
             "properties": {
               "commands": {
-                "description": "Команды, поддерживаемые ботом",
+                "description": "Commands supported by bot",
                 "type": "array",
                 "items": {
                   "$ref": "#/components/schemas/BotCommand"
@@ -1672,40 +2085,12 @@
           }
         ]
       },
-      "BotPatch": {
+      "BotCommandsInfo": {
+        "type": "object",
+        "description": "Bot commands information",
         "properties": {
-          "first_name": {
-            "description": "Отображаемое имя бота",
-            "type": "string",
-            "maxLength": 64,
-            "minLength": 1,
-            "readOnly": false,
-            "nullable": true
-          },
-          "last_name": {
-            "description": "Отображаемое второе имя бота",
-            "type": "string",
-            "maxLength": 64,
-            "minLength": 1,
-            "readOnly": false,
-            "nullable": true
-          },
-          "name": {
-            "description": "_Поле устарело, скоро будет удалено. Используйте_ `first_name`",
-            "type": "string",
-            "readOnly": false,
-            "nullable": true
-          },
-          "description": {
-            "description": "Описание бота",
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 16000,
-            "readOnly": false,
-            "nullable": true
-          },
           "commands": {
-            "description": "Команды, поддерживаемые ботом. Чтобы удалить все команды, передайте пустой список",
+            "description": "Commands supported by bot",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/BotCommand"
@@ -1713,30 +2098,36 @@
             "maxItems": 32,
             "readOnly": false,
             "nullable": true
-          },
-          "photo": {
-            "description": "Запрос на установку фото бота",
-            "allOf": [
-              {
-                "$ref": "#/components/schemas/PhotoAttachmentRequestPayload"
-              }
-            ],
-            "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": {
-        "description": "до 32 элементов
Комманды, поддерживаемые ботом",
+        "type": "object",
+        "description": "Bot command with name and description",
         "properties": {
           "name": {
-            "description": "Название команды",
+            "description": "Command name",
             "type": "string",
             "maxLength": 64,
             "minLength": 1
           },
           "description": {
-            "description": "Описание команды (по желанию)",
+            "description": "Optional command description",
             "type": "string",
             "minLength": 1,
             "maxLength": 128,
@@ -1749,14 +2140,19 @@
         ]
       },
       "Chat": {
+        "type": "object",
+        "description": "Chat, channel or dialog object",
         "properties": {
           "chat_id": {
-            "description": "ID чата",
-            "type": "integer",
-            "format": "int64"
+            "description": "Chats identifier",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ChatId"
+              }
+            ]
           },
           "type": {
-            "description": "Тип чата:\n - `\"chat\"` — Групповой чат.",
+            "description": "Type of chat. One of: dialog, chat, channel",
             "allOf": [
               {
                 "$ref": "#/components/schemas/ChatType"
@@ -1764,7 +2160,7 @@
             ]
           },
           "status": {
-            "description": "Статус чата:\n- `\"active\"` — Бот является активным участником чата.\n- `\"removed\"` — Бот был удалён из чата.\n- `\"left\"` — Бот покинул чат.\n- `\"closed\"` — Чат был закрыт.",
+            "description": "Chat status. One of:\n - active: bot is active member of chat\n - removed: bot was kicked\n - left: bot intentionally left chat\n - closed: chat was closed\n - suspended: bot was stopped by user. *Only for dialogs*",
             "allOf": [
               {
                 "$ref": "#/components/schemas/ChatStatus"
@@ -1772,38 +2168,43 @@
             ]
           },
           "title": {
-            "description": "Отображаемое название чата. Может быть `null` для диалогов",
+            "description": "Visible title of chat. Can be null for dialogs",
             "type": "string",
-            "nullable": true
+            "nullable": true,
+            "readOnly": false
           },
           "icon": {
-            "description": "Иконка чата",
+            "description": "Icon of chat",
             "nullable": true,
             "allOf": [
               {
                 "$ref": "#/components/schemas/Image"
               }
-            ]
+            ],
+            "readOnly": false
           },
           "last_event_time": {
-            "description": "Время последнего события в чате",
+            "description": "Time of last event occurred in chat",
             "type": "integer",
             "format": "int64"
           },
           "participants_count": {
-            "description": "Количество участников чата. Для диалогов всегда `2`",
+            "description": "Number of people in chat. Always 2 for `dialog` chat type",
             "type": "integer",
             "format": "int32"
           },
           "owner_id": {
-            "description": "ID владельца чата",
+            "description": "Identifier of chat owner. Visible only for chat admins",
             "nullable": true,
-            "type": "integer",
-            "format": "int64",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/UserId"
+              }
+            ],
             "readOnly": false
           },
           "participants": {
-            "description": "Участники чата с временем последней активности. Может быть `null`, если запрашивается список чатов",
+            "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",
@@ -1813,22 +2214,23 @@
             }
           },
           "is_public": {
-            "description": "Доступен ли чат публично (для диалогов всегда `false`)",
+            "description": "Is current chat publicly available. Always `false` for dialogs",
             "type": "boolean"
           },
           "link": {
-            "description": "Ссылка на чат",
+            "description": "Link on chat",
             "type": "string",
             "readOnly": false,
             "nullable": true
           },
           "description": {
-            "description": "Описание чата",
+            "description": "Chat description",
             "type": "string",
-            "nullable": true
+            "nullable": true,
+            "readOnly": false
           },
           "dialog_with_user": {
-            "description": "Данные о пользователе в диалоге (только для чатов типа `\"dialog\"`)",
+            "description": "Another user in conversation. For `dialog` type chats only",
             "allOf": [
               {
                 "$ref": "#/components/schemas/UserWithPhoto"
@@ -1837,14 +2239,14 @@
             "nullable": true,
             "readOnly": false
           },
-          "chat_message_id": {
-            "description": "ID сообщения, содержащего кнопку, через которую был инициирован чат",
+          "messages_count": {
+            "description": "Messages count in chat. Only for group chats and channels. **Not available** for dialogs",
             "nullable": true,
             "readOnly": false,
-            "type": "string"
+            "type": "integer"
           },
           "pinned_message": {
-            "description": "Закреплённое сообщение в чате (возвращается только при запросе конкретного чата)",
+            "description": "Pinned message in chat or channel. Returned only when single chat is requested",
             "nullable": true,
             "readOnly": false,
             "allOf": [
@@ -1858,51 +2260,57 @@
           "chat_id",
           "type",
           "status",
-          "title",
           "last_event_time",
           "participants_count",
-          "icon",
-          "is_public",
-          "description"
+          "is_public"
         ]
       },
       "ChatType": {
-        "description": "Тип чата: диалог, чат",
+        "type": "string",
+        "description": "Type of chat. Dialog (one-on-one), chat or channel",
         "enum": [
-          "chat"
+          "dialog",
+          "chat",
+          "channel"
         ]
       },
       "ChatStatus": {
-        "description": "Статус чата для текущего бота",
+        "type": "string",
+        "description": "Chat status for current bot",
         "enum": [
           "active",
           "removed",
           "left",
-          "closed"
+          "closed",
+          "suspended"
         ]
       },
       "ChatList": {
+        "type": "object",
+        "description": "Paginated list of chats",
         "properties": {
           "chats": {
-            "description": "Список запрашиваемых чатов",
+            "description": "List of requested chats",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/Chat"
             }
           },
           "marker": {
-            "description": "Указатель на следующую страницу запрашиваемых чатов",
+            "description": "Reference to the next page of requested chats",
             "nullable": true,
             "type": "integer",
-            "format": "int64"
+            "format": "int64",
+            "readOnly": false
           }
         },
         "required": [
-          "chats",
-          "marker"
+          "chats"
         ]
       },
       "ChatPatch": {
+        "type": "object",
+        "description": "Patch object for updating chat info",
         "properties": {
           "icon": {
             "readOnly": false,
@@ -1920,14 +2328,21 @@
             "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": "ID сообщения для закрепления в чате. Чтобы удалить закреплённое сообщение, используйте метод [unpin](/docs-api/methods/DELETE/chats/%7BchatId%7D/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": "Если `true`, участники получат системное уведомление об изменении",
+            "description": "By default, participants will be notified about change with system message in chat/channel",
             "type": "boolean",
             "default": true,
             "readOnly": false,
@@ -1936,7 +2351,8 @@
         }
       },
       "ChatMember": {
-        "description": "Объект, описывающий участника чата",
+        "type": "object",
+        "description": "Chat or channel member with membership info",
         "allOf": [
           {
             "$ref": "#/components/schemas/UserWithPhoto"
@@ -1944,82 +2360,48 @@
           {
             "properties": {
               "last_access_time": {
-                "description": "Время последней активности пользователя в чате. Может быть устаревшим для суперчатов (равно времени вступления)",
+                "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",
-                "description": "Является ли пользователь владельцем чата"
+                "type": "boolean"
               },
               "is_admin": {
-                "type": "boolean",
-                "description": "Является ли пользователь администратором чата"
+                "type": "boolean"
               },
               "join_time": {
                 "type": "integer",
-                "format": "int64",
-                "description": "Дата присоединения к чату в формате Unix time"
+                "format": "int64"
               },
               "permissions": {
-                "description": "Перечень прав пользователя. Возможные значения:\n- `\"read_all_messages\"` — Читать все сообщения.\n- `\"add_remove_members\"` — Добавлять/удалять участников.\n- `\"add_admins\"` — Добавлять администраторов.\n- `\"change_chat_info\"` — Изменять информацию о чате.\n- `\"pin_message\"` — Закреплять сообщения.\n- `\"write\"` — Писать сообщения.\n- `\"edit_link\"` — Изменять ссылку на чат.\n",
+                "description": "Permissions in chat if member is admin. `null` otherwise",
                 "type": "array",
                 "uniqueItems": true,
                 "nullable": true,
                 "items": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ChatAdminPermission"
-                    }
-                  ]
-                }
+                  "$ref": "#/components/schemas/ChatAdminPermission"
+                },
+                "readOnly": false
               },
               "alias": {
-                "description": "Заголовок, который будет показан на клиенте\n\nЕсли пользователь администратор или владелец и ему не установлено это название, то поле не передаётся, клиенты на своей стороне подменят на \"владелец\" или \"админ\"",
-                "type": "string"
+                "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",
-              "permissions",
               "join_time"
             ]
           }
         ]
       },
-      "ChatAdmin": {
-        "properties": {
-          "user_id": {
-            "description": "Идентификатор администратора с правами доступа",
-            "type": "integer",
-            "format": "int64"
-          },
-          "permissions": {
-            "description": "Перечень прав пользователя. Возможные значения:\n- `\"read_all_messages\"` — Читать все сообщения.\n- `\"add_remove_members\"` — Добавлять/удалять участников.\n- `\"add_admins\"` — Добавлять администраторов.\n- `\"change_chat_info\"` — Изменять информацию о чате.\n- `\"pin_message\"` — Закреплять сообщения.\n- `\"write\"` — Писать сообщения.\n",
-            "type": "array",
-            "uniqueItems": true,
-            "items": {
-              "allOf": [
-                {
-                  "$ref": "#/components/schemas/ChatAdminPermission"
-                }
-              ]
-            }
-          },
-          "alias": {
-            "description": "Заголовок, который будет показан на клиенте\n\nЕсли пользователь администратор или владелец и ему не установлено это название, то поле не передаётся, клиенты на своей стороне подменят на \"владелец\" или \"админ\"",
-            "type": "string"
-          }
-        },
-        "required": [
-          "user_id",
-          "permissions"
-        ]
-      },
       "ChatAdminPermission": {
-        "description": "Права администратора чата",
+        "description": "Chat admin permissions",
         "type": "string",
         "enum": [
           "read_all_messages",
@@ -2027,21 +2409,27 @@
           "add_admins",
           "change_chat_info",
           "pin_message",
+          "edit_link",
           "write",
-          "edit_link"
+          "edit",
+          "delete",
+          "can_call",
+          "view_stats"
         ]
       },
       "ChatMembersList": {
+        "type": "object",
+        "description": "Paginated list of chat members",
         "properties": {
           "members": {
-            "description": "Список участников чата с информацией о времени последней активности",
+            "description": "Participants in chat with time of last activity",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/ChatMember"
             }
           },
           "marker": {
-            "description": "Указатель на следующую страницу данных",
+            "description": "Pointer to the next data page",
             "type": "integer",
             "format": "int64",
             "nullable": true,
@@ -2052,32 +2440,12 @@
           "members"
         ]
       },
-      "ChatAdminsList": {
-        "properties": {
-          "admins": {
-            "description": "Массив администраторов чата",
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/ChatAdmin"
-            }
-          },
-          "marker": {
-            "description": "Указатель на следующую страницу данных",
-            "type": "integer",
-            "format": "int64",
-            "nullable": true,
-            "readOnly": false
-          }
-        },
-        "required": [
-          "admins"
-        ]
-      },
       "Image": {
-        "description": "Общая схема, описывающая объект изображения",
+        "type": "object",
+        "description": "Generic schema describing image object",
         "properties": {
           "url": {
-            "description": "URL изображения",
+            "description": "URL of image",
             "type": "string"
           }
         },
@@ -2086,19 +2454,20 @@
         ]
       },
       "Subscription": {
-        "description": "Схема для описания подписки на WebHook",
+        "type": "object",
+        "description": "Schema to describe WebHook subscription",
         "properties": {
           "url": {
-            "description": "URL вебхука",
+            "description": "Webhook URL",
             "type": "string"
           },
           "time": {
-            "description": "Unix-время, когда была создана подписка",
+            "description": "Unix-time when subscription was created",
             "type": "integer",
             "format": "int64"
           },
           "update_types": {
-            "description": "Типы обновлений, на которые подписан бот",
+            "description": "Update types bot subscribed for",
             "example": "[\"message_created\", \"bot_started\"]",
             "type": "array",
             "nullable": true,
@@ -2106,27 +2475,31 @@
             "items": {
               "type": "string",
               "minLength": 1
-            }
+            },
+            "readOnly": false
           }
         },
         "required": [
           "url",
-          "time",
-          "update_types",
-          "version"
+          "time"
         ]
       },
       "Recipient": {
-        "description": "Новый получатель сообщения. Может быть пользователем или чатом",
+        "type": "object",
+        "description": "New message recipient. Could be user, chat or channel",
         "properties": {
           "chat_id": {
-            "description": "ID чата",
-            "type": "integer",
-            "format": "int64",
-            "nullable": true
+            "description": "Chat or channel identifier",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ChatId"
+              }
+            ],
+            "nullable": true,
+            "readOnly": false
           },
           "chat_type": {
-            "description": "Тип чата",
+            "description": "Chat type",
             "allOf": [
               {
                 "$ref": "#/components/schemas/ChatType"
@@ -2134,32 +2507,46 @@
             ]
           },
           "user_id": {
-            "description": "ID пользователя, если сообщение было отправлено пользователю",
-            "type": "integer",
-            "format": "int64",
-            "nullable": true
+            "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_id",
-          "chat_type",
-          "user_id"
+          "chat_type"
         ]
       },
       "Message": {
-        "description": "Сообщение в чате",
+        "type": "object",
+        "description": "Message in chat",
         "properties": {
           "sender": {
-            "description": "Пользователь, отправивший сообщение",
+            "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
+            "readOnly": false,
+            "nullable": true
           },
           "recipient": {
-            "description": "Получатель сообщения. Может быть пользователем или чатом",
+            "description": "Message recipient. Could be user, chat or channel",
             "allOf": [
               {
                 "$ref": "#/components/schemas/Recipient"
@@ -2167,12 +2554,12 @@
             ]
           },
           "timestamp": {
-            "description": "Время создания сообщения в формате Unix-time",
+            "description": "Unix-time when message was created",
             "type": "integer",
             "format": "int64"
           },
           "link": {
-            "description": "Пересланное или ответное сообщение",
+            "description": "Forwarded or replied message",
             "nullable": true,
             "readOnly": false,
             "allOf": [
@@ -2182,7 +2569,7 @@
             ]
           },
           "body": {
-            "description": "Содержимое сообщения. Текст + вложения. Может быть `null`, если сообщение содержит только пересланное сообщение",
+            "description": "Body of created message. Text + attachments. Could be null if message contains only forwarded message",
             "allOf": [
               {
                 "$ref": "#/components/schemas/MessageBody"
@@ -2190,7 +2577,7 @@
             ]
           },
           "stat": {
-            "description": "Статистика сообщения.",
+            "description": "Message statistics. Available only for channels in getMessages method context",
             "allOf": [
               {
                 "$ref": "#/components/schemas/MessageStat"
@@ -2200,7 +2587,7 @@
             "readOnly": false
           },
           "url": {
-            "description": "Публичная ссылка на сообщение. Может быть null для диалогов или не публичных чатов",
+            "description": "Message public URL. Can be `null` for dialogs or non-public chats/channels",
             "type": "string",
             "nullable": true,
             "readOnly": false
@@ -2212,8 +2599,71 @@
           "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": {
-        "description": "Статистика сообщения",
+        "type": "object",
+        "description": "Message statistics",
         "properties": {
           "views": {
             "type": "integer"
@@ -2224,33 +2674,39 @@
         ]
       },
       "MessageBody": {
-        "description": "Схема, представляющая тело сообщения",
+        "description": "Schema representing body of message",
         "type": "object",
         "properties": {
           "mid": {
-            "description": "Уникальный ID сообщения",
-            "type": "string"
+            "description": "Unique identifier of message",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/MessageId"
+              }
+            ]
           },
           "seq": {
-            "description": "ID последовательности сообщения в чате",
+            "description": "Sequence identifier of message in chat",
             "type": "integer",
             "format": "int64"
           },
           "text": {
-            "description": "Новый текст сообщения",
+            "description": "Message text",
             "type": "string",
-            "nullable": true
+            "nullable": true,
+            "readOnly": false
           },
           "attachments": {
-            "description": "Вложения сообщения. Могут быть одним из типов `Attachment`. Смотрите описание схемы",
+            "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": "Разметка текста сообщения. Для подробной информации загляните в раздел [Форматирование](/docs-api#Форматирование%20текста)",
+            "description": "Message text markup. See formatting section in https://dev.max.ru/docs-api for more info",
             "type": "array",
             "nullable": true,
             "readOnly": false,
@@ -2261,17 +2717,53 @@
         },
         "required": [
           "mid",
-          "seq",
-          "text",
-          "attachments",
-          "link"
+          "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": {
-        "description": "Пагинированный список сообщений",
+        "type": "object",
+        "description": "Paginated list of messages",
         "properties": {
           "messages": {
-            "description": "Массив сообщений",
+            "description": "List of messages",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/Message"
@@ -2282,8 +2774,24 @@
           "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": "Формат текста сообщения",
+        "description": "Message text format",
         "type": "string",
         "enum": [
           "markdown",
@@ -2291,39 +2799,44 @@
         ]
       },
       "NewMessageBody": {
+        "type": "object",
+        "description": "Body of a new message to send",
         "properties": {
           "text": {
-            "description": "Новый текст сообщения",
+            "description": "Message text",
             "type": "string",
             "maxLength": 4000,
-            "nullable": true
+            "nullable": true,
+            "readOnly": false
           },
           "attachments": {
-            "description": "Вложения сообщения. Если пусто, все вложения будут удалены",
+            "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": "Ссылка на сообщение",
+            "description": "Link to Message",
             "type": "object",
             "nullable": true,
             "allOf": [
               {
                 "$ref": "#/components/schemas/NewMessageLink"
               }
-            ]
+            ],
+            "readOnly": false
           },
           "notify": {
-            "description": "Если false, участники чата не будут уведомлены (по умолчанию `true`)",
+            "description": "If false, chat participants would not be notified",
             "type": "boolean",
             "default": true,
             "readOnly": false
           },
           "format": {
-            "description": "Если установлен, текст сообщения будет форматирован данным способом. Для подробной информации загляните в раздел [Форматирование](/docs-api#Форматирование%20текста)",
+            "description": "If set, message text will be formatted according to given markup",
             "readOnly": false,
             "nullable": true,
             "allOf": [
@@ -2332,17 +2845,48 @@
               }
             ]
           }
-        },
-        "required": [
-          "text",
-          "attachments",
-          "link"
-        ]
+        }
+      },
+      "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": "Тип ссылки сообщения",
+            "description": "Type of message link",
             "nullable": false,
             "allOf": [
               {
@@ -2351,8 +2895,12 @@
             ]
           },
           "mid": {
-            "description": "ID сообщения исходного сообщения",
-            "type": "string",
+            "description": "Message identifier of original message",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/MessageId"
+              }
+            ],
             "nullable": false
           }
         },
@@ -2362,9 +2910,11 @@
         ]
       },
       "LinkedMessage": {
+        "type": "object",
+        "description": "Forwarded or replied message",
         "properties": {
           "type": {
-            "description": "Тип связанного сообщения",
+            "description": "Type of linked message",
             "allOf": [
               {
                 "$ref": "#/components/schemas/MessageLinkType"
@@ -2372,18 +2922,22 @@
             ]
           },
           "sender": {
-            "description": "Пользователь, отправивший сообщение.",
+            "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
+            "readOnly": false,
+            "nullable": true
           },
           "chat_id": {
-            "description": "Чат, в котором сообщение было изначально опубликовано. Только для пересланных сообщений",
-            "type": "integer",
-            "format": "int64",
+            "description": "Chat where message has been originally posted",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ChatId"
+              }
+            ],
             "readOnly": false
           },
           "message": {
@@ -2399,7 +2953,53 @@
           "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"
@@ -2409,8 +3009,21 @@
           "message"
         ]
       },
+      "SendCommentResult": {
+        "type": "object",
+        "description": "Result of sending a comment",
+        "properties": {
+          "message": {
+            "$ref": "#/components/schemas/CommentMessage"
+          }
+        },
+        "required": [
+          "message"
+        ]
+      },
       "Attachment": {
-        "description": "Общая схема, представляющая вложение сообщения",
+        "type": "object",
+        "description": "Generic schema representing message attachment",
         "discriminator": {
           "propertyName": "type",
           "mapping": {
@@ -2435,7 +3048,8 @@
         ]
       },
       "PhotoAttachment": {
-        "description": "Вложение изображения",
+        "type": "object",
+        "description": "Image attachment",
         "allOf": [
           {
             "$ref": "#/components/schemas/Attachment"
@@ -2443,12 +3057,7 @@
           {
             "properties": {
               "payload": {
-                "type": "object",
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/PhotoAttachmentPayload"
-                  }
-                ]
+                "$ref": "#/components/schemas/PhotoAttachmentPayload"
               }
             },
             "required": [
@@ -2458,9 +3067,11 @@
         ]
       },
       "PhotoAttachmentPayload": {
+        "type": "object",
+        "description": "Payload of photo attachment containing image metadata",
         "properties": {
           "photo_id": {
-            "description": "Уникальный ID этого изображения",
+            "description": "Unique identifier of this image",
             "type": "integer",
             "format": "int64"
           },
@@ -2469,7 +3080,7 @@
             "type": "string"
           },
           "url": {
-            "description": "URL изображения",
+            "description": "Image URL",
             "type": "string"
           }
         },
@@ -2480,6 +3091,8 @@
         ]
       },
       "VideoAttachment": {
+        "type": "object",
+        "description": "Video attachment",
         "allOf": [
           {
             "$ref": "#/components/schemas/Attachment"
@@ -2487,16 +3100,10 @@
           {
             "properties": {
               "payload": {
-                "type": "object",
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/MediaAttachmentPayload"
-                  }
-                ]
+                "$ref": "#/components/schemas/MediaAttachmentPayload"
               },
               "thumbnail": {
-                "description": "Миниатюра видео",
-                "type": "string",
+                "description": "Video thumbnail",
                 "nullable": true,
                 "readOnly": false,
                 "allOf": [
@@ -2506,19 +3113,19 @@
                 ]
               },
               "width": {
-                "description": "Ширина видео",
+                "description": "Video width",
                 "type": "integer",
                 "nullable": true,
                 "readOnly": false
               },
               "height": {
-                "description": "Высота видео",
+                "description": "Video height",
                 "type": "integer",
                 "nullable": true,
                 "readOnly": false
               },
               "duration": {
-                "description": "Длина видео в секундах",
+                "description": "Video duration in seconds",
                 "type": "integer",
                 "nullable": true,
                 "readOnly": false
@@ -2531,9 +3138,11 @@
         ]
       },
       "VideoThumbnail": {
+        "type": "object",
+        "description": "Video thumbnail image",
         "properties": {
           "url": {
-            "description": "URL изображения",
+            "description": "Image URL",
             "type": "string"
           }
         },
@@ -2542,45 +3151,47 @@
         ]
       },
       "VideoUrls": {
+        "type": "object",
+        "description": "Available video download and streaming URLs by resolution",
         "properties": {
           "mp4_1080": {
-            "description": "URL видео в разрешении 1080p, если доступно",
+            "description": "Video URL in 1080p resolution, if available",
             "type": "string",
             "nullable": true,
             "readOnly": false
           },
           "mp4_720": {
-            "description": "URL видео в разрешении 720p, если доступно",
+            "description": "Video URL in 720 resolution, if available",
             "type": "string",
             "nullable": true,
             "readOnly": false
           },
           "mp4_480": {
-            "description": "URL видео в разрешении 480p, если доступно",
+            "description": "Video URL in 480 resolution, if available",
             "type": "string",
             "nullable": true,
             "readOnly": false
           },
           "mp4_360": {
-            "description": "URL видео в разрешении 360p, если доступно",
+            "description": "Video URL in 360 resolution, if available",
             "type": "string",
             "nullable": true,
             "readOnly": false
           },
           "mp4_240": {
-            "description": "URL видео в разрешении 240p, если доступно",
+            "description": "Video URL in 240 resolution, if available",
             "type": "string",
             "nullable": true,
             "readOnly": false
           },
           "mp4_144": {
-            "description": "URL видео в разрешении 144p, если доступно",
+            "description": "Video URL in 144 resolution, if available",
             "type": "string",
             "nullable": true,
             "readOnly": false
           },
           "hls": {
-            "description": "URL трансляции, если доступна",
+            "description": "Live streaming URL, if available",
             "type": "string",
             "nullable": true,
             "readOnly": false
@@ -2588,13 +3199,15 @@
         }
       },
       "VideoAttachmentDetails": {
+        "type": "object",
+        "description": "Detailed information about video attachment including direct URLs",
         "properties": {
           "token": {
-            "description": "Токен видео-вложения",
+            "description": "Video attachment token",
             "type": "string"
           },
           "urls": {
-            "description": "URL-ы для скачивания или воспроизведения видео. Может быть null, если видео недоступно",
+            "description": "URLs to download or play video. Can be null if video is unavailable",
             "nullable": true,
             "readOnly": false,
             "allOf": [
@@ -2604,7 +3217,7 @@
             ]
           },
           "thumbnail": {
-            "description": "Миниатюра видео",
+            "description": "Video thumbnail",
             "nullable": true,
             "readOnly": false,
             "allOf": [
@@ -2614,15 +3227,15 @@
             ]
           },
           "width": {
-            "description": "Ширина видео",
+            "description": "Video width",
             "type": "integer"
           },
           "height": {
-            "description": "Высота видео",
+            "description": "Video height",
             "type": "integer"
           },
           "duration": {
-            "description": "Длина видео в секундах",
+            "description": "Video duration in seconds",
             "type": "integer"
           }
         },
@@ -2634,6 +3247,8 @@
         ]
       },
       "AudioAttachment": {
+        "type": "object",
+        "description": "Audio attachment",
         "allOf": [
           {
             "$ref": "#/components/schemas/Attachment"
@@ -2641,15 +3256,10 @@
           {
             "properties": {
               "payload": {
-                "type": "object",
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/MediaAttachmentPayload"
-                  }
-                ]
+                "$ref": "#/components/schemas/MediaAttachmentPayload"
               },
               "transcription": {
-                "description": "Аудио транскрипция",
+                "description": "Audio transcription",
                 "type": "string",
                 "nullable": true,
                 "readOnly": false
@@ -2662,6 +3272,8 @@
         ]
       },
       "FileAttachment": {
+        "type": "object",
+        "description": "File attachment",
         "allOf": [
           {
             "$ref": "#/components/schemas/Attachment"
@@ -2669,19 +3281,14 @@
           {
             "properties": {
               "payload": {
-                "type": "object",
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/FileAttachmentPayload"
-                  }
-                ]
+                "$ref": "#/components/schemas/FileAttachmentPayload"
               },
               "filename": {
-                "description": "Имя загруженного файла",
+                "description": "Uploaded file name",
                 "type": "string"
               },
               "size": {
-                "description": "Размер файла в байтах",
+                "description": "File size in bytes",
                 "type": "integer",
                 "format": "int64"
               }
@@ -2695,9 +3302,11 @@
         ]
       },
       "AttachmentPayload": {
+        "type": "object",
+        "description": "Base payload for message attachments containing media URL",
         "properties": {
           "url": {
-            "description": "URL медиа-вложения. Этот URL будет получен в объекте [Update](/docs-api/objects/Update) после отправки сообщения в чат.\n\nПрямую ссылку на видео также можно получить с помощью метода [`GET /videos/{-videoToken-}`](/docs-api/methods/GET/videos/-videoToken-)",
+            "description": "Media attachment URL.\nFor video attachments use getVideoAttachmentDetails method to obtain direct links.",
             "type": "string"
           }
         },
@@ -2706,6 +3315,8 @@
         ]
       },
       "MediaAttachmentPayload": {
+        "type": "object",
+        "description": "Payload for media (video/audio) attachments with reuse token",
         "allOf": [
           {
             "$ref": "#/components/schemas/AttachmentPayload"
@@ -2713,7 +3324,7 @@
           {
             "properties": {
               "token": {
-                "description": "Используйте `token`, если вы пытаетесь повторно использовать одно и то же вложение в другом сообщении.",
+                "description": "Use `token` in case when you are trying to reuse the same attachment in other message",
                 "type": "string"
               }
             },
@@ -2724,6 +3335,8 @@
         ]
       },
       "FileAttachmentPayload": {
+        "type": "object",
+        "description": "Payload for file attachments with reuse token",
         "allOf": [
           {
             "$ref": "#/components/schemas/AttachmentPayload"
@@ -2731,7 +3344,7 @@
           {
             "properties": {
               "token": {
-                "description": "Используйте `token`, если вы пытаетесь повторно использовать одно и то же вложение в другом сообщении.",
+                "description": "Use `token` in case when you are trying to reuse the same attachment in other message",
                 "type": "string"
               }
             },
@@ -2742,6 +3355,8 @@
         ]
       },
       "ContactAttachment": {
+        "type": "object",
+        "description": "Contact attachment",
         "allOf": [
           {
             "$ref": "#/components/schemas/Attachment"
@@ -2749,12 +3364,7 @@
           {
             "properties": {
               "payload": {
-                "type": "object",
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/ContactAttachmentPayload"
-                  }
-                ]
+                "$ref": "#/components/schemas/ContactAttachmentPayload"
               }
             },
             "required": [
@@ -2764,15 +3374,23 @@
         ]
       },
       "ContactAttachmentPayload": {
+        "type": "object",
+        "description": "Payload of contact attachment containing user contact info",
         "properties": {
           "vcf_info": {
-            "description": "Информация о пользователе в формате VCF.",
+            "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": "Информация о пользователе",
+            "description": "User info",
             "nullable": true,
             "readOnly": false,
             "allOf": [
@@ -2784,6 +3402,8 @@
         }
       },
       "StickerAttachmentPayload": {
+        "type": "object",
+        "description": "Payload of sticker attachment",
         "allOf": [
           {
             "$ref": "#/components/schemas/AttachmentPayload"
@@ -2791,7 +3411,7 @@
           {
             "properties": {
               "code": {
-                "description": "ID стикера",
+                "description": "Sticker identifier",
                 "type": "string"
               }
             },
@@ -2802,6 +3422,8 @@
         ]
       },
       "StickerAttachment": {
+        "type": "object",
+        "description": "Sticker attachment",
         "allOf": [
           {
             "$ref": "#/components/schemas/Attachment"
@@ -2809,19 +3431,14 @@
           {
             "properties": {
               "payload": {
-                "type": "object",
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/StickerAttachmentPayload"
-                  }
-                ]
+                "$ref": "#/components/schemas/StickerAttachmentPayload"
               },
               "width": {
-                "description": "Ширина стикера",
+                "description": "Sticker width",
                 "type": "integer"
               },
               "height": {
-                "description": "Высота стикера",
+                "description": "Sticker height",
                 "type": "integer"
               }
             },
@@ -2834,17 +3451,18 @@
         ]
       },
       "ShareAttachmentPayload": {
-        "description": "Полезная нагрузка запроса ShareAttachmentRequest",
+        "type": "object",
+        "description": "Payload of ShareAttachmentRequest",
         "properties": {
           "url": {
-            "description": "URL, прикрепленный к сообщению в качестве предпросмотра медиа",
+            "description": "URL attached to message as media preview",
             "minLength": 1,
             "type": "string",
             "nullable": true,
             "readOnly": false
           },
           "token": {
-            "description": "Токен вложения",
+            "description": "Attachment token",
             "type": "string",
             "nullable": true,
             "readOnly": false
@@ -2852,6 +3470,8 @@
         }
       },
       "ShareAttachment": {
+        "type": "object",
+        "description": "Link preview attachment with media",
         "allOf": [
           {
             "$ref": "#/components/schemas/Attachment"
@@ -2859,27 +3479,22 @@
           {
             "properties": {
               "payload": {
-                "type": "object",
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/ShareAttachmentPayload"
-                  }
-                ]
+                "$ref": "#/components/schemas/ShareAttachmentPayload"
               },
               "title": {
-                "description": "Заголовок предпросмотра ссылки.",
+                "description": "Link preview title",
                 "type": "string",
                 "readOnly": false,
                 "nullable": true
               },
               "description": {
-                "description": "Описание предпросмотра ссылки",
+                "description": "Link preview description",
                 "type": "string",
                 "readOnly": false,
                 "nullable": true
               },
               "image_url": {
-                "description": "Изображение предпросмотра ссылки",
+                "description": "Link preview image",
                 "type": "string",
                 "nullable": true,
                 "readOnly": false
@@ -2892,6 +3507,8 @@
         ]
       },
       "LocationAttachment": {
+        "type": "object",
+        "description": "Geographic location attachment",
         "allOf": [
           {
             "$ref": "#/components/schemas/Attachment"
@@ -2900,13 +3517,11 @@
             "properties": {
               "latitude": {
                 "type": "number",
-                "format": "double",
-                "description": "Широта"
+                "format": "double"
               },
               "longitude": {
                 "type": "number",
-                "format": "double",
-                "description": "Долгота"
+                "format": "double"
               }
             },
             "required": [
@@ -2917,7 +3532,8 @@
         ]
       },
       "InlineKeyboardAttachment": {
-        "description": "Кнопки в сообщении",
+        "type": "object",
+        "description": "Buttons in messages",
         "allOf": [
           {
             "$ref": "#/components/schemas/Attachment"
@@ -2925,12 +3541,7 @@
           {
             "properties": {
               "payload": {
-                "type": "object",
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/Keyboard"
-                  }
-                ]
+                "$ref": "#/components/schemas/Keyboard"
               }
             },
             "required": [
@@ -2939,50 +3550,9 @@
           }
         ]
       },
-      "ReplyKeyboardAttachment": {
-        "description": "Custom reply keyboard in message",
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/Attachment"
-          },
-          {
-            "properties": {
-              "buttons": {
-                "type": "array",
-                "items": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/ReplyButton"
-                  }
-                }
-              }
-            },
-            "required": [
-              "buttons"
-            ]
-          }
-        ]
-      },
-      "DataAttachment": {
-        "description": "Attachment contains payload sent through `SendMessageButton`",
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/Attachment"
-          },
-          {
-            "properties": {
-              "data": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "data"
-            ]
-          }
-        ]
-      },
       "Keyboard": {
-        "description": "Клавиатура - это двумерный массив кнопок",
+        "type": "object",
+        "description": "Keyboard is two-dimension array of buttons",
         "properties": {
           "buttons": {
             "type": "array",
@@ -2999,12 +3569,14 @@
         ]
       },
       "Button": {
+        "type": "object",
+        "description": "Inline keyboard button",
         "properties": {
           "type": {
             "type": "string"
           },
           "text": {
-            "description": "Видимый текст кнопки",
+            "description": "Visible text of button",
             "type": "string",
             "minLength": 1,
             "maxLength": 128
@@ -3017,8 +3589,9 @@
             "link": "#/components/schemas/LinkButton",
             "request_geo_location": "#/components/schemas/RequestGeoLocationButton",
             "request_contact": "#/components/schemas/RequestContactButton",
+            "message": "#/components/schemas/MessageButton",
             "open_app": "#/components/schemas/OpenAppButton",
-            "message": "#/components/schemas/MessageButton"
+            "clipboard": "#/components/schemas/ClipboardButton"
           }
         },
         "required": [
@@ -3027,7 +3600,8 @@
         ]
       },
       "CallbackButton": {
-        "description": "После нажатия на такую кнопку клиент отправляет на сервер полезную нагрузку, которая содержит",
+        "type": "object",
+        "description": "After pressing this type of button client sends to server payload it contains",
         "allOf": [
           {
             "$ref": "#/components/schemas/Button"
@@ -3035,19 +3609,9 @@
           {
             "properties": {
               "payload": {
-                "description": "Токен кнопки",
+                "description": "Button payload",
                 "type": "string",
                 "maxLength": 1024
-              },
-              "intent": {
-                "description": "Намерение кнопки. Влияет на отображение клиентом.",
-                "readOnly": false,
-                "default": "default",
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/Intent"
-                  }
-                ]
               }
             },
             "required": [
@@ -3057,7 +3621,8 @@
         ]
       },
       "LinkButton": {
-        "description": "После нажатия на такую кнопку пользователь переходит по ссылке, которую она содержит",
+        "type": "object",
+        "description": "After pressing this type of button user follows the link it contains",
         "allOf": [
           {
             "$ref": "#/components/schemas/Button"
@@ -3075,8 +3640,18 @@
           }
         ]
       },
+      "MessageButton": {
+        "type": "object",
+        "description": "After pressing this type of button it sends message from user in chat",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/Button"
+          }
+        ]
+      },
       "RequestContactButton": {
-        "description": "AПосле нажатия на такую кнопку клиент отправляет новое сообщение с вложением текущего контакта пользователя",
+        "type": "object",
+        "description": "After pressing this type of button client sends new message with attachment of current user contact",
         "allOf": [
           {
             "$ref": "#/components/schemas/Button"
@@ -3084,7 +3659,8 @@
         ]
       },
       "RequestGeoLocationButton": {
-        "description": "После нажатия на такую кнопку клиент отправляет новое сообщение с вложением текущего географического положения пользователя",
+        "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"
@@ -3092,7 +3668,7 @@
           {
             "properties": {
               "quick": {
-                "description": "Если *true*, отправляет местоположение без запроса подтверждения пользователя",
+                "description": "If *true*, sends location without asking user's confirmation",
                 "readOnly": false,
                 "type": "boolean",
                 "default": false
@@ -3101,181 +3677,67 @@
           }
         ]
       },
-      "ChatButton": {
-        "description": "Кнопка, которая создает новый чат, как только первый пользователь на нее нажмёт.\nBБот будет добавлен в участники чата как администратор.\nMАвтор сообщения станет владельцем чата.",
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/Button"
-          },
-          {
-            "properties": {
-              "chat_title": {
-                "description": "Название чата, который будет создан",
-                "type": "string",
-                "maxLength": 200
-              },
-              "chat_description": {
-                "description": "Описание чата",
-                "readOnly": false,
-                "nullable": true,
-                "type": "string",
-                "maxLength": 400
-              },
-              "start_payload": {
-                "description": "Стартовая полезная нагрузка будет отправлена боту, как только чат будет создан",
-                "readOnly": false,
-                "nullable": true,
-                "type": "string",
-                "maxLength": 512
-              },
-              "uuid": {
-                "description": "Уникальный ID кнопки среди всех кнопок чата на клавиатуре.\nЕсли `uuid` изменён, новый чат будет создан при следующем нажатии.\nСервер сгенерирует его в момент, когда кнопка будет впервые размещена.\nИспользуйте его при редактировании сообщения.'",
-                "readOnly": false,
-                "nullable": true,
-                "type": "integer"
-              }
-            },
-            "required": [
-              "chat_title"
-            ]
-          }
-        ]
-      },
       "OpenAppButton": {
-        "description": "Кнопка для запуска мини-приложения",
+        "type": "object",
+        "description": "After pressing this type of button client opens mini app",
         "allOf": [
           {
             "$ref": "#/components/schemas/Button"
           },
           {
             "properties": {
-              "web_app": {
-                "description": "Публичное имя (username) бота или ссылка на него, чьё мини-приложение надо запустить",
+              "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": "Идентификатор бота, чьё мини-приложение надо запустить",
+                "description": "Unique identifier of the bot wired to the mini app",
+                "nullable": true,
                 "readOnly": false,
-                "type": "integer",
-                "format": "int64"
-              },
-              "payload": {
-                "description": "Параметр запуска, который будет передан в [initData](/docs/webapps/bridge#WebAppData) мини-приложения",
-                "readOnly": false,
-                "type": "string"
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/UserId"
+                  }
+                ]
               }
-            }
+            },
+            "required": [
+              "web_app"
+            ]
           }
         ]
       },
-      "MessageButton": {
-        "description": "Кнопка для запуска мини-приложения",
+      "ClipboardButton": {
+        "type": "object",
+        "description": "After pressing this type of button client copies payload data to clipboard",
         "allOf": [
           {
             "$ref": "#/components/schemas/Button"
           },
           {
             "properties": {
-              "text": {
-                "minLength": 1,
-                "maxLength": 128,
-                "description": "Текст кнопки, который будет отправлен в чат от лица пользователя",
-                "readOnly": false,
-                "type": "string"
+              "payload": {
+                "description": "Button payload",
+                "type": "string",
+                "maxLength": 1024
               }
-            }
-          }
-        ]
-      },
-      "Intent": {
-        "description": "Намерение кнопки",
-        "type": "string",
-        "enum": [
-          "positive",
-          "negative",
-          "default"
-        ]
-      },
-      "ReplyButton": {
-        "description": "After pressing this type of button client will send a message on behalf of user with given payload",
-        "properties": {
-          "text": {
-            "description": "Видимый текст кнопки",
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 128
-          },
-          "payload": {
-            "description": "Токен кнопки",
-            "type": "string",
-            "maxLength": 1024,
-            "readOnly": false,
-            "nullable": true
-          }
-        },
-        "discriminator": {
-          "propertyName": "type",
-          "mapping": {
-            "message": "#/components/schemas/SendMessageButton",
-            "user_geo_location": "#/components/schemas/SendGeoLocationButton",
-            "user_contact": "#/components/schemas/SendContactButton"
-          }
-        },
-        "required": [
-          "text"
-        ]
-      },
-      "SendMessageButton": {
-        "description": "After pressing this type of button client will send a message on behalf of user with given payload",
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/ReplyButton"
-          },
-          {
-            "properties": {
-              "intent": {
-                "description": "Намерение кнопки. Влияет на отображение клиентом.",
-                "readOnly": false,
-                "default": "default",
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/Intent"
-                  }
-                ]
-              }
-            }
-          }
-        ]
-      },
-      "SendGeoLocationButton": {
-        "description": "После нажатия на такую кнопку клиент отправляет новое сообщение с вложением текущего географического положения пользователя",
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/ReplyButton"
-          },
-          {
-            "properties": {
-              "quick": {
-                "description": "Если *true*, отправляет местоположение без запроса подтверждения пользователя",
-                "readOnly": false,
-                "type": "boolean",
-                "default": false
-              }
-            }
-          }
-        ]
-      },
-      "SendContactButton": {
-        "description": "AПосле нажатия на такую кнопку клиент отправляет новое сообщение с вложением текущего контакта пользователя",
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/ReplyButton"
+            },
+            "required": [
+              "payload"
+            ]
           }
         ]
       },
       "MessageLinkType": {
-        "description": "Тип связанного сообщения",
+        "description": "Type of linked message",
         "type": "string",
         "enum": [
           "forward",
@@ -3283,7 +3745,8 @@
         ]
       },
       "AttachmentRequest": {
-        "description": "Запрос на прикрепление данных к сообщению",
+        "type": "object",
+        "description": "Request to attach some data to message",
         "discriminator": {
           "propertyName": "type",
           "mapping": {
@@ -3308,6 +3771,8 @@
         ]
       },
       "PhotoAttachmentRequest": {
+        "type": "object",
+        "description": "Request to attach image to message",
         "allOf": [
           {
             "$ref": "#/components/schemas/AttachmentRequest"
@@ -3315,11 +3780,7 @@
           {
             "properties": {
               "payload": {
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/PhotoAttachmentRequestPayload"
-                  }
-                ]
+                "$ref": "#/components/schemas/PhotoAttachmentRequestPayload"
               }
             },
             "required": [
@@ -3329,23 +3790,24 @@
         ]
       },
       "PhotoAttachmentRequestPayload": {
-        "description": "Запрос на прикрепление изображения (все поля являются взаимоисключающими)",
+        "type": "object",
+        "description": "Request to attach image. All fields are mutually exclusive",
         "properties": {
           "url": {
-            "description": "Любой внешний URL изображения, которое вы хотите прикрепить",
+            "description": "Any external image URL you want to attach",
             "minLength": 1,
             "nullable": true,
             "readOnly": false,
             "type": "string"
           },
           "token": {
-            "description": "Токен существующего вложения",
+            "description": "Token of any existing attachment",
             "nullable": true,
             "readOnly": false,
             "type": "string"
           },
           "photos": {
-            "description": "Токены, полученные после загрузки изображений",
+            "description": "Tokens were obtained after uploading images",
             "nullable": true,
             "readOnly": false,
             "type": "object",
@@ -3356,9 +3818,11 @@
         }
       },
       "PhotoToken": {
+        "type": "object",
+        "description": "Token representing an uploaded image",
         "properties": {
           "token": {
-            "description": "Закодированная информация загруженного изображения",
+            "description": "Encoded information of uploaded image",
             "type": "string"
           }
         },
@@ -3366,22 +3830,9 @@
           "token"
         ]
       },
-      "PhotoTokens": {
-        "description": "Это информация, которую вы получите, как только изображение будет загружено",
-        "properties": {
-          "photos": {
-            "type": "object",
-            "additionalProperties": {
-              "$ref": "#/components/schemas/PhotoToken"
-            }
-          }
-        },
-        "required": [
-          "photos"
-        ]
-      },
       "VideoAttachmentRequest": {
-        "description": "Запрос на прикрепление видео к сообщению",
+        "type": "object",
+        "description": "Request to attach video to message",
         "allOf": [
           {
             "$ref": "#/components/schemas/AttachmentRequest"
@@ -3389,11 +3840,7 @@
           {
             "properties": {
               "payload": {
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/UploadedInfo"
-                  }
-                ]
+                "$ref": "#/components/schemas/UploadedInfo"
               }
             },
             "required": [
@@ -3403,7 +3850,8 @@
         ]
       },
       "AudioAttachmentRequest": {
-        "description": "Запрос на прикрепление аудио к сообщению. ДОЛЖЕН быть единственным вложением в сообщении",
+        "type": "object",
+        "description": "Request to attach audio to message. MUST be the only attachment in message",
         "allOf": [
           {
             "$ref": "#/components/schemas/AttachmentRequest"
@@ -3411,11 +3859,7 @@
           {
             "properties": {
               "payload": {
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/UploadedInfo"
-                  }
-                ]
+                "$ref": "#/components/schemas/UploadedInfo"
               }
             },
             "required": [
@@ -3425,17 +3869,19 @@
         ]
       },
       "UploadedInfo": {
-        "description": "Это информация, которую вы получите, как только аудио/видео будет загружено",
+        "type": "object",
+        "description": "This is information you will receive as soon as audio/video is uploaded",
         "properties": {
           "token": {
-            "description": "Токен — уникальный ID загруженного медиафайла",
+            "description": "Token is unique uploaded media identifier",
             "type": "string",
             "readOnly": false
           }
         }
       },
       "FileAttachmentRequest": {
-        "description": "Запрос на прикрепление файла к сообщению. ДОЛЖЕН быть единственным вложением в сообщении",
+        "type": "object",
+        "description": "Request to attach file to message. MUST be the only attachment in message",
         "allOf": [
           {
             "$ref": "#/components/schemas/AttachmentRequest"
@@ -3443,11 +3889,7 @@
           {
             "properties": {
               "payload": {
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/UploadedInfo"
-                  }
-                ]
+                "$ref": "#/components/schemas/UploadedInfo"
               }
             },
             "required": [
@@ -3457,7 +3899,8 @@
         ]
       },
       "UploadType": {
-        "description": "Тип загружаемого файла",
+        "type": "string",
+        "description": "Type of file uploading",
         "enum": [
           "image",
           "video",
@@ -3466,7 +3909,8 @@
         ]
       },
       "ContactAttachmentRequest": {
-        "description": "Запрос на прикрепление карточки контакта к сообщению. MДОЛЖЕН быть единственным вложением в сообщении",
+        "type": "object",
+        "description": "Request to attach contact card to message. MUST be the only attachment in message",
         "allOf": [
           {
             "$ref": "#/components/schemas/AttachmentRequest"
@@ -3474,11 +3918,7 @@
           {
             "properties": {
               "payload": {
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/ContactAttachmentRequestPayload"
-                  }
-                ]
+                "$ref": "#/components/schemas/ContactAttachmentRequestPayload"
               }
             },
             "required": [
@@ -3488,38 +3928,42 @@
         ]
       },
       "ContactAttachmentRequestPayload": {
+        "type": "object",
+        "description": "Payload for contact attachment request",
         "properties": {
           "name": {
-            "description": "Имя контакта",
+            "description": "Contact name",
             "nullable": true,
-            "type": "string"
+            "type": "string",
+            "readOnly": false
           },
           "contact_id": {
-            "description": "ID контакта, если он зарегистирован в MAX",
+            "description": "Contact identifier if it is registered Max user",
             "nullable": true,
             "readOnly": false,
-            "type": "integer",
-            "format": "int64"
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/UserId"
+              }
+            ]
           },
           "vcf_info": {
-            "description": "Полная информация о контакте в формате VCF",
+            "description": "Full information about contact in VCF format",
             "nullable": true,
             "readOnly": false,
             "type": "string"
           },
           "vcf_phone": {
-            "description": "Телефон контакта в формате VCF",
+            "description": "Contact phone in VCF format",
             "readOnly": false,
             "nullable": true,
             "type": "string"
           }
-        },
-        "required": [
-          "name"
-        ]
+        }
       },
       "StickerAttachmentRequest": {
-        "description": "Запрос на прикрепление стикера. ДОЛЖЕН быть единственным вложением в сообщении",
+        "type": "object",
+        "description": "Request to attach sticker. MUST be the only attachment request in message",
         "allOf": [
           {
             "$ref": "#/components/schemas/AttachmentRequest"
@@ -3527,11 +3971,7 @@
           {
             "properties": {
               "payload": {
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/StickerAttachmentRequestPayload"
-                  }
-                ]
+                "$ref": "#/components/schemas/StickerAttachmentRequestPayload"
               }
             },
             "required": [
@@ -3541,9 +3981,11 @@
         ]
       },
       "StickerAttachmentRequestPayload": {
+        "type": "object",
+        "description": "Payload for sticker attachment request",
         "properties": {
           "code": {
-            "description": "Код стикера",
+            "description": "Sticker code",
             "type": "string"
           }
         },
@@ -3552,7 +3994,8 @@
         ]
       },
       "InlineKeyboardAttachmentRequest": {
-        "description": "Запрос на прикрепление клавиатуры к сообщению",
+        "type": "object",
+        "description": "Request to attach keyboard to message",
         "allOf": [
           {
             "$ref": "#/components/schemas/AttachmentRequest"
@@ -3560,12 +4003,7 @@
           {
             "properties": {
               "payload": {
-                "type": "object",
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/InlineKeyboardAttachmentRequestPayload"
-                  }
-                ]
+                "$ref": "#/components/schemas/InlineKeyboardAttachmentRequestPayload"
               }
             },
             "required": [
@@ -3575,11 +4013,13 @@
         ]
       },
       "InlineKeyboardAttachmentRequestPayload": {
+        "type": "object",
+        "description": "Payload for inline keyboard attachment request",
         "properties": {
           "buttons": {
-            "description": "Двумерный массив кнопок",
+            "description": "Two-dimensional array of buttons",
             "type": "array",
-            "minLength": 1,
+            "minItems": 1,
             "items": {
               "type": "array",
               "items": {
@@ -3592,47 +4032,9 @@
           "buttons"
         ]
       },
-      "ReplyKeyboardAttachmentRequest": {
-        "description": "Request to attach reply keyboard to message",
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/AttachmentRequest"
-          },
-          {
-            "properties": {
-              "direct": {
-                "description": "Applicable only for chats. If `true` keyboard will be shown only for user bot mentioned or replied",
-                "type": "boolean",
-                "default": false,
-                "readOnly": false
-              },
-              "direct_user_id": {
-                "description": "If set to `true`, reply keyboard will only be shown to this participant in chat",
-                "type": "integer",
-                "format": "int64",
-                "nullable": true,
-                "readOnly": false
-              },
-              "buttons": {
-                "description": "Двумерный массив кнопок",
-                "type": "array",
-                "minLength": 1,
-                "items": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/ReplyButton"
-                  }
-                }
-              }
-            },
-            "required": [
-              "buttons"
-            ]
-          }
-        ]
-      },
       "LocationAttachmentRequest": {
-        "description": "Запрос на прикрепление клавиатуры к сообщению",
+        "type": "object",
+        "description": "Request to attach geographic location to message",
         "allOf": [
           {
             "$ref": "#/components/schemas/AttachmentRequest"
@@ -3641,13 +4043,11 @@
             "properties": {
               "latitude": {
                 "type": "number",
-                "format": "double",
-                "description": "Широта"
+                "format": "double"
               },
               "longitude": {
                 "type": "number",
-                "format": "double",
-                "description": "Долгота"
+                "format": "double"
               }
             },
             "required": [
@@ -3658,7 +4058,8 @@
         ]
       },
       "ShareAttachmentRequest": {
-        "description": "Запрос на прикрепление предпросмотра медиафайла по внешнему URL",
+        "type": "object",
+        "description": "Request to attach media preview of any external URL",
         "allOf": [
           {
             "$ref": "#/components/schemas/AttachmentRequest"
@@ -3666,11 +4067,7 @@
           {
             "properties": {
               "payload": {
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/ShareAttachmentPayload"
-                  }
-                ]
+                "$ref": "#/components/schemas/ShareAttachmentPayload"
               }
             },
             "required": [
@@ -3680,18 +4077,20 @@
         ]
       },
       "MarkupElement": {
+        "type": "object",
+        "description": "Base type for text markup (formatting) elements",
         "properties": {
           "type": {
-            "description": "Тип элемента разметки. Может быть **жирный**,  *курсив*, ~зачеркнутый~, подчеркнутый, `моноширинный`, ссылка или упоминание пользователя",
+            "description": "Type of the markup element. Can be **strong**, *emphasized*, ~strikethrough~, ++underline++, `monospaced`, highlighted, link, quote, header or user_mention",
             "type": "string"
           },
           "from": {
-            "description": "Индекс начала элемента разметки в тексте. Нумерация с нуля",
+            "description": "Element start index (zero-based) in text",
             "type": "integer",
             "format": "int32"
           },
           "length": {
-            "description": "Длина элемента разметки",
+            "description": "Length of the markup element",
             "type": "integer",
             "format": "int32"
           }
@@ -3705,7 +4104,10 @@
             "link": "#/components/schemas/LinkMarkup",
             "strikethrough": "#/components/schemas/StrikethroughMarkup",
             "underline": "#/components/schemas/UnderlineMarkup",
-            "user_mention": "#/components/schemas/UserMentionMarkup"
+            "user_mention": "#/components/schemas/UserMentionMarkup",
+            "heading": "#/components/schemas/HeadingMarkup",
+            "highlighted": "#/components/schemas/HighlightedMarkup",
+            "quote": "#/components/schemas/QuoteMarkup"
           }
         },
         "required": [
@@ -3715,7 +4117,8 @@
         ]
       },
       "StrongMarkup": {
-        "description": "Представляет **жирный** текст",
+        "type": "object",
+        "description": "Represents **bold** in text",
         "allOf": [
           {
             "$ref": "#/components/schemas/MarkupElement"
@@ -3723,7 +4126,8 @@
         ]
       },
       "EmphasizedMarkup": {
-        "description": "Представляет *курсив*",
+        "type": "object",
+        "description": "Represents *italic* in text",
         "allOf": [
           {
             "$ref": "#/components/schemas/MarkupElement"
@@ -3731,7 +4135,8 @@
         ]
       },
       "MonospacedMarkup": {
-        "description": "Представляет `моноширинный` или блок ```код``` в тексте",
+        "type": "object",
+        "description": "Represents `monospaced` or ```code``` block in text",
         "allOf": [
           {
             "$ref": "#/components/schemas/MarkupElement"
@@ -3739,7 +4144,8 @@
         ]
       },
       "LinkMarkup": {
-        "description": "Представляет ссылку в тексте",
+        "type": "object",
+        "description": "Represents link in text",
         "allOf": [
           {
             "$ref": "#/components/schemas/MarkupElement"
@@ -3747,7 +4153,7 @@
           {
             "properties": {
               "url": {
-                "description": "URL ссылки",
+                "description": "Link's URL",
                 "type": "string",
                 "minLength": 1,
                 "maxLength": 2048
@@ -3760,7 +4166,8 @@
         ]
       },
       "StrikethroughMarkup": {
-        "description": "Представляет ~зачекрнутый~ текст",
+        "type": "object",
+        "description": "Represents ~strikethrough~ block in text",
         "allOf": [
           {
             "$ref": "#/components/schemas/MarkupElement"
@@ -3768,7 +4175,8 @@
         ]
       },
       "UnderlineMarkup": {
-        "description": "Представляет подчеркнутый текст",
+        "type": "object",
+        "description": "Represents ++underlined++ part of the text",
         "allOf": [
           {
             "$ref": "#/components/schemas/MarkupElement"
@@ -3776,7 +4184,8 @@
         ]
       },
       "HeadingMarkup": {
-        "description": "Представляет заголовок текста",
+        "type": "object",
+        "description": "Represents header part of the text",
         "allOf": [
           {
             "$ref": "#/components/schemas/MarkupElement"
@@ -3784,7 +4193,8 @@
         ]
       },
       "UserMentionMarkup": {
-        "description": "Представляет упоминание пользователя в тексте. Упоминание может быть как по имени пользователя, так и по ID, если у пользователя нет имени",
+        "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"
@@ -3792,15 +4202,18 @@
           {
             "properties": {
               "user_link": {
-                "description": "`@username` упомянутого пользователя",
+                "description": "`@username` of mentioned user",
                 "type": "string",
                 "nullable": true,
                 "readOnly": false
               },
               "user_id": {
-                "description": "ID упомянутого пользователя без имени",
-                "type": "integer",
-                "format": "int64",
+                "description": "Identifier of mentioned user without username",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/UserId"
+                  }
+                ],
                 "nullable": true,
                 "readOnly": false
               }
@@ -3809,7 +4222,17 @@
         ]
       },
       "HighlightedMarkup": {
-        "description": "Представляет выделенную часть текста",
+        "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"
@@ -3817,14 +4240,22 @@
         ]
       },
       "SubscriptionRequestBody": {
-        "description": "Запрос на настройку подписки WebHook",
+        "type": "object",
+        "description": "Request to set up WebHook subscription",
         "properties": {
           "url": {
-            "description": "URL HTTP(S)-эндпойнта вашего бота. Должен начинаться с `http(s)://`",
-            "type": "string"
+            "$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": "Список типов обновлений, которые ваш бот хочет получать. Для полного списка типов см. объект [Update](/docs-api/objects/Update)",
+            "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,
@@ -3832,13 +4263,6 @@
               "type": "string"
             },
             "readOnly": false
-          },
-          "secret": {
-            "description": "Cекрет, который должен быть отправлен в заголовке `X-Max-Bot-Api-Secret` в каждом запросе Webhook. Разрешены только символы `A-Z`, `a-z`, `0-9`, и дефис. Заголовок рекомендован, чтобы запрос поступал из установленного веб-узла",
-            "type": "string",
-            "minLength": 5,
-            "maxLength": 256,
-            "pattern": "^[a-zA-Z0-9_-]{5,256}$"
           }
         },
         "required": [
@@ -3846,10 +4270,11 @@
         ]
       },
       "GetSubscriptionsResult": {
-        "description": "Список всех WebHook подписок",
+        "type": "object",
+        "description": "List of all WebHook subscriptions",
         "properties": {
           "subscriptions": {
-            "description": "Список текущих подписок",
+            "description": "Current subscriptions",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/Subscription"
@@ -3861,14 +4286,15 @@
         ]
       },
       "SimpleQueryResult": {
-        "description": "Простой ответ на запрос",
+        "type": "object",
+        "description": "Simple response to request",
         "properties": {
           "success": {
-            "description": "`true`, если запрос был успешным, `false` в противном случае",
+            "description": "`true` if request was successful. `false` otherwise",
             "type": "boolean"
           },
           "message": {
-            "description": "Объяснительное сообщение, если результат не был успешным",
+            "description": "Explanatory message if the result is not successful",
             "type": "string",
             "readOnly": false
           }
@@ -3878,13 +4304,19 @@
         ]
       },
       "PinMessageBody": {
+        "type": "object",
+        "description": "Request body for pinning a message in chat",
         "properties": {
           "message_id": {
-            "description": "ID сообщения, которое нужно закрепить. Соответствует полю `Message.body.mid`",
-            "type": "string"
+            "description": "Identifier of message to be pinned in chat",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/MessageId"
+              }
+            ]
           },
           "notify": {
-            "description": "Если `true`, участники получат уведомление с системным сообщением о закреплении",
+            "description": "If `true`, participants will be notified with system message in chat/channel",
             "type": "boolean",
             "default": true,
             "readOnly": false,
@@ -3896,9 +4328,11 @@
         ]
       },
       "GetPinnedMessageResult": {
+        "type": "object",
+        "description": "Result of getting pinned message in chat",
         "properties": {
           "message": {
-            "description": "Закреплённое сообщение. Может быть `null`, если в чате нет закреплённого сообщения",
+            "description": "Pinned message. Can be `null` if no message pinned in chat",
             "readOnly": false,
             "nullable": true,
             "allOf": [
@@ -3910,24 +4344,25 @@
         }
       },
       "Callback": {
-        "description": "Объект, отправленный боту, когда пользователь нажимает кнопку",
+        "type": "object",
+        "description": "Object sent to bot when user presses button",
         "properties": {
           "timestamp": {
-            "description": "Unix-время, когда пользователь нажал кнопку",
+            "description": "Unix-time when user pressed the button",
             "type": "integer",
             "format": "int64"
           },
           "callback_id": {
-            "description": "Текущий ID клавиатуры",
+            "description": "Current keyboard identifier",
             "type": "string"
           },
           "payload": {
-            "description": "Токен кнопки",
+            "description": "Button payload",
             "type": "string",
             "readOnly": false
           },
           "user": {
-            "description": "Пользователь, нажавший на кнопку",
+            "description": "User pressed the button",
             "allOf": [
               {
                 "$ref": "#/components/schemas/User"
@@ -3942,10 +4377,11 @@
         ]
       },
       "CallbackAnswer": {
-        "description": "Отправьте этот объект, когда ваш бот хочет отреагировать на нажатие кнопки",
+        "type": "object",
+        "description": "Send this object when your bot wants to react to when a button is pressed",
         "properties": {
           "message": {
-            "description": "Заполните это, если хотите изменить текущее сообщение",
+            "description": "Fill this if you want to modify current message",
             "nullable": true,
             "readOnly": false,
             "allOf": [
@@ -3955,7 +4391,7 @@
             ]
           },
           "notification": {
-            "description": "Заполните это, если хотите просто отправить одноразовое уведомление пользователю",
+            "description": "Fill this if you just want to send one-time notification to user",
             "nullable": true,
             "readOnly": false,
             "type": "string"
@@ -3963,18 +4399,19 @@
         }
       },
       "Error": {
-        "description": "Сервер возвращает это, если возникло исключение при вашем запросе",
+        "type": "object",
+        "description": "Server returns this if there was an exception to your request",
         "properties": {
           "error": {
-            "description": "Ошибка",
+            "description": "Error",
             "type": "string"
           },
           "code": {
-            "description": "Код ошибки",
+            "description": "Error code",
             "type": "string"
           },
           "message": {
-            "description": "Читаемое описание ошибки",
+            "description": "Human-readable description",
             "type": "string"
           }
         },
@@ -3984,16 +4421,18 @@
         ]
       },
       "UploadEndpoint": {
-        "description": "Точка доступа, куда следует загружать ваши бинарные файлы",
+        "description": "Endpoint you should upload to your binaries",
         "type": "object",
         "properties": {
           "url": {
-            "description": "URL для загрузки файла",
+            "description": "URL to upload",
             "type": "string"
           },
           "token": {
-            "description": "Видео- или аудио-токен для отправки сообщения",
-            "type": "string"
+            "description": "Video or audio token for send message",
+            "type": "string",
+            "readOnly": false,
+            "nullable": true
           }
         },
         "required": [
@@ -4001,20 +4440,14 @@
         ]
       },
       "UserIdsList": {
+        "type": "object",
+        "description": "List of user identifiers",
         "properties": {
           "user_ids": {
-            "name": "user_ids",
-            "description": "Массив ID пользователей для добавления в чат",
-            "required": true,
-            "schema": {
-              "type": "array",
-              "uniqueItems": true,
-              "items": {
-                "type": "integer",
-                "format": "int64"
-              }
+            "items": {
+              "$ref": "#/components/schemas/UserId"
             },
-            "style": "simple"
+            "maxItems": 100
           }
         },
         "required": [
@@ -4022,6 +4455,8 @@
         ]
       },
       "ActionRequestBody": {
+        "type": "object",
+        "description": "Request body for sending action to chat",
         "properties": {
           "action": {
             "$ref": "#/components/schemas/SenderAction"
@@ -4031,8 +4466,50 @@
           "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": {
-        "description": "Действие, отправляемое участникам чата. Возможные значения:\n- `\"typing_on\"` — Бот набирает сообщение.\n- `\"sending_photo\"` — Бот отправляет фото.\n- `\"sending_video\"` — Бот отправляет видео.\n- `\"sending_audio\"` — Бот отправляет аудиофайл.\n-  `\"sending_file\"` — Бот отправляет файл.\n- `\"mark_seen\"` — Бот помечает сообщения как прочитанные.\n",
+        "type": "string",
+        "description": "Different actions to send to chat members",
         "enum": [
           "typing_on",
           "sending_photo",
@@ -4043,29 +4520,31 @@
         ]
       },
       "UpdateList": {
-        "description": "Список всех обновлений в чатах, в которых ваш бот участвовал",
+        "type": "object",
+        "description": "List of all updates in chats your bot participated in",
         "properties": {
           "updates": {
-            "description": "Страница обновлений",
+            "description": "Page of updates",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/Update"
             }
           },
           "marker": {
-            "description": "Указатель на следующую страницу данных",
+            "description": "Pointer to the next data page",
             "type": "integer",
             "format": "int64",
-            "nullable": true
+            "nullable": true,
+            "readOnly": false
           }
         },
         "required": [
-          "updates",
-          "marker"
+          "updates"
         ]
       },
       "Update": {
-        "description": "Объект`Update` представляет различные типы событий, произошедших в чате. См. его наследников",
+        "type": "object",
+        "description": "`Update` object represents different types of events that happened in chat. See its inheritors",
         "discriminator": {
           "propertyName": "update_type",
           "mapping": {
@@ -4073,18 +4552,21 @@
             "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",
-            "dialog_muted": "#/components/schemas/DialogMutedUpdate",
-            "dialog_unmuted": "#/components/schemas/DialogUnmutedUpdate",
-            "dialog_cleared": "#/components/schemas/DialogClearedUpdate",
-            "dialog_removed": "#/components/schemas/DialogRemovedUpdate",
             "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",
-            "message_chat_created": "#/components/schemas/MessageChatCreatedUpdate"
+            "bot_admin_permissions_changed": "#/components/schemas/BotAdminPermissionsChangedUpdate"
           }
         },
         "properties": {
@@ -4092,7 +4574,7 @@
             "type": "string"
           },
           "timestamp": {
-            "description": "Unix-время, когда произошло событие",
+            "description": "Unix-time when event has occurred",
             "type": "integer",
             "format": "int64"
           }
@@ -4103,7 +4585,8 @@
         ]
       },
       "MessageCallbackUpdate": {
-        "description": "Вы получите этот `update` как только пользователь нажмёт кнопку",
+        "type": "object",
+        "description": "You will get this `update` as soon as user presses button",
         "allOf": [
           {
             "$ref": "#/components/schemas/Update"
@@ -4119,30 +4602,31 @@
                 ]
               },
               "message": {
-                "description": "Изначальное сообщение, содержащее встроенную клавиатуру. Может быть `null`, если оно было удалено к моменту, когда бот получил это обновление",
+                "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": "Текущий язык пользователя в формате IETF BCP 47",
+                "description": "Current user locale in IETF BCP 47 format",
                 "type": "string",
                 "nullable": true,
                 "readOnly": false
               }
             },
             "required": [
-              "callback",
-              "message"
+              "callback"
             ]
           }
         ]
       },
       "MessageCreatedUpdate": {
-        "description": "ы получите этот `update`, как только сообщение будет создано",
+        "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"
@@ -4150,7 +4634,7 @@
           {
             "properties": {
               "message": {
-                "description": "Новое созданное сообщение",
+                "description": "Newly created message",
                 "allOf": [
                   {
                     "$ref": "#/components/schemas/Message"
@@ -4158,7 +4642,7 @@
                 ]
               },
               "user_locale": {
-                "description": "Текущий язык пользователя в формате IETF BCP 47. Доступно только в диалогах",
+                "description": "Current user locale in IETF BCP 47 format. Available only in dialogs",
                 "type": "string",
                 "readOnly": false,
                 "nullable": true
@@ -4171,7 +4655,8 @@
         ]
       },
       "MessageRemovedUpdate": {
-        "description": "Вы получите этот `update`, как только сообщение будет удалено",
+        "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"
@@ -4179,18 +4664,28 @@
           {
             "properties": {
               "message_id": {
-                "description": "ID удаленного сообщения",
-                "type": "string"
+                "description": "Identifier of removed message",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/MessageId"
+                  }
+                ]
               },
               "chat_id": {
-                "description": "ID чата, где сообщение было удалено",
-                "type": "integer",
-                "format": "int64"
+                "description": "Chat identifier where message has been deleted",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/ChatId"
+                  }
+                ]
               },
               "user_id": {
-                "description": "Пользователь, удаливший сообщение",
-                "type": "integer",
-                "format": "int64"
+                "description": "User who deleted this message",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/UserId"
+                  }
+                ]
               }
             },
             "required": [
@@ -4202,7 +4697,8 @@
         ]
       },
       "MessageEditedUpdate": {
-        "description": "Вы получите этот `update`, как только сообщение будет отредактировано",
+        "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"
@@ -4210,7 +4706,106 @@
           {
             "properties": {
               "message": {
-                "description": "Отредактированное сообщение",
+                "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"
@@ -4225,7 +4820,8 @@
         ]
       },
       "BotAddedToChatUpdate": {
-        "description": "Вы получите этот update, как только бот будет добавлен в чат",
+        "type": "object",
+        "description": "You will receive this update when bot has been added to chat",
         "allOf": [
           {
             "$ref": "#/components/schemas/Update"
@@ -4233,12 +4829,15 @@
           {
             "properties": {
               "chat_id": {
-                "description": "ID чата, куда был добавлен бот",
-                "type": "integer",
-                "format": "int64"
+                "description": "Chat id where bot was added",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/ChatId"
+                  }
+                ]
               },
               "user": {
-                "description": "Пользователь, добавивший бота в чат",
+                "description": "User who added bot to chat",
                 "allOf": [
                   {
                     "$ref": "#/components/schemas/User"
@@ -4246,7 +4845,7 @@
                 ]
               },
               "is_channel": {
-                "description": "Указывает, был ли бот добавлен в канал или нет",
+                "description": "Indicates whether bot has been added to channel or not",
                 "type": "boolean"
               }
             },
@@ -4259,7 +4858,8 @@
         ]
       },
       "BotRemovedFromChatUpdate": {
-        "description": "Вы получите этот update, как только бот будет удалён из чата",
+        "type": "object",
+        "description": "You will receive this update when bot has been removed from chat",
         "allOf": [
           {
             "$ref": "#/components/schemas/Update"
@@ -4267,12 +4867,15 @@
           {
             "properties": {
               "chat_id": {
-                "description": "ID чата, откуда был удалён бот",
-                "type": "integer",
-                "format": "int64"
+                "description": "Chat identifier bot removed from",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/ChatId"
+                  }
+                ]
               },
               "user": {
-                "description": "Пользователь, удаливший бота из чата",
+                "description": "User who removed bot from chat",
                 "allOf": [
                   {
                     "$ref": "#/components/schemas/User"
@@ -4280,7 +4883,7 @@
                 ]
               },
               "is_channel": {
-                "description": "Указывает, был ли бот удалён из канала или нет",
+                "description": "Indicates whether bot has been removed from channel or not",
                 "type": "boolean"
               }
             },
@@ -4292,146 +4895,9 @@
           }
         ]
       },
-      "DialogMutedUpdate": {
-        "description": "Вы получите этот update, когда пользователь заглушит диалог с ботом",
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/Update"
-          },
-          {
-            "properties": {
-              "chat_id": {
-                "description": "ID чата, где произошло событие",
-                "type": "integer",
-                "format": "int64"
-              },
-              "user": {
-                "description": "Пользователь, который отключил уведомления",
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/User"
-                  }
-                ]
-              },
-              "muted_until": {
-                "description": "Время в формате Unix, до наступления которого диалог был отключён",
-                "type": "integer",
-                "format": "int64"
-              },
-              "user_locale": {
-                "description": "Текущий язык пользователя в формате IETF BCP 47",
-                "type": "string"
-              }
-            },
-            "required": [
-              "chat_id",
-              "user",
-              "muted_until"
-            ]
-          }
-        ]
-      },
-      "DialogUnmutedUpdate": {
-        "description": "Вы получите этот update, когда пользователь включит уведомления в диалоге с ботом",
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/Update"
-          },
-          {
-            "properties": {
-              "chat_id": {
-                "description": "ID чата, где произошло событие",
-                "type": "integer",
-                "format": "int64"
-              },
-              "user": {
-                "description": "Пользователь, который включил уведомления",
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/User"
-                  }
-                ]
-              },
-              "user_locale": {
-                "description": "Текущий язык пользователя в формате IETF BCP 47",
-                "type": "string"
-              }
-            },
-            "required": [
-              "chat_id",
-              "user"
-            ]
-          }
-        ]
-      },
-      "DialogClearedUpdate": {
-        "description": "Бот получает этот тип обновления сразу после очистки истории диалога.",
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/Update"
-          },
-          {
-            "properties": {
-              "chat_id": {
-                "description": "ID чата, где произошло событие",
-                "type": "integer",
-                "format": "int64"
-              },
-              "user": {
-                "description": "Пользователь, который включил уведомления",
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/User"
-                  }
-                ]
-              },
-              "user_locale": {
-                "description": "Текущий язык пользователя в формате IETF BCP 47",
-                "type": "string"
-              }
-            },
-            "required": [
-              "chat_id",
-              "user"
-            ]
-          }
-        ]
-      },
-      "DialogRemovedUpdate": {
-        "description": "Вы получите этот update, когда пользователь удаляет чат",
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/Update"
-          },
-          {
-            "properties": {
-              "chat_id": {
-                "description": "ID чата, где произошло событие",
-                "type": "integer",
-                "format": "int64"
-              },
-              "user": {
-                "description": "Пользователь, который удалил чат",
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/User"
-                  }
-                ]
-              },
-              "user_locale": {
-                "description": "Текущий язык пользователя в формате IETF BCP 47",
-                "type": "string"
-              }
-            },
-            "required": [
-              "chat_id",
-              "user"
-            ]
-          }
-        ]
-      },
       "UserAddedToChatUpdate": {
-        "description": "Вы получите это обновление, когда пользователь будет добавлен в чат, где бот является администратором",
+        "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"
@@ -4439,12 +4905,15 @@
           {
             "properties": {
               "chat_id": {
-                "description": "ID чата, где произошло событие",
-                "type": "integer",
-                "format": "int64"
+                "description": "Chat identifier where event has occurred",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/ChatId"
+                  }
+                ]
               },
               "user": {
-                "description": "Пользователь, добавленный в чат",
+                "description": "User added to chat",
                 "allOf": [
                   {
                     "$ref": "#/components/schemas/User"
@@ -4452,14 +4921,17 @@
                 ]
               },
               "inviter_id": {
-                "description": "Пользователь, который добавил пользователя в чат. Может быть `null`, если пользователь присоединился к чату по ссылке",
-                "type": "integer",
-                "format": "int64",
+                "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": "Указывает, был ли пользователь добавлен в канал или нет",
+                "description": "Indicates whether user has been added to channel or not",
                 "type": "boolean"
               }
             },
@@ -4472,7 +4944,8 @@
         ]
       },
       "UserRemovedFromChatUpdate": {
-        "description": "Вы получите это обновление, когда пользователь будет удалён из чата, где бот является администратором",
+        "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"
@@ -4480,12 +4953,15 @@
           {
             "properties": {
               "chat_id": {
-                "description": "ID чата, где произошло событие",
-                "type": "integer",
-                "format": "int64"
+                "description": "Chat identifier where event has occurred",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/ChatId"
+                  }
+                ]
               },
               "user": {
-                "description": "Пользователь, удалённый из чата",
+                "description": "User removed from chat",
                 "allOf": [
                   {
                     "$ref": "#/components/schemas/User"
@@ -4493,13 +4969,16 @@
                 ]
               },
               "admin_id": {
-                "description": "Администратор, который удалил пользователя из чата. Может быть `null`, если пользователь покинул чат сам",
-                "type": "integer",
-                "format": "int64",
+                "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": "Указывает, был ли пользователь удалён из канала или нет",
+                "description": "Indicates whether user has been removed from channel or not",
                 "type": "boolean"
               }
             },
@@ -4512,7 +4991,8 @@
         ]
       },
       "BotStartedUpdate": {
-        "description": "Бот получает этот тип обновления, как только пользователь нажал кнопку `Start`",
+        "type": "object",
+        "description": "Bot gets this type of update as soon as user pressed `Start` button",
         "allOf": [
           {
             "$ref": "#/components/schemas/Update"
@@ -4520,12 +5000,15 @@
           {
             "properties": {
               "chat_id": {
-                "description": "ID диалога, где произошло событие",
-                "type": "integer",
-                "format": "int64"
+                "description": "Dialog identifier where event has occurred",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/ChatId"
+                  }
+                ]
               },
               "user": {
-                "description": "Пользователь, который нажал кнопку 'Start'",
+                "description": "User pressed the 'Start' button",
                 "allOf": [
                   {
                     "$ref": "#/components/schemas/User"
@@ -4533,14 +5016,14 @@
                 ]
               },
               "payload": {
-                "description": "Дополнительные данные из дип-линков, переданные при запуске бота",
+                "description": "Additional data from deep-link passed on bot startup",
                 "type": "string",
                 "maxLength": 512,
                 "nullable": true,
                 "readOnly": false
               },
               "user_locale": {
-                "description": "Текущий язык пользователя в формате IETF BCP 47",
+                "description": "Current user locale in IETF BCP 47 format",
                 "type": "string",
                 "readOnly": false
               }
@@ -4553,7 +5036,8 @@
         ]
       },
       "BotStoppedUpdate": {
-        "description": "Бот получает этот тип обновления, как только пользователь останавливает бота",
+        "type": "object",
+        "description": "Bot gets this type of update as soon as bot has been stopped",
         "allOf": [
           {
             "$ref": "#/components/schemas/Update"
@@ -4561,12 +5045,15 @@
           {
             "properties": {
               "chat_id": {
-                "description": "ID диалога, где произошло событие",
-                "type": "integer",
-                "format": "int64"
+                "description": "Dialog identifier where event has occurred",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/ChatId"
+                  }
+                ]
               },
               "user": {
-                "description": "Пользователь, который остановил чат",
+                "description": "User who stopped the bot",
                 "allOf": [
                   {
                     "$ref": "#/components/schemas/User"
@@ -4574,7 +5061,165 @@
                 ]
               },
               "user_locale": {
-                "description": "Текущий язык пользователя в формате IETF BCP 47",
+                "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
               }
@@ -4587,7 +5232,8 @@
         ]
       },
       "ChatTitleChangedUpdate": {
-        "description": "BБот получит это обновление, когда будет изменено название чата",
+        "type": "object",
+        "description": "Bot gets this type of update as soon as title has been changed in chat",
         "allOf": [
           {
             "$ref": "#/components/schemas/Update"
@@ -4595,12 +5241,15 @@
           {
             "properties": {
               "chat_id": {
-                "description": "ID чата, где произошло событие",
-                "type": "integer",
-                "format": "int64"
+                "description": "Chat identifier where event has occurred",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/ChatId"
+                  }
+                ]
               },
               "user": {
-                "description": "Пользователь, который изменил название",
+                "description": "User who changed title",
                 "allOf": [
                   {
                     "$ref": "#/components/schemas/User"
@@ -4608,7 +5257,7 @@
                 ]
               },
               "title": {
-                "description": "Новое название",
+                "description": "New title",
                 "type": "string"
               }
             },
@@ -4620,39 +5269,119 @@
           }
         ]
       },
-      "MessageChatCreatedUpdate": {
-        "description": "Бот получит это обновление, когда чат будет создан, как только первый пользователь нажмёт кнопку чата",
+      "BotAdminPermissionsChangedUpdate": {
+        "type": "object",
+        "description": "Bot will get this update when bot admin permissions changed",
         "allOf": [
           {
             "$ref": "#/components/schemas/Update"
           },
           {
             "properties": {
-              "chat": {
-                "description": "Созданный чат",
+              "chat_id": {
+                "description": "Chat identifier where event has occurred",
                 "allOf": [
                   {
-                    "$ref": "#/components/schemas/Chat"
+                    "$ref": "#/components/schemas/ChatId"
                   }
                 ]
               },
-              "message_id": {
-                "description": "ID сообщения, где была нажата кнопка",
-                "type": "string"
+              "user_id": {
+                "description": "User or bot who changed bot admin permissions",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/UserId"
+                  }
+                ]
               },
-              "start_payload": {
-                "description": "Полезная нагрузка от кнопки чата",
-                "type": "string",
+              "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": [
-              "message_id",
-              "chat"
+              "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"
+        ]
       }
     }
   }