MaxBotApi 1.0.15

.NET 10.0 This package targets .NET 10.0. The package is compatible with this framework or higher. 
dotnet add package MaxBotApi --version 1.0.15
                    


                    

                
NuGet\Install-Package MaxBotApi -Version 1.0.15
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="MaxBotApi" Version="1.0.15" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="MaxBotApi" Version="1.0.15" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="MaxBotApi" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add MaxBotApi --version 1.0.15
                    


                    

                
#r "nuget: MaxBotApi, 1.0.15"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package MaxBotApi@1.0.15
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=MaxBotApi&version=1.0.15
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=MaxBotApi&version=1.0.15
                    


                            Install as a Cake Tool

.NET Client for Max Bot API

Используется net10 C#14, построено для работы через webhook.

Для разработки использовалась следующая документация https://dev.max.ru/docs-api

Доступно в nuget:

https://www.nuget.org/packages/MaxBotApi

<details> <summary>Установка</summary>

установка через .NET CLi
dotnet add package MaxBotApi
установка через NuGet package manager
Install-Package MaxBotApi

</details>

Реализованы методы API

bots

метод описание
✔ GET /me Получение информации о боте
✔ PATCH /me Изменение информации о боте

messages

метод описание
✔ GET /messages Получение сообщений
✔ POST /messages Отправить сообщение
✔ PUT /messages Редактирование сообщения
✔ DELETE /messages Удалить сообщение
✔ GET /messages/{messageId} Получить сообщение
✔ GET /videos/{videoToken} Получить информацию о видео
✔ POST /answers Ответ на Callback

chats

метод описание
✔ GET /chats Получение списка всех групповых чатов
✔ GET /chats/{chatId} Получение информации о групповом чате
✔ PATCH /chats/{chatId} Изменение информации о групповом чате
✔ DELETE /chats/{chatId} Удаление группового чата
✔ POST /chats/{chatId}/actions Отправка действия в групповой чат
✔ GET /chats/{chatId}/pin Получение закрепленного сообщения в групповом чате
✔ PUT /chats/{chatId}/pin Закрепление сообщения в групповом чате
✔ DELETE /chats/{chatId}/pin Удаление закрепленного сообщения в групповом чате
✔ GET /chats/{chatId}/members/me Получение информации о членстве бота в групповом чате
✔ DELETE /chats/{chatId}/members/me Удаление бота из группового чата
✔ GET /chats/{chatId}/members/admins Получение списка администраторов группового чата
✔ POST /chats/{chatId}/members/admins Назначить администратора группового чата
✔ DELETE /chats/{chatId}/members/admins Отменить права администратора группового чата
✔ GET /chats/{chatId}/members Получение участников группового чата
✔ POST /chats/{chatId}/members Добавление участников в групповой чат
✔ DELETE /chats/{chatId}/members Удаление участников из группового чата

upload

метод описание
✔ POST /uploads Загрузка файлов

subscriptions

метод описание
✔ GET /subscriptions Получение подписок
✔ POST /subscriptions Подписка на обновления
✔ DELETE /subscriptions Отписка от обновлений
✔ GET /updates Получение обновлений

Список изменений

Документация

Модели данных

Перечисления типов

Пример для minimal api - webhook

Пример консольного приложения - long-polling

добавлен проект-пример SampleBot

проект реализует сценарий бота уведомлений для событий из Zabbix.

Список изменений

<a id="changelog"></a>

изменения 1.0.15

  • добавлен новый тип кнопки - ClipboardButton

изменения 1.0.14

  • добавлены операторы преобразования UploadDataResponse в ImageAttachmentRequest, FileAttachmentRequest, AudioAttachmentRequest и VideoAttachmentRequest для упрощения использования выходных данных после UploadFile.

Пример использования:

    List<AttachmentRequest> attachments = [];
    var file1 = await bot.UploadFile(UploadType.File, "test.pdf");
    attachments.Add((FileAttachmentRequest)file1);
    var pic1 = await bot.UploadFile(UploadType.Image, "test.jpg");
    attachments.Add((ImageAttachmentRequest)pic1);
    var audio = await bot.UploadFile(UploadType.Audio, "test.mp3");
    attachments.Add((AudioAttachmentRequest)audio);
    var video = await bot.UploadFile(UploadType.Video, "test.mp4");
    attachments.Add((VideoAttachmentRequest)video);
    await bot.SendMessage(targetUid, "reply", attachments: attachments);

!! Внимание, в примере указана использование сразу нескольких типов вложений, но платформа на данный момент этого не позволяет, и будет возвращать одну из следующих ошибок (зависит от того, какой типа вложения использован первым):

  • Must be only one file attachment in message
  • Must be only one audio attachment in message
  • Must be only one video attachment in message

изменения 1.0.13.1

  • UploadFile (SendFile) исправлено преждевременное закрытие потока при чтении из файла

изменения 1.0.13

  • изменение MutedUntil поля в DialogMutedUpdate с long на DateTime
  • исправлена загрузка файла с помощью Stream
  • исправлена сериализация значения по умолчанию для поля Type (критично при отправке репостов)

изменения 1.0.12

  • добавлена перегрузка для метода AddButton(string text), добавляющая MessageButton в InlineKeyboard
InlineKeyboard AddButton(string text)

изменения 1.0.11

  • добавлен опциональный параметр Stream в метод UploadFile, для возможности работы с программно-подготовленным контентом вместо чтения с диска.
async Task<UploadDataResponse> UploadFile(UploadType type, string filename, Stream? fileStream = null)

изменения 1.0.10

  • Добавлен механизм повторных запросов при отправке сообщения, вложения которого требуют время на обработку платформой. Обработка ошибки "Key: errors.process.attachment.file.not.processed". При возникновении ошибки "errors.process.attachment.file.not.processed", будет произведена повторная попытка отправки сообщения. Задержка перед повторной попыткой расчитывается по формуле [номер попытки * 5 сек], за количество попыток в MaxBotClientOptions отвечает RetryWaitAttachment (значение по умолчанию - 10, итого, максимум времени ожидания - до 275 сек), после этого исключение будет выброшено во внешнюю обработку.

изменения 1.0.9

  • [FIX] не обрабатывались апдейты типа used_added/user_removed

изменения 1.0.8

  • добавлен метод расширения ReplyMessage

изменения 1.0.7

  • добавлена поддержка long-polling (из документации: Long Polling — для разработки и тестирования, только Webhook — для production-окружения)
  • добавлен метод AnswerCallback идентичный SendCallbackReact, более привычный для тех кто переносит код с телеграм-бота

Для работы long-polling достаточно задать обработчики событий OnError и OnUpdate, опционально можно задать обработчик OnMessage (без него, события типа MessageCreated и MessageEdited будут обрабатываться в OnUpdate) и поддерживать рабочий цикл ПО до завершения.

Изменения 1.0.6

  • Добавлены расширения для InlineKeyboard, упрощающие работу с ней.
public InlineKeyboard AddButton(string text, string callbackPayload)

добавляет CallbackButton в клавиатуру

public InlineKeyboard AddButton(Button button)

добавляет Button в клавиатуру (для иных типов кнопок)

public InlineKeyboard AddNewRow(params Button[] buttons)

добавляет новую строку в клавиатуру (с кнопками или без)

Пример использования
InlineKeyboard ik = new ();
ik.AddButton("Кнопка 1 строка 1", "callback payload 1");
ik.AddButton("Кнопка 2 строка 1", "callback payload 2");
ik.AddNewRow();
ik.AddButton("Кнопка 3 строка 2", "callback payload 3");
ik.AddNewRow().AddButton("Кнопка 4 строка 3", "callback payload 4").AddButton("Кнопка 5 строка 3", "callback payload 5");

NewMessageBody nm = new NewMessageBody()
{
    Attachments = [(InlineKeyboardAttachmentRequest)ik],
    Text = "Нажмите на любую кнопку"
};

var apiResponse = await maxbot.SendCallbackReact(callback_id, nm);

Документация

<a id="documentation"></a>

Методы:

subscriptions

Подписка на события (регистрация webhook)

<a id="method-setwebhook"></a>

async Task<ApiRespone> SetWebhook(string url, string? secretToken = null, IEnumerable<UpdateType>? updateTypes = null)

