MAX BOT API Client (TypeScript)

maxbot-api-client-ts — это современный TypeScript SDK для интеграции с MAX BOT API. Библиотека предоставляет строго типизированный интерфейс для управления ботами, сообщениями, чатами и медиафайлами, а также поддерживает работу через long-polling и вебхуки.

Для использования библиотеки потребуется получить токен бота в консоли разработчика MAX bot.
Ознакомиться с инструкцией можно по ссылке.

API

Документацию по REST API MAX можно найти по ссылке dev.max.ru/docs-api. Библиотека является оберткой для REST API, поэтому документация по указанной выше ссылке также применима к используемым здесь моделям.

Документацию по MAX BOT API можно найти по ссылке green-api.com/max-bot-api/docs.

Поддержка

Руководства и новости

Установка

Убедитесь, что у вас установлена версия Node.js версии не ниже 18

node -v

npm -v

Установите библиотеку:

npm install @green-api/maxbot-api-client-ts

Использование и примеры

Параметры конфигурации:

• base_url - Базовый URL-адрес серверов платформы MaxBot. Все методы API будут маршрутизироваться по этому корневому адресу. Актуальный адрес указан в официальной документации.
• token - Уникальный секретный ключ авторизации (API-ключ) вашего бота. Получить его можно в личном кабинете после регистрации или создании бота на платформе business.max.ru.
• ratelimiter - Встроенный ограничитель частоты запросов. Он контролирует количество исходящих запросов в секунду (RPS), защищая бота от блокировки со стороны сервера за превышение лимитов. Рекомендуемое значение — не менее 25.
• timeout - Максимальное время ожидания ответа от сервера (в секундах). Если сервер не ответит в течение этого времени, запрос будет завершен с ошибкой. Оптимальное значение — 30 секунд.

Как инициализировать клиент:

import { MaxBotAPI } from '@green-api/maxbot-api-client-ts';

const response = new MaxBotAPI({
    base_url: "https://platform-api.max.ru",
    token: "YOUR_BOT_TOKEN",
    ratelimiter: 25,
    timeout: 30000
});

Как получить информацию о боте:

Ссылка на пример: getBot/main.ts

const response = await bot.bots.getBot();

Как отправить сообщение:

Ссылка на пример: sendMessage/main.ts

await bot.messages.sendMessage({
    user_id: 123456789,
    text: "Hello world!",
});

Как легко отправить файл (по ссылке или локальный):

Метод helpers.sendFile сам определит тип источника и загрузит файл на сервер, если это необходимо.

Ссылка на пример: sendFile/main.ts

await bot.helpers.sendFile({
    chat_id: 123456789,
    file_source: "./documents/report.pdf",
});

await bot.helpers.sendFile({
    chat_id: 123456789,
    file_source: "https://example.com/image.png",
});

Как получить входящее уведомление:

Ссылка на пример: getUpdates/main.ts

const response = await bot.subscriptions.getUpdates({
    timeout: 25,
    marker: marker,
    types: [UpdateType.MessageCreated]
});

Список примеров

| Описание | Ссылка на пример | |--------------------------------------|----------------------------------------------------------| | Как отправить сообщение | sendMessage/main.ts | | Как получить информацию о боте | getBot/main.ts | | Как отправить файл | sendFile/main.ts | | Как загрузить файл | uploadFile/main.ts | | Как получить входящее уведомление | getUpdates/main.ts |

Список всех методов библиотеки

| Метод API | Описание | Ссылка на документацию MAX | Ссылка на документацию MAX BOT API | |-----------------|-------------------------|------------------------------------------------|----------------------------------------------| | bots.getBot | Получает информацию о боте | getBot | GetBot | | bots.patchBot | Изменяет информацию о боте | | patchBot | | chats.getChats | Возвращает список групповых чатов, в которых участвовал бот | getChats | GetChats | | chats.getChat | Возвращает информацию о групповом чате по его ID | getChat | GetChat | | chats.editChat | Позволяет редактировать информацию о групповом чате | editChat | EditChat | | chats.deleteChat | Удаляет групповой чат для всех участников | deleteChat | DeleteChat | | chats.sendAction | Позволяет отправлять следующие действия бота в групповой чат | sendAction | SendAction | | chats.getPinnedMessage | Возвращает закрепленное сообщение в чате | getPinnedMessage | GetPinnedMessage | | chats.pinMessage | Закрепляет сообщение в групповом чате | pinMessage | PinMessage | | chats.unpinMessage | Удаляет закрепленное сообщение в групповом чате | unpinMessage | UnpinMessage | | chats.getChatMembership | Возвращает членство бота в групповом чате | getChatMembership | GetChatMembership | | chats.leaveChat | Удаляет бота из группового чата | leaveChat | LeaveChat | | chats.getChatAdmins | Возвращает список всех администраторов группового чата | getChatAdmins | GetChatAdmins | | chats.setChatAdmins | Назначает участника группы администратором | setChatAdmins | SetChatAdmins | | chats.deleteAdmin | Отменяет права администратора пользователя в групповом чате | deleteAdmin | DeleteAdmin | | chats.getChatMembers | Возвращает список участников группового чата | getChatMembers | GetChatMembers | | chats.addMembers | Добавляет участников в групповой чат | addMembers | AddMembers | | chats.deleteMember | Удаляет участника из группового чата | deleteMember | DeleteMember | | subscriptions.getSubscriptions | Возвращает список подписок на уведомления веб-хуков | getSubscriptions | GetSubscriptions | | subscriptions.subscribe | Настраивает доставку событий бота через веб-хук | subscribe | Subscribe | | subscriptions.unsubscribe | Отменяет подписку бота на получение обновлений через веб-хук | unsubscribe | Unsubscribe | | subscriptions.getUpdates | Получает входящие обновления | getUpdates | GetUpdates | | upload.uploadFile | Загружает файл на серверы MAX для последующей передачи | uploadFile | UploadFile | | helpers.sendFile | Упрощает отправку файлов, автоматически определяя URL или путь | | SendFile | | messages.getMessages | Возвращает информацию о сообщении или массив сообщений из чата | getMessages | GetMessages | | messages.sendMessage | Отправляет текстовое или медиа-сообщение указанному пользователю или в чат | sendMessage | SendMessage | | messages.editMessage | Редактирует текст или медиафайл ранее отправленного сообщения | editMessage | EditMessage | | messages.deleteMessage | Удаляет сообщение из чата | deleteMessage | DeleteMessage | | messages.getMessage | Извлекает содержимое и метаданные конкретного сообщения по его ID | getMessage | GetMessage | | messages.getVideoInfo | Возвращает подробную информацию о прикрепленном видео | getVideoInfo | GetVideoInfo | | messages.answerCallback | Отправляет ответ после того, как пользователь нажмет кнопку | answerCallback | AnswerCallback|

Лицензия

MIT