maxbot-api-client-ts

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 maxbot-api-client-ts

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

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

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

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

import { MaxBotAPI } from '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