Подписывает бота на получение обновлений через WebHook. После вызова этого метода бот будет получать уведомления о новых событиях в чатах на указанный URL. Ваш сервер должен прослушивать один из следующих портов: 80, 8080, 443, 8443, 16384-32383

  • url (string) URL HTTP(S)-эндпойнта вашего бота. Должен начинаться с http(s)://
  • secret (string?) от 5 до 256 символов. Cекрет, который должен быть отправлен в заголовке X-Max-Bot-Api-Secret в каждом запросе Webhook. Разрешены только символы A-Z, a-z, 0-9, и дефис. Заголовок рекомендован, чтобы запрос поступал из установленного веб-узла.
  • updateTypes (IEnumerable<UpdateType>?) - Список типов обновлений, которые ваш бот хочет получать. Если передается null - бот будет получать все возможные обновления. Возможные типы обновлений на текущий момент:
    • MessageCreated,
    • MessageCallback,
    • MessageEdited,
    • MessageRemoved,
    • BotAdded,
    • BotRemoved,
    • DialogMuted,
    • DialogUnmuted,
    • DialogCleared,
    • DialogRemoved,
    • UserAdded,
    • UserRemoved,
    • BotStarted,
    • BotStopped,
    • ChatTitleChanged

Возвращает объект ApiResponse

Удаление подписки на события

<a id="method-deletewebhook"></a>

async Task<ApiResponse> DeleteWebhook(string url)

Отписывает бота от получения обновлений через Webhook. После вызова этого метода бот перестаёт получать уведомления о новых событиях, и становится доступна доставка уведомлений через API с длительным опросом

  • url (string) URL, который нужно удалить из подписок на WebHook.

Возвращает объект ApiResponse

Получение подписок

Запрос действующих подписок

<a id="method-getwebhookinfo"></a>

async Task<Subscriptions> GetWebhookInfo()

Если ваш бот получает данные через Webhook, этот метод возвращает список всех подписок. При настройке уведомлений для production-окружения рекомендуем использовать Webhook.

Обратите внимание: для отправки вебхуков поддерживается только протокол HTTPS, включая самоподписанные сертификаты. HTTP не поддерживается

Возвращает объект Subscriptions - список текущих подписок

Получение обновлений

<a id="method-getupdates"></a> применяется при long-polling подключении

async Task<UpdatesResponse> GetUpdates(int limit = 100, int timeout = 30, long? marker = null, IEnumerable<UpdateType>? types = null)

Этот метод можно использовать для получения обновлений при разработке и тестировании, если ваш бот не подписан на Webhook. Для production-окружения рекомендуем использовать Webhook

Метод использует долгий опрос (long polling). Каждое обновление имеет свой номер последовательности. Свойство marker в ответе указывает на следующее ожидаемое обновление.

Все предыдущие обновления считаются завершёнными после прохождения параметра marker. Если параметр marker не передан, бот получит все обновления, произошедшие после последнего подтверждения

  • limit (int) Максимальное количество обновлений для получения, по умолчанию 100
  • timeout (int) Тайм-аут в секундах для долгого опроса, по умолчанию 30
  • marker (long?) Если передан, бот получит обновления, которые еще не были получены. Если не передан, получит все новые обновления
  • types (IEnumerable<UpdateType>?) Список типов обновлений, которые ваш бот хочет получать. Если передается null - бот будет получать все возможные обновления

Возвращает объект UpdatesResponse содержащий массив Update

Update будет представлен одним из наследуемых классов:

MessageCreatedUpdate
MessageCallbackUpdate
MessageEditedUpdate
MessageRemovedUpdate
BotAddedUpdate
BotRemovedUpdate
DialogMutedUpdate
DialogUnmutedUpdate
DialogClearedUpdate
DialogRemovedUpdate
BotStartedUpdate
BotStoppedUpdate
ChatTitleChangedUpdate

bot

Получение информации о боте

<a id="method-getme"></a>

async Task<BotInfo> GetMe()

Метод возвращает информацию о боте, который идентифицируется с помощью токена доступа access_token. В ответе приходит объект User с вариантом наследования BotInfo, который содержит идентификатор бота, его название, никнейм, время последней активности, описание и аватар (при наличии)

Изменение информации о боте

<a id="method-editme"></a>


async Task<ApiResponse> EditMe(string? name = null, string? description = null, 
    IEnumerable<BotCommand>? commands = null, PhotoAttachmentRequestPayload? photo = null)
  • name (string?) - отображаемое имя бота
  • description (string?) - описание бота
  • commands (IEnumerable<BotCommand>?) - перечень доступных комманд бота
  • photo (PhotoAttachmentRequestPayload) - изображение для профиля бота
!Внимание! Данный метод не задокументирован в официальной документации и взят из исходников библиотек под TS. Использовать на свой страх и риск!

Возвращает объект ApiResponse

messages

Получение сообщений

<a id="method-getmessages"></a>

async Task<MessagesResponse> GetMessages(long chat_id, DateTime? from = null, DateTime? to = null, int? count = null)
async Task<MessagesResponse> GetMessages(IEnumerable<string> messages_ids, DateTime? from = null, DateTime? to = null, int? count = null)

Метод возвращает информацию о сообщении или массив сообщений из чата. Для выполнения запроса нужно указать один из параметров — chat_id или message_ids:

  • chat_id (long) — метод возвращает массив сообщений из указанного чата. Сообщения возвращаются в обратном порядке: последние сообщения будут первыми в массиве. ID чата, чтобы получить сообщения из определённого чата. Обязательный параметр, если не указан message_ids

  • message_ids (IEnumerable<string>) — метод возвращает информацию о запрошенных сообщениях. Можно указать один идентификатор или несколько. Список ID сообщений, которые нужно получить (через запятую). Обязательный параметр, если не указан chat_id

  • from (DateTime?) - Время начала для запрашиваемых сообщений

  • to (DateTime?) - Время окончания для запрашиваемых сообщений

  • count (int?) - Максимальное количество сообщений в ответе, по умолчанию 50

Возвращает объект MessagesResponse

Отправить сообщение

<a id="method-sendmessage"></a>

async Task<ApiMessage> SendMessage(long user_id, string? text, bool disable_link_preview = false, bool notify = true,
            TextFormat? text_format = null,
            NewMessageLink? link = null, IEnumberable<AttachmentRequest>? attachments = null)

async Task<ApiMessage> SendMessageToChat(long chat_id, string? text, bool disable_link_preview = false, bool notify = true,
            TextFormat? text_format = null,
            NewMessageLink? link = null, IEnumberable<AttachmentRequest>? attachments = null)

используйте SendMessage с указанием user_id, если хотите отправить сообщение пользователю.

используйте SendMessageToChat с указанием chat_id, если хотите отправить сообщение в группу.

  • user_id (long) - Если вы хотите отправить сообщение пользователю, укажите его ID
  • chat_id (long) - Если сообщение отправляется в чат, укажите его ID
  • disable_link_preview (bool) - Если false, сервер не будет генерировать превью для ссылок в тексте сообщения
  • text (string?) - Новый текст сообщения, до 4000 символов
  • attachments (IEnumerable<AttachmentRequest>?) - Вложения сообщения. Если пусто, все вложения будут удалены
  • link (NewMessageLink?) - Ссылка на сообщение (для ответов и репостов)
  • notify (bool) - Если false, участники чата не будут уведомлены (по умолчанию true)
  • text_format (TextFormat?) - Если установлен, текст сообщения будет форматирован данным способом, возможные варианты Markdown или HTML

Возвращает объект ApiMessage

Ответ на сообщение (вспомогательный метод)
async Task<ApiMessage> ReplyMessage(Message message, string? text, bool disable_link_preview = false,
            bool notify = true,
            TextFormat? text_format = null,
            NewMessageLink? link = null, IEnumerable<AttachmentRequest>? attachments = null)

Данный метод отвечает на входящее сообщение, автоматически выбирая SendMessage или SendMessageToChat

Возвращает объект ApiMessage

Редактирование сообщения

<a id="method-editmessage"></a>

async Task<ApiResponse> EditMessage(string message_id, string? text = null, IEnumberable<AttachmentRequest>? attachments = null, NewMessageLink? link = null,
            bool notify = true, TextFormat text_format = TextFormat.HTML)

Редактирует сообщение в чате. Если поле attachments равно null, вложения текущего сообщения не изменяются. Если в этом поле передан пустой список, все вложения будут удалены

С помощью метода можно отредактировать сообщения, которые отправлены менее 24 часов назад

  • message_id (string) - ID редактируемого сообщения
  • text (string?) - Новый текст сообщения, до 4000 символов
  • attachments (IEnumerable<AttachmentRequest>) - Вложения сообщения. Если пусто, все вложения будут удалены
  • link (NewMessageLink?) - Ссылка на сообщение (для ответов и репостов)
  • notify (bool) - Если false, участники чата не будут уведомлены (по умолчанию true)
  • text_format (TextFormat?) - Если установлен, текст сообщения будет форматирован данным способом, возможные варианты Markdown или HTML

Возвращает объект ApiResponse

Удалить сообщение

<a id="method-deletemessage"></a>

async Task<ApiResponse> DeleteMessage(string messageId)

Удаляет сообщение в диалоге или чате, если бот имеет разрешение на удаление сообщений

С помощью метода можно удалять сообщения, которые отправлены менее 24 часов назад

  • message_id (string) - ID удаляемого сообщения

Возвращает объект ApiResponse

Ответ на Callback

<a id="method-answercallback"></a>

async Task<ApiResponse> SendCallbackReact(string callback_id, NewMessageBody? newMessageBody = null, string? notification = null)
// дополнительное название одного и того же метода 
async Task<ApiResponse> AnswerCallback(string callback_id, NewMessageBody? newMessageBody = null, string? notification = null)

Этот метод используется для отправки ответа после того, как пользователь нажал на кнопку. Ответом может быть обновленное сообщение и/или одноразовое уведомление для пользователя

  • callback_id (string) - Идентификатор кнопки, по которой пользователь кликнул. Бот получает идентификатор как часть Update с типом **MessageCallbackUpdate **.
  • newMessageBody (NewMessageBody?) - Заполните это, если хотите изменить текущее сообщение (текст, вложения, кнопки)
  • notification (string?) - Заполните это, если хотите просто отправить одноразовое уведомление пользователю (не отображается в десктоп-клиенте, возможно временно, но есть в мобильных приложениях)

Возвращает объект ApiResponse

Получить сообщение

<a id="method-getmessage"></a>

async Task<Message> GetMessage(string message_id)

Возвращает сообщение по его ID

  • message_id (string) - ID сообщения (mid), чтобы получить одно сообщение в чате

Возвращает объект Message

Получить информацию о видео

<a id="method-getvideoinfo"></a>

async Task<VideoInfo> GetVideoInfo(string video_token)

Возвращает подробную информацию о прикреплённом видео. URL-адреса воспроизведения и дополнительные метаданные

  • video_token (string) Токен видео-вложения

Возвращает объект VideoInfo

chat

Получение списка всех групповых чатов

<a id="method-getchats"></a>

async Task<ChatsResponse> GetChats()
async Task<ChatsResponse> GetChats(int count = 50, long? marker = null)

Возвращает список групповых чатов, в которых участвовал бот, информацию о каждом чате и маркер для перехода к следующей странице списка

  • count (int) - Количество запрашиваемых чатов, по умолчанию 50
  • marker (long?) - Указатель на следующую страницу данных. Для первой страницы передайте null

Возвращает объект ChatsResponse

Получение информации о групповом чате

<a id="method-getchat"></a>

async Task<Chat> GetChat(long chat_id)

Возвращает информацию о групповом чате по его ID

  • chat_id (long) - ID запрашиваемого чата

Возвращает объект Chat

Изменение информации о групповом чате

<a id="method-editchatinfo"></a>

async Task<Chat> EditChatInfo(long chat_id, PhotoAttachmentRequestPayload? icon = null, string? title = null, string? pin = null,
            bool? notify = null)

Позволяет редактировать информацию о групповом чате, включая название, иконку и закреплённое сообщение

  • chat_id (long) - ID редактируемого чата
  • icon (PhotoAttachmentRequestPayload?) - Запрос на прикрепление изображения (все поля являются взаимоисключающими)
  • title (string?) - от 1 до 200 символов
  • pin (string?) - ID сообщения для закрепления в чате. Чтобы удалить закреплённое сообщение, используйте метод UnpinMessage
  • notify (bool?) - Если true, участники получат системное уведомление об изменении

Возвращает объект Chat

Удаление группового чата

<a id="method-deletechat"></a>

async Task<ApiResponse>DeleteChat(long chat_id)

Удаляет групповой чат для всех участников

  • chat_id (long) - ID удаляемого чата

Возвращает объект ApiResponse

Отправка действия бота в групповой чат

<a id="method-sendchataction"></a>

async Task<ApiResponse> SendChatAction(long chat_id, SenderAction action)

Позволяет отправлять в групповой чат такие действия бота, как например: «набор текста» или «отправка фото»

  • chat_id (long) - ID группового чата
  • action (SenderAction) - Действие, отправляемое участникам чата. Возможные значения:
    • TypingOn, — Бот набирает сообщение.
    • SendingPhoto, — Бот отправляет фото.
    • SendingVideo, — Бот отправляет видео.
    • SendingAudio, — Бот отправляет аудиофайл.
    • SendingFile, — Бот отправляет файл.
    • MarkSeen — Бот помечает сообщения как прочитанные.

Возвращает объект ApiResponse

Получение закреплённого сообщения в групповом чате

<a id="method-getchatpinnedmessage"></a>

async Task<ApiMessage> GetChatPinnedMessage(long chat_id)

Возвращает закреплённое сообщение в групповом чате

  • chat_id (long) - ID группового чата

Возвращает объект ApiMessage

Закрепление сообщения в групповом чате

<a id="method-pinmessage"></a>

async Task<ApiResponse> PinMessage(long chat_id, string message_id, bool notify = true)
  • chat_id (long) - ID группового чата
  • message_id (string) - ID сообщения, которое нужно закрепить. Соответствует полю Message.MessageBody.MessageId
  • notify (bool) - Если true, участники получат уведомление с системным сообщением о закреплении

Возвращает объект ApiResponse

Удаление закреплённого сообщения в групповом чате

<a id="method-unpinmessage"></a>

async Task<ApiResponse> UnpinMessage(long chat_id)

Удаляет закреплённое сообщение в групповом чате

  • chat_id (long) - ID группового чата

Возвращает объект ApiResponse

Получение информации о членстве бота в групповом чате

<a id="method-getchatmyinfo"></a>

async Task<ChatMember> GetChatMyInfo(long chat_id)

Возвращает информацию о членстве текущего бота в групповом чате. Бот идентифицируется с помощью токена доступа

  • chat_id (long) - ID группового чата

Возвращает наследованный от User объект ChatMember

Удаление бота из группового чата

<a id="method-leavechat"></a>

async Task<ApiResponse> LeaveChat(long chat_id)

Удаляет бота из участников группового чата

  • chat_id (long) - ID группового чата

Возвращает объект ApiResponse

Получение списка администраторов группового чата

<a id="method-getchatadmins"></a>

async Task<ChatMembersResponse> GetChatAdmins(long chat_id, long? marker = null)

Возвращает список всех администраторов группового чата. Бот должен быть администратором в запрашиваемом чате

  • chat_id (long) - ID группового чата
  • marker (long?) - Указатель на следующую страницу данных

Возвращает объект ChatMembersResponse

Назначить администратора группового чата

<a id="method-addchatadmins"></a>

async Task<ApiResponse> AddChatAdmins(long chat_id, IEnumerable<ChatAdmin> admins)

Возвращает значение true, если в групповой чат добавлены все администраторы.

В группе может быть не более 50 администраторов

  • chat_id (long) - ID группового чата
  • admins (IEnumerable<ChatAdmin>) - Список пользователей, которые получат права администратора чата

Возвращает объект ApiResponse

Отменить права администратора в групповом чате

<a id="method-deletechatadmin"></a>

async Task<ApiResponse> DeleteChatAdmin(long chat_id, long user_id)

Отменяет права администратора у пользователя в групповом чате, лишая его административных привилегий

  • chat_id (long) - ID группового чата
  • user_id (long) - ID пользователя

Возвращает объект ApiResponse

Получение участников группового чата

<a id="method-getchatmembers"></a>

async Task<ChatMembersResponse> GetChatMembers(long chat_id)
async Task<ChatMembersResponse> GetChatMembers(long chat_id, long marker, int count = 20)
async Task<ChatMembersResponse> GetChatMembers(long chat_id, IEnumerable<long> user_ids)

Возвращает список участников группового чата

  • chat_id (long) - ID группового чата
  • user_ids (IEnumerable<long>) - Список ID пользователей, чье членство нужно получить. Когда этот параметр передан, параметры count и marker игнорируются
  • marker (long) - Указатель на следующую страницу данных
  • count (int) - Количество участников, которых нужно вернуть, по умолчанию 20

Возвращает объект ChatMembersReponse

Добавление участников в групповой чат

<a id="method-inviteuser"></a>

async Task<ApiResponse> InviteUser(long chat_id, IEnumerable<long> user_ids)

Добавляет участников в групповой чат. Для этого могут потребоваться дополнительные права

  • chat_id (long) - ID группового чата
  • user_ids (IEnumerable<long>) - Список ID пользователей для добавления в чат

Возвращает объект ApiResponse

Удаление участника из группового чата

<a id="method-kickuser"></a>

async Task<ApiResponse> KickUser(long chat_id, long user_id, bool block = false)

Удаляет участника из группового чата. Для этого могут потребоваться дополнительные права

  • chat_id (long) - ID группового чата
  • user_id (long) - ID пользователя, которого нужно удалить из чата
  • block (bool) - Если установлено в true, пользователь будет заблокирован в чате. Применяется только для чатов с публичной или приватной ссылкой. Игнорируется в остальных случаях

Возвращает объект ApiResponse

Upload

Загрузка файлов

<a id="method-uploadfile"></a>

async Task<UploadDataResponse> UploadFile(UploadType type, string filename, Stream? fileStream = null)

Делает полную операцию по загрузке файла: получет ссылку на загрузку и по ней загружает файл

  • type (UploadType) - тип загружаемого файла, может быть Image, Video, Audio, File
  • filename (string) - путь до загружаемого файла
  • fileStream (Stream?) - опциональный параметр для загрузки файлов с помощью Stream (с 1.0.11)
Типы файлов:
    • image: JPG, JPEG, PNG, GIF, TIFF, BMP, HEIC
    • video: MP4, MOV, MKV, WEBM, MATROSKA
    • audio: MP3, WAV, M4A и другие
    • file: любые типы файлов

Может вызывать исключение типа FileNotFoundException. Возвращает объект UploadDataResponse

Для использования загруженного вложения, его необходимо преобразовать в AttachmentRequest и отправить сообщение с вложениями.

    List<AttachmentRequest> attachments = [];
    var file1 = await bot.UploadFile(UploadType.File, "test.pdf");
    attachments.Add((FileAttachmentRequest)file1);
    var pic1 = await bot.UploadFile(UploadType.Image, "test.jpg");
    attachments.Add((ImageAttachmentRequest)pic1);
    var audio = await bot.UploadFile(UploadType.Audio, "test.mp3");
    attachments.Add((AudioAttachmentRequest)audio);
    var video = await bot.UploadFile(UploadType.Video, "test.mp4");
    attachments.Add((VideoAttachmentRequest)video);
    await bot.SendMessage(targetUid, "reply", attachments: attachments);

<a id="datamodels"></a>

Модели данных

<a id="model-apimessage"></a>

ApiMessage
public class ApiMessage
{
    public required Message Message { get; set; }
}
ApiResponse

<a id="model-apiresponse"></a>

public class ApiResponse
{
    // true, если запрос был успешным, false в противном случае
    public bool Success { get; set; }

    // Объяснительное сообщение, если результат не был успешным
    public string? Message { get; set; }
}

<a id="model-attachment"></a>

Attachment

ContactAttachemnt | InlineKeyboardAttachment | StickerAttachment | FileAttachment | AudioAttachment | VideoAttachment | ShareAttachment | ImageAttachment | LocationAttachment

public abstract class Attachment
{
    // image, video, audio, file, sticker, contact, inline_keyboard, share, location 
    public abstract AttachmentType Type { get; set; }
}

<a id="model-contactattachment"></a>

  • ContactAttachment
public class ContactAttachment : Attachment
{
    public required ContactAttachmentPayload Payload { get; set; }    
}

<a id="model-inlinekeyboardattachment"></a>

  • InlineKeyboardAttachment
public class InlineKeyboardAttachment : Attachment
{
    public required InlineKeyboard Payload { get; set; }
}

<a id="model-stickerattachment"></a>

  • StickerAttachment
public class StickerAttachment : Attachment
{
    public required StickerAttachmentPayload Payload { get; set; }

    // Ширина стикера
    public int Width { get; set; }

    // Высота стикера
    public int Height { get; set; }
}

<a id="model-fileattachment"></a>

  • FileAttachment
public class FileAttachment : Attachment
{
    public required FileAttachmentPayload Payload { get; set; }

    // Имя загруженного файла
    public required string Filename { get; set; }

    // Размер файла в байтах
    public long Size { get; set; }
}

<a id="model-audioattachment"></a>

  • AudioAttachment
public class AudioAttachment : Attachment
{
    public required MediaAttachmentPayload Payload { get; set; }

    // Аудио транскрипция
    public string? Transcription { get; set; }
}

<a id="model-videoattachment"></a>

  • VideoAttachment
public class VideoAttachment : Attachment
{
    public required MediaAttachmentPayload Payload { get; set; }

    // Миниатюра видео
    public VideoThumbnail? Thumbnail { get; set; }

    // Ширина видео
    public int? Width { get; set; }

    // Высота видео
    public int? Height { get; set; }

    // Длина видео в секундах
    public int? Duration { get; set; }
}

<a id="model-shareattachment"></a>

  • ShareAttachment
public class ShareAttachment : Attachment
{
    public required ShareAttachmentPayload Payload { get; set; }

    // Заголовок предпросмотра ссылки.
    public string? Title { get; set; }

    // Описание предпросмотра ссылки
    public string? Description { get; set; }

    // Изображение предпросмотра ссылки
    public string? ImageUrl { get; set; }
}

<a id="model-imageattachment"></a>

  • ImageAttachment
public class ImageAttachment : Attachment
{
    public required PhotoAttachmentPayload Payload { get; set; }
}

<a id="model-locationattachment"></a>

  • LocationAttachment

public class LocationAttachment : Attachment
{
    // широта
    public double Latitude { get; set; }

    // долгота
    public double Longitude { get; set; }
}

<a id="model-attachmentrequest"></a>

AttachmentRequest

ImageAttachmentRequest | VideoAttachmentRequest | AudioAttachmentRequest | FileAttachmentRequest | StickerAttachmentRequest | ContactAttachmentRequest | InlineKeyboardAttachmentRequest | LocationAttachmentRequest | ShareAttachmentRequest

public abstract class AttachmentRequest
{
    // Тип
    public abstract AttachmentType Type { get; }    
}

<a id="model-imageattachmentrequest"></a>

  • ImageAttachmentRequest
public class ImageAttachmentRequest : AttachmentRequest
{
    // Запрос на прикрепление изображения (все поля являются взаимоисключающими)
    public required PhotoAttachmentRequestPayload  Payload { get; set; }    
}

<a id="model-videoattachmentrequest"></a>

  • VideoAttachmentRequest
public class VideoAttachmentRequest : AttachmentRequest
{
    // Это информация, которую вы получите, как только аудио/видео будет загружено
    public required UploadedInfo Payload { get; set; }
}

<a id="model-audioattachmentrequest"></a>

  • AudioAttachmentRequest
public class AudioAttachmentRequest : AttachmentRequest
{
    // Это информация, которую вы получите, как только аудио/видео будет загружено
    public required UploadedInfo Payload { get; set; }
}

<a id="model-fileattachmentrequest"></a>

  • FileAttachmentRequest
public class FileAttachmentRequest : AttachmentRequest
{
    // Это информация, которую вы получите, как только аудио/видео будет загружено
    public required UploadedInfo Payload { get; set; }
}

<a id="model-stickerattachmentrequest"></a>

  • StickerAttachmentRequest
public class StickerAttachmentRequest : AttachmentRequest
{
    public required StickerAttachmentRequestPayload Payload { get; set; }
}

<a id="model-contactattachmentrequest"></a>

  • ContactAttachmentRequest
public class ContactAttachmentRequest : AttachmentRequest
{
    public required ContactAttachmentRequestPayload Payload { get; set; }
}

<a id="model-inlinekeyboardattachmentrequest"></a>

  • InlineKeyboardAttachmentRequest
public class InlineKeyboardAttachmentRequest : AttachmentRequest
{
    public required InlineKeyboardAttachmentRequestPayload Payload { get; set; }
}

<a id="model-locationattachmentrequest"></a>

  • LocationAttachmentRequest
public class LocationAttachmentRequest : AttachmentRequest
{
    // широта
    public double Latitude { get; set; }
    
    // долгота
    public double Longitude { get; set; }
}

<a id="model-shareattachmentrequest"></a>

  • ShareAttachmentRequest
public class ShareAttachmentRequest : AttachmentRequest
{
    public required ShareAttachmentPayload Payload { get; set; }
}

<a id="model-botcommand"></a>

BotCommand
public class BotCommand
{
    // от 1 до 64 символов, Название команды
    public required string Name { get; set; }

    // от 1 до 128 символов, Описание команды (по желанию)
    public string? Description { get; set; }

}

<a id="model-botinfo"></a>

BotInfo
public class BotInfo : User 
{
    // до 16000 символов. Описание пользователя или бота. В случае с пользователем может принимать значение null, если описание не заполнено
    public string? Description { get; set; }
    // URL аватара пользователя или бота в уменьшенном размере
    public string? AvatarUrl { get; set; }
    // URL аватара пользователя или бота в полном размере
    public string? FullAvatarUrl { get; set; }
    // Команды, поддерживаемые ботом. до 32 элементов
    public BotCommand[]? Commands { get; set; }
}

<a id="model-button"></a>

Button

MessageButton | OpenAppButton | RequestContactButton | RequestGeoLocationButton | LinkButton | CallbackButton | ClipboardButton

public abstract class Button
{
    public abstract ButtonType Type { get; }
}

<a id="model-messagebutton"></a>

  • MessageButton
public class MessageButton : Button
{
    // от 1 до 128 символов
    // Видимый текст кнопки
    public required string Text { get; set; }
}

<a id="model-openappbutton"></a>

  • OpenAppButton
public class OpenAppButton : Button
{
    // от 1 до 128 символов
    // Видимый текст кнопки
    public required string Text { get; set; }

    // Публичное имя (username) бота или ссылка на него, чьё мини-приложение надо запустить
    public string WebApp { get; set; } = string.Empty;

    // Идентификатор бота, чьё мини-приложение надо запустить
    public long ContactId { get; set; }

    // Параметр запуска, который будет передан в initData мини-приложения
    public string Payload { get; set; } = string.Empty;
}

<a id="model-requestcontactbutton"></a>

  • RequestContactButton
public class RequestContactButton : Button
{
    // от 1 до 128 символов
    // Видимый текст кнопки
    public required string Text { get; set; }
}

<a id="model-requestgeolocationbutton"></a>

  • RequestGeoLocationButton
public class RequestGeoLocationButton : Button
{    
    // от 1 до 128 символов
    // Видимый текст кнопки
    public required string Text { get; set; }

    // Если true, отправляет местоположение без запроса подтверждения пользователя
    public bool Quick { get; set; }
}

<a id="model-linkbutton"></a>

  • LinkButton
public class LinkButton : Button
{
    // от 1 до 128 символов
    // Видимый текст кнопки
    public required string Text { get; set; }

    // до 2048 символов
    public required string Url { get; set; }
}

<a id="model-callbackbutton"></a>

  • CallbackButton
public class CallbackButton : Button
{
    // от 1 до 128 символов
    // Видимый текст кнопки
    public required string Text { get; set; }

    // до 1024 символов
    // Токен кнопки
    public required string Payload { get; set; }
}

<a id="model-clipboardbutton"></a>

  • ClipboardButton
public class ClipboardButton : Button
{
    // от 1 до 128 символов
    // Видимый текст кнопки. Чтобы он отображался полностью, рекомендуем не превышать заданное количество символов в зависимости от размещения текста: 20 символов — при 1 кнопке в ряду, 10 — при 2, 5 — при 3, 3 — при 4
    public required string Text { get; set; }

    // Текст, который копируется в буфер обмена после нажатия на кнопку
    public required string Payload { get; set; }
}

<a id="model-callback"></a>

Callback
public class Callback
{
    // время, когда пользователь нажал кнопку
    public DateTime TimeStamp { get; set; }
    
    // Текущий ID клавиатуры
    public required string CallbackId { get; set; }
    
    // Токен кнопки
    public string? Payload { get; set; }
    
    // Пользователь, нажавший на кнопку
    public required User User { get; set; }

}

<a id="model-chat"></a>

Chat
public class Chat
{
    // ID чата
    public long ChatId { get; set; }

    // Тип чата: dialog, chat, channel
    public ChatType Type { get; set; }

    // Статус чата:
    // Active — Бот является активным участником чата.
    // Removed — Бот был удалён из чата.
    // Left — Бот покинул чат.
    // Closed — Чат был закрыт.
    public ChatStatus Status { get; set; }
    
    // Отображаемое название чата. Может быть null для диалогов
    public string? Title { get; set; }
    
    // Время последнего события в чате
    public DateTime LastEventTime { get; set; }
    
    // Количество участников чата. Для диалогов всегда 2
    public int ParticipantsCount { get; set; }
    
    // ID владельца чата
    public long? OwnerId { get; set; }
    
    // Доступен ли чат публично (для диалогов всегда false)
    public bool IsPublic { get; set; }
    
    // Ссылка на чат
    public string? Link { get; set; }
    
    // Описание чата
    public string? Description { get; set; }

    // Данные о пользователе в диалоге (только для чатов типа "dialog")
    public UserWithPhoto? DialogWithUser { get; set; }
    
    // ID сообщения, содержащего кнопку, через которую был инициирован чат
    public string? ChatMessageId { get; set; }
    
    // Закреплённое сообщение в чате (возвращается только при запросе конкретного чата)
    public Message? PinnedMessage { get; set; }
}

<a id="model-chatadmin"></a>

ChatAdmin
public class ChatAdmin
{
    // Идентификатор пользователя-участника чата, который назначается администратором
    // Максимум — 50 администраторов в чате
    public long UserID { get; set; }

    // Перечень прав доступа пользователя. Возможные значения:
    // "read_all_messages" — Читать все сообщения. Это право важно при назначении ботов: без него бот не будет получать апдейты (вебхуки) в групповом чате
    // "add_remove_members" — Добавлять/удалять участников
    // "add_admins" — Добавлять администраторов
    // "change_chat_info" — Изменять информацию о чате
    // "pin_message" — Закреплять сообщения
    // "write" — Писать сообщения
    // "can_call" — Совершать звонки
    // "edit_link" — Изменять ссылку на чат
    // "post_edit_delete_message" — Публиковать, редактировать и удалять сообщения
    // "edit_message" — Редактировать сообщения
    // "delete_message" — Удалять сообщения
    // Если право назначается администратору, то обновляются его текущие права доступа
    public required IEnumerable<ChatAdminPermission> Permissions { get; set; }

    // Титул администратора (вместо "админ" и "владелец")
    public string? Alias { get; set; }

}

<a id="model-chatmember"></a>

ChatMember
public class ChatMember:User
{
    // до 16000 символов
    // Описание пользователя или бота. В случае с пользователем может принимать значение null, если описание не заполнено
    public string? Description { get; set; }

    // URL аватара пользователя или бота в уменьшенном размере
    public string? AvatarUrl { get; set; }

    // URL аватара пользователя или бота в полном размере
    public string? FullAvatarUrl { get; set; }

    // Время последней активности пользователя в чате. Может быть устаревшим для суперчатов (равно времени вступления)
    public DateTime LastAccessTime { get; set; }
    
    // Является ли пользователь владельцем чата
    public bool IsOwner { get; set; }
    
    // Является ли пользователь администратором чата 
    public bool IsAdmin { get; set; }

    // Дата присоединения к чату в формате Unix time
    public DateTime JoinTime { get; set; }
    
    // Перечень прав пользователя. Возможные значения:
    // "read_all_messages" — Читать все сообщения.
    // "add_remove_members" — Добавлять/удалять участников.
    // "add_admins" — Добавлять администраторов.
    // "change_chat_info" — Изменять информацию о чате.
    // "pin_message" — Закреплять сообщения.
    // "write" — Писать сообщения.
    // "edit_link" — Изменять ссылку на чат.
    public ChatAdminPermission[]? Permissions { get; set; }
    
    // Заголовок, который будет показан на клиенте
    // Если пользователь администратор или владелец и ему не установлено это название, то поле не передаётся, клиенты на своей стороне подменят на "владелец" или "админ"
    public string? Alias { get; set; }    
}

<a id="model-chatmembersresponse"></a>

ChatMembersResponse
public class ChatMembersResponse
{
    // Список участников чата с информацией о времени последней активности
    public required ChatMember[] ChatMembers { get; set; }
    
    // Указатель на следующую страницу данных
    public long? Marker  { get; set; }    
}

<a id="model-chatsresponse"></a>

ChatsResponse
public class ChatsResponse
{
    public required IEnumerable<Chat> Chats { get; set; }
}

<a id="model-inlinekeyboard"></a>

InlineKeyboard
public class InlineKeyboard
{
    // двумерный массив кнопок ([строка][столбец])
    public required IEnumerable<IEnumerable<Button>> Buttons { get; set; } = [];   

}

<a id="model-linkedmessage"></a>

LinkedMessage
public class LinkedMessage
{
    // Тип связанного сообщения
    public MessageLinkType Type { get; set; }
    
    // Пользователь, отправивший сообщение.
    public User? Sender { get; set; }
    
    // Чат, в котором сообщение было изначально опубликовано. Только для пересланных сообщений
    public long? ChatId { get; set; }
    
    // Схема, представляющая тело сообщения
    public required MessageBody MessageBody { get; set; }

}

<a id="model-markupelement"></a>

MarkupElement
public abstract class MarkupElement
{
    // Тип элемента разметки. Может быть жирный, курсив, зачеркнутый, подчеркнутый, моноширинный, ссылка или упоминание пользователя
    // strong , emphasized, monospaced, link, strikethrough, underline, user_mention
    public abstract MarkupElementType Type { get; set; }

    // Индекс начала элемента разметки в тексте. Нумерация с нуля
    public int From { get; set; }

    // Длина элемента разметки
    public int Length { get; set; } 
}

<a id="model-strongmarkupelement"></a>

  • StrongMarkupElement
public class StrongMarkupElement : MarkupElement
{
}

<a id="model-emphasizedmarkupelement"></a>

  • EmphasizedMarkupElement
public class EmphasizedMarkupElement : MarkupElement
{
}

<a id="model-monospacedmarkupelement"></a>

  • MonospacedMarkupElement
public class MonospacedMarkupElement : MarkupElement
{
}

<a id="model-linkmarkupelement"></a>

  • LinkMarkupElement
public class LinkMarkupElement : MarkupElement
{
    // URL ссылки, до 1024 символов
    public required string Url { get; set; }
}

<a id="model-strikethroughmarkupelement"></a>

  • StrikethroughMarkupElement
public class StrikethroughMarkupElement : MarkupElement
{
}

<a id="model-underlinemarkupelement"></a>

  • UnderlineMarkupElement
public class UnderlineMarkupElement : MarkupElement
{    
}

<a id="model-usermentionmarkupelement"></a>

  • UserMentionMarkupElement
public class UserMentionMarkupElement : MarkupElement
{
    // @username упомянутого пользователя
    public string? UserLink { get; set; }

    // ID упомянутого пользователя без имени
    public long? UserID { get; set; }
}

<a id="model-message"></a>

Message
public class Message
{
    // Пользователь, отправивший сообщение
    public required User Sender { get; set; }
    
    // Получатель сообщения. Может быть пользователем или чатом
    public required Recipient Recipient { get; set; }
    
    /// Время создания сообщения
    public DateTime TimeStamp { get; set; }
    
    // Пересланное или ответное сообщение
    public LinkedMessage? Link { get; set; }
    
    // Содержимое сообщения. Текст + вложения. Может быть null, если сообщение содержит только пересланное сообщение
    public MessageBody? MessageBody { get; set; }
    
    // Статистика сообщения.
    public MessageStat? Stat { get; set; }
    
    // Публичная ссылка на пост в канале. Отсутствует для диалогов и групповых чатов
    public string? Url { get; set; }   
}

<a id="model-messagebody"></a>

MessageBody
public class MessageBody
{
    // Уникальный ID сообщения
    public required string MessageId { get; set; }

    // ID последовательности сообщения в чате
    public long SequenceId { get; set; }

    // Новый текст сообщения
    public string? Text { get; set; }

    // Вложения сообщения. Могут быть одним из типов Attachment. Смотрите описание схемы
    public Attachment[]? Attachments { get; set; }

    // Разметка текста сообщения. Для подробной информации загляните в раздел Форматирование https://dev.max.ru/docs-api#%D0%A4%D0%BE%D1%80%D0%BC%D0%B0%D1%82%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5%20%D1%82%D0%B5%D0%BA%D1%81%D1%82%D0%B0
    public MarkupElement[]? Markup { get; set; }
}

<a id="model-messagesresponse"></a>

MessagesResponse
public class MessagesResponse
{
    // Массив сообщений
    public required Message[]  Messages { get; set; }
}

<a id="model-messagestat"></a>

MessageStat
public class MessageStat
{
    public long Views { get; set; }
}

<a id="model-newmessagebody"></a>

NewMessageBody
public class NewMessageBody
{
    // до 4000 символов
    // Новый текст сообщения
    public string? Text { get; set; }

    // Вложения сообщения. Если пусто, все вложения будут удалены
    public IEnumerable<AttachmentRequest>? Attachments { get; set; }

    // Ссылка на сообщение
    public NewMessageLink? Link { get; set; }

    // По умолчанию: true
    // Если false, участники чата не будут уведомлены (по умолчанию true)
    public bool Notify { get; set; }
    
    // по умолчанию форматирование текста в HTML
    public TextFormat? TextFormat { get; set; }    
}

<a id="model-newmessagelink"></a>

public class NewMessageLink
{
    // Тип ссылки сообщения
    public required MessageLinkType Type { get; set; }
    
    // ID сообщения исходного сообщения
    public required string MessageId { get; set; }    
}

<a id="model-recipient"></a>

Recipient
public class Recipient
{
    // ID чата
    public long ChatId { get; set; }

    // Тип чата
    public required ChatType ChatType { get; set; }

    // ID пользователя, если сообщение было отправлено пользователю
    public long? UserId { get; set; }
}

<a id="model-subscription"></a>

Subscription
public class Subscription
{
    // URL вебхука
    public required string Url { get; set; }

    // время, когда была создана подписка
    public DateTime Time { get; set; }

    // типа обновлений, на которые зарегистрирована подписка
    public UpdateType[]? UpdateTypes { get; set; }    
}

<a id="model-subscriptions"></a>

Subscriptions
public class Subscriptions 
{
    public Subscription[]? Webhooks { get; set; }
}

<a id="model-update"></a>

Update

MessageCreatedUpdate | MessageCallbackUpdate | MessageEditedUpdate | MessageRemovedUpdate | BotAddedUpdate | BotRemovedUpdate | DialogMutedUpdate | DialogUnmutedUpdate | DialogClearedUpdate | DialogRemovedUpdate | UserAddedUpdate | UserRemovedUpdate | BotStartedUpdate | BotStoppedUpdate | ChatTitleChangedUpdate

public abstract class Update
{
    // ОбъектUpdate представляет различные типы событий, произошедших в чате. См. его наследников
    public  UpdateType UpdateType { get; set; }

    // время, когда произошло событие
    public DateTime TimeStamp { get; set; }

}

<a id="model-messagecreatedupdate"></a>

  • MessageCreatedUpdate
public class MessageCreatedUpdate : Update
{
    // Новое созданное сообщение
    public required Message Message { get; set; }

    // Текущий язык пользователя в формате IETF BCP 47
    public string? UserLocale { get; set; }
 
}

<a id="model-messagecallbackupdate"></a>

  • MessageCallbackUpdate
public class MessageCallbackUpdate : Update
{
    // клавиатура
    public required Callback Callback { get; set; }

    // Изначальное сообщение, содержащее встроенную клавиатуру. Может быть null, если оно было удалено к моменту, когда бот получил это обновление
    public Message? Message { get; set; }

    // Текущий язык пользователя в формате IETF BCP 47
    public string? UserLocale { get; set; }   
}

<a id="model-messageeditedupdate"></a>

  • MessageEditedUpdate
public class MessageEditedUpdate : Update
{
    // Отредактированное сообщение
    public required Message Message { get; set; }
}

<a id="model-messageremovedupdate"></a>

  • MessageRemovedUpdate
public class MessageRemovedUpdate : Update
{
    // ID удаленного сообщения
    public required string MessageId { get; set; }

    // ID чата, где произошло событие
    public long ChatId { get; set; }

    // Пользователь, удаливший сообщение
    public long UserId { get; set; }
}

<a id="model-botaddedupdate"></a>

  • BotAddedUpdate
public class BotAddedUpdate : Update
{
    // ID чата, где произошло событие
    public long ChatId { get; set; }

    // Пользователь, добавивший бота в чат
    public required User User { get; set; }

    // Указывает, был ли бот добавлен в канал или нет
    public bool IsChannel { get; set; }
}

<a id="model-botremovedupdate"></a>

  • BotRemovedUpdate
public class BotRemovedUpdate : Update
{
    // ID чата, где произошло событие
    public long ChatId { get; set; }

    // Пользователь, удаливший бота из чата
    public required User User { get; set; }

    // Указывает, был ли бот удалён из канала или нет
    public bool IsChannel { get; set; }
}

<a id="model-dialogmutedupdate"></a>

  • DialogMutedUpdate
public class DialogMutedUpdate : Update
{
    // ID чата, где произошло событие
    public long ChatId { get; set; }

    // Пользователь, который включил уведомления
    public required User User { get; set; }

    // Время в формате Unix, до наступления которого диалог был отключён
    public DateTime MutedUntil { get; set; }

    // Текущий язык пользователя в формате IETF BCP 47
    public string? UserLocale { get; set; }
}

<a id="model-dialogunmutedupdate"></a>

  • DialogUnmutedUpdate
public class DialogUnmutedUpdate : Update
{
    // ID чата, где произошло событие
    public long ChatId { get; set; }

    // Пользователь, который включил уведомления
    public required User User { get; set; }

    // Текущий язык пользователя в формате IETF BCP 47
    public string? UserLocale { get; set; }
}

<a id="model-dialogclearedupdate"></a>

  • DialogClearedUpdate
public class DialogClearedUpdate : Update
{
    // ID чата, где произошло событие
    public long ChatId { get; set; }

    // Пользователь, который включил уведомления
    public required User User { get; set; }

    // Текущий язык пользователя в формате IETF BCP 47
    public string? UserLocale { get; set; }
}

<a id="model-dialogremovedupdate"></a>

  • DialogRemovedUpdate
public class DialogRemovedUpdate : Update
{
    // ID чата, где произошло событие
    public long ChatId { get; set; }

    // Пользователь, который удалил чат
    public required User User { get; set; }

    // Текущий язык пользователя в формате IETF BCP 47
    public string? UserLocale { get; set; }
}

<a id="model-useraddedupdate"></a>

  • UserAddedUpdate
public class UserAddedUpdate : Update
{
    // ID чата, где произошло событие
    public long ChatId { get; set; }

    // Пользователь, добавленный в чат
    public required User User { get; set; }

    // Пользователь, который добавил пользователя в чат. Может быть null, если пользователь присоединился к чату по ссылке
    public long? InviterId { get; set; }

    // Указывает, был ли пользователь добавлен в канал или нет
    public bool IsChannel { get; set; }
}

<a id="model-userremovedupdate"></a>

  • UserRemovedUpdate
public class UserRemovedUpdate : Update
{
    // ID чата, где произошло событие
    public long ChatId { get; set; }

    // Пользователь, удалённый из чата
    public required User User { get; set; }

    // Администратор, который удалил пользователя из чата. Может быть null, если пользователь покинул чат сам
    public long? AdminId { get; set; }

    // Указывает, был ли пользователь удалён из канала или нет
    public bool IsChannel { get; set; }
}

<a id="model-botstartedupdate"></a>

  • BotStartedUpdate
public class BotStartedUpdate : Update
{
    // ID чата, где произошло событие
    public long ChatId { get; set; }

    // Пользователь, добавивший бота в чат
    public required User User { get; set; }

    // Дополнительные данные из дип-линков, переданные при запуске бота
    public string? Payload { get; set; }

    // Текущий язык пользователя в формате IETF BCP 47
    public string? UserLocale { get; set; }
}

<a id="model-botstoppedupdate"></a>

  • BotStoppedUpdate
public class BotStoppedUpdate : Update
{
    // ID чата, где произошло событие
    public long ChatId { get; set; }

    // Пользователь, добавивший бота в чат
    public required User User { get; set; }

    // Текущий язык пользователя в формате IETF BCP 47
    public string? UserLocale { get; set; }
}

<a id="model-chattitlechangedupdate"></a>

  • ChatTitleChangedUpdate
public class ChatTitleChangedUpdate : Update
{
    // Новое название
    public string? Title { get; set; }
    // ID чата, где произошло событие
    public long ChatId { get; set; }

    // Пользователь, который изменил название
    public required User User { get; set; }
}

<a id="model-updatesresponse"></a>

UpdatesResponse
public class UpdatesResponse
{
    // Страница обновлений
    public Update[]? Updates { get; set; }
    // Указатель на следующую страницу данных, если есть
    public long? Marker { get; set; }
}

<a id="model-uploaddataresponse"></a>

UploadDataResponse
public class UploadDataResponse
{
    // Токен, используемый для прикрепления в AttachmentRequest, не используется при UploadType=Image
    public string? Token { get; set; }

    // Токены, полученные после загрузки изображений, только для UploadType=Image
    public Dictionary<string, UploadedInfo>? Photos { get; set; }
}

<a id="model-uploadedinfo"></a>

UploadedInfo
public class UploadedInfo
{
    // Токен — уникальный ID загруженного медиафайла
    public required string Token { get; set; }
}

<a id="model-uploadurlresponse"></a>

UploadUrlResponse
public class UploadUrlResponse
{
    public required string Url { get; set; }
    
    public string? Token { get; set; } 
}

<a id="model-user"></a>

User
public class User : IEquatable<User>
{
    // int64 - ID пользователя
    public long UserID { get; set; }

    // string - Отображаемое имя пользователя
    public required string FirstName { get; set; } 

    // string [nullable] - Отображаемая фамилия пользователя
    public string? LastName { get; set; }

    // string [nullable] optional - deprecated
    public string? Name { get; set; }

    // string - Уникальное публичное имя пользователя. Может быть null, если пользователь недоступен или имя не задано 
    public string? UserName { get; set; }

    // bool - true, если пользователь является ботом
    public bool IsBot { get; set; }

    // int64 - Время последней активности пользователя в MAX (Unix-время в миллисекундах). Может быть неактуальным, если пользователь отключил статус "онлайн" в настройках.
    public DateTime LastActivityTime { get; set; }
}

<a id="model-userwithphoto"></a>

UserWithPhoto
public class UserWithPhoto : User
{
    // до 16000 символов
    // Описание пользователя или бота. В случае с пользователем может принимать значение null, если описание не заполнено
    public string? Description { get; set; }

    // URL аватара пользователя или бота в уменьшенном размере
    public string? AvatarUrl { get; set; }

    // URL аватара пользователя или бота в полном размере
    public string? FullAvatarUrl { get; set; }
}

<a id="model-videoinfo"></a>

VideoInfo
public class VideoInfo
{
    // Токен видео-вложения
    public required string Token { get; set; }

    // URL-ы для скачивания или воспроизведения видео. Может быть null, если видео недоступно
    public VideoUrls? Urls { get; set; }

    // Миниатюра видео
    public PhotoAttachmentPayload? Thumbnail { get; set; }
    
    // Ширина видео
    public int Width { get; set; }

    // Высота видео
    public int Height { get; set; }

    // Длина видео в секундах
    public int Duration { get; set; }
}

<a id="model-videourls"></a>

VideoUrls
public class VideoUrls
{
    // URL видео в разрешении 1080p, если доступно
    public string? mp4_1080 { get; set; }
    
    // URL видео в разрешении 720p, если доступно
    public string? mp4_720 { get; set; }
    
    // URL видео в разрешении 480p, если доступно 
    public string? mp4_480 { get; set; }

    // URL видео в разрешении 360p, если доступно 
    public string? mp4_360 { get; set; }

    // URL видео в разрешении 240p, если доступно 
    public string? mp4_240 { get; set; }

    // URL видео в разрешении 144p, если доступно 
    public string? mp4_144 { get; set; }

    // URL трансляции, если доступна
    public string? HLS { get; set; } 
}

<a id="model-contactattachmentpayload"></a> <a id="model-contactattachmentrequestpayload"></a> <a id="model-fileattachmentpayload"></a> <a id="model-inlinekeyboardattachmentrequestpayload"></a> <a id="model-mediaattachmentpayload"></a> <a id="model-photoattachmentpayload"></a> <a id="model-photoattachmentrequestpayload"></a> <a id="model-shareattachmentpayload"></a> <a id="model-stickerattachmentpayload"></a> <a id="model-stickerattachmentrequestpayload"></a> <a id="model-videothumbnail"></a>

VideoThumbnail
public class VideoThumbnail
{
    public required string Url { get; set; }
}
Внимание!!! На текущий момент в API нет метода для разблокировки заблокированных пользователей, пока это могут делать только администраторы вручную (Ticket: 4009805)

<a id="enums"></a>

Перечисления типов

<a id="enum-attachmenttype"></a>

AttachmentType
public enum AttachmentType
{
    Image,
    Video,
    Audio,
    File,
    Sticker,
    Contact,
    InlineKeyboard,
    Share,
    Location,
}

<a id="enum-buttontype"></a>

ButtonType
public enum ButtonType
{
    // Кнопка обработки события
    Callback,
    // Кнопка-ссылка
    Link,
    // Кнопка запроса геолокации
    RequestGeoLocation,
    // Кнопка запроса контакта
    RequestContact,
    // Кнопка открытия приложения
    OpenApp,
    // Кнопка сообщения (текст кнопки будет использован как выбор ответа в сообщении при нажатии)
    Message,
    // Кнопка, содержимое которой копируется в буфер обмена
    Clipboard
}

<a id="enum-chatadminpermissions"></a>

ChatAdminPermissions
public enum ChatAdminPermission
{
    ReadAllMessages,
    AddRemoveMembers,
    AddAdmins,
    ChangeChatInfo,
    PinMessage,
    Write,
    CanCall,
    EditLink,
    PostEditDeleteMessage,
    EditMessage,
    DeleteMessage,
    ViewStats,
    Delete,
    Edit   
}

<a id="enum-chatstatus"></a>

ChatStatus
public enum ChatStatus
{
    Active,
    Removed,
    Left,
    Closed
}

<a id="enum-chattype"></a>

ChatType
public enum ChatType
{
    // групповой чат
    Chat,
    // личные сообщения
    Dialog,
    // канал
    Channel

<a id="enum-markupelementtype"></a>

MarkupElementType
public enum MarkupElementType
{
    // жирный
    Strong ,
    // курсив
    Emphasized,
    // моноширинный
    Monospaced,
    // ссылка
    Link,
    // зачеркнутый
    Strikethrough,
    // подчеркнутый
    Underline, 
    // упоминание пользователя
    UserMention
}

<a id="enum-messagelinktype"></a>

MessageLinkType
public enum MessageLinkType
{
    // Пересланное сообщение
    Forward,
    // Ответ на сообщение
    Reply
}

<a id="enum-senderaction"></a>

SenderAction
public enum SenderAction
{
    // печатает...
    TypingOn,
    // отправляет фото..
    SendingPhoto,
    // отправляет видео...
    SendingVideo,
    // отправляет аудио/голосовое
    SendingAudio,
    // отправляет файл
    SendingFile,
    // отмечает сообщения прочитанными
    MarkSeen
}

<a id="enum-textformat"></a>

TextFormat
public enum TextFormat
{
    Markdown,
    HTML
}

<a id="enum-updatetype"></a>

UpdateType
public enum UpdateType
{
    // Новое сообщение
    MessageCreated,
    // Событие callback (нажата кнопка)
    MessageCallback,
    // Сообщение отредактировано
    MessageEdited,
    // Сообщение удалено
    MessageRemoved,
    // Бот добавлен в группу
    BotAdded,
    // Бот исключен из группы
    BotRemoved,
    // Уведомления в диалоге отключены
    DialogMuted,
    // Уведомления в диалоге включены
    DialogUnmuted,
    // Диалог очищен (все сообщения удалены)
    DialogCleared,
    // Диалог удален
    DialogRemoved,
    // Пользователь добавлен в группу 
    UserAdded,
    // Пользователь удален из группы
    UserRemoved,
    // Начат диалог с ботом
    BotStarted,
    // Прекращен диалог с ботом
    BotStopped,
    // Произошла смена названия группы
    ChatTitleChanged
}

<a id="enum-uploadtype"></a>

UploadType
public enum UploadType
{
    // image: JPG, JPEG, PNG, GIF, TIFF, BMP, HEIC
    Image,
    // video: MP4, MOV, MKV, WEBM, MATROSKA
    Video,
    // audio: MP3, WAV, M4A и другие
    Audio,
    // file: любые типы файлов
    File
}

<a id="example"></a>

Пример для minimal api (webhook)

using MaxBot;
using MaxBotApi;
using MaxBotApi.Enums;
using MaxBotApi.Models;
string token = "токен бота";
string webhookUrl = "https://адресвашегобота/bot";
string secret = "проверочныйкод"; // этим кодом будет сопровождаться каждый запрос от платформы
var bot = new MaxBotClient(token);
await bot.SetWebhook(webhookUrl, secret);

var builder = WebApplication.CreateBuilder(args);
builder.Services.ConfigureHttpJsonOptions(options => { options.SerializerOptions.PropertyNamingPolicy = null; });
builder.Services.AddHttpClient("maxwebhook").RemoveAllLoggers().AddTypedClient(httpClient => bot);

var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.MapPost("/bot", HandleUpdate);
app.Run();
await bot.DeleteWebhook(webhookUrl);

async Task HandleUpdate(MaxBotClient _bot, Update update)
{
    switch (update)
    {
        case MessageEditedUpdate meu:
            await Task.Run(async () => await ProcessMessage(meu.Message, null));
            return;
        case MessageCreatedUpdate mcu:
            await Task.Run(async () => await ProcessMessage(mcu.Message, mcu.UserLocale));
            return;
        case BotRemovedUpdate:
        case BotAddedUpdate:
        case ChatTitleChangedUpdate:
        case MessageCallbackUpdate:
        case UserAddedUpdate:
        case UserRemovedUpdate:
        case MessageRemovedUpdate:
        case DialogMutedUpdate:
        case DialogUnmutedUpdate:
        case DialogClearedUpdate:
        case DialogRemovedUpdate:
        case BotStartedUpdate:
        case BotStoppedUpdate:
            break;
    }
}


async Task ProcessMessage(Message message, string? userLocale)
{
    if (string.IsNullOrEmpty(message.MessageBody?.Text)) return;
    if (message.Recipient.ChatType == ChatType.Dialog)
    {
        await bot.SendMessage(message.Sender.UserID, message.MessageBody?.Text);
    } else if (message.Recipient.ChatType == ChatType.Chat)
    {
        // пример отправки ботом картинки test.png в ответ на слово test
        if (message.MessageBody.Text is "test")
        {
            try
            {
                var data = await bot.UploadFile(UploadType.Image, "test.png");
                if (data.Photos is not null)
                {
                    List<AttachmentRequest> attachments = [];
                    foreach (var photo in data.Photos)
                    {
                        attachments.Add(new ImageAttachmentRequest()
                        {
                            Payload = new PhotoAttachmentRequestPayload() { Token = photo.Value.Token }
                        });
                    }

                    await bot.SendMessageToChat(message.Recipient.ChatId, "reply", false, false, TextFormat.HTML,
                        new NewMessageLink() { MessageId = message.MessageBody.MessageId, Type = MessageLinkType.Reply },
                        attachments);
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message)
            }
        } else {
            await bot.SendMessageToChat(message.Recipient.ChatId, message.MessageBody?.Text);
        }        
    }    
}

<a id="example2"></a>

Минимальный рабочий пример long-polling исполнения:
using MaxBotApi;
using MaxBotApi.Enums;
using MaxBotApi.Models;

CancellationTokenSource cts = new();
string botToken = "токен вашего бота";
MaxBotClient  bot = new(botToken, cancellationToken: cts.Token);

EventWaitHandle waitHandle = new(false, EventResetMode.AutoReset, null, out bool createdNew);
bool signaled;

bot.OnError += OnError;
bot.OnMessage += OnMessage;
bot.OnUpdate += OnUpdate;

var me = await bot.GetMe();
Console.WriteLine(string.Format("@{0} запущен... Наберите 'shutdown' в лс боту для завершения", me.FirstName));
if (!createdNew)
    waitHandle.Set();
else
    do { signaled = waitHandle.WaitOne(TimeSpan.FromMilliseconds(33)); }
    while (!signaled);

cts.Cancel(); // stop the bot
Console.WriteLine("exit!");

async Task OnError(Exception exception, HandleErrorSource source)
{
    Console.WriteLine(exception.ToString());
    await Task.CompletedTask;
}

async Task OnUpdate(Update update)
{
    Console.WriteLine(update);
    await Task.CompletedTask;
}

async Task OnMessage(Message msg, UpdateType type)
{
    if (msg.MessageBody?.Text == "shutdown")
    {
        waitHandle.Set();
    }
    Console.WriteLine(msg);
    await Task.CompletedTask;
}
Данный клиент будет постепенно дорабатываться, документация дополняться.
По любым вопросам, связанным с данным кодом и документацией к нему, можно писать мне в MAX

🔗 MaxBotApi - Группа разработки

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

  • net10.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.15 24 4/9/2026
1.0.14 101 3/30/2026
1.0.13.1 90 3/29/2026
1.0.13 91 3/26/2026
1.0.12.1 84 3/26/2026
1.0.12 89 3/22/2026
1.0.11 105 3/18/2026
1.0.10 200 3/6/2026
1.0.9 184 3/1/2026
1.0.8.1 90 2/27/2026
1.0.8 90 2/26/2026
1.0.7 92 2/24/2026
1.0.6 92 2/22/2026
1.0.5 93 2/21/2026
1.0.4 92 2/21/2026
1.0.3 92 2/20/2026
1.0.2 87 2/20/2026
1.0.1 92 2/19/2026
1.0.0 90 2/19/2026