Max Bot API Client

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

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

[!WARNING] По умолчанию session() хранит данные только в памяти процесса. При остановке, падении или перезапуске бота все сессии и незавершённые сценарии будут потеряны. Для одного процесса можно подключить SQLite, а для нескольких экземпляров — общее хранилище, например Redis или серверную базу данных.

Быстрый старт

Если вы новичок, то можете прочитать официальную документацию, написанную разработчиками Max.

Получение токена

Откройте диалог с Master Bot, следуйте инструкциям и создайте нового бота. После создания бота Master Bot отправит вам токен.

Установка

npm

npm install @maxhub/max-bot-api

yarn

yarn add @maxhub/max-bot-api

pnpm

pnpm add @maxhub/max-bot-api

Пример

import { Bot } from '@maxhub/max-bot-api';

const bot = new Bot(process.env.BOT_TOKEN);

// Установка подсказок с доступными командами
bot.api.setMyCommands([
  { 
    name: 'ping',
    description: 'Сыграть в пинг-понг'
  },
]);

// Обработчик события запуска бота
bot.on('bot_started', (ctx) => ctx.reply('Привет! Отправь мне команду /ping, чтобы сыграть в пинг-понг'));

// Обработчик команды '/ping'
bot.command('ping', (ctx) => ctx.reply('pong'));

// Обработчик для сообщения с текстом 'hello'
bot.hears('hello', (ctx) => ctx.reply('world'));

// Обработчик для всех остальных входящих сообщений
bot.on('message_created', (ctx) => ctx.reply(ctx.message.body.text));

bot.start();

Пользовательский fetch

Можно передать собственную реализацию fetch для запросов Bot API:

const bot = new Bot(token, {
  clientOptions: {
    fetch: customFetch,
  },
});

clientOptions.fetch используется только API-клиентом Bot API. Через него проходят обычные API-запросы, например /me, /updates, /messages, а также запрос за upload URL через /uploads.

Эта настройка не влияет на загрузку содержимого файлов через StreamUploadClient: после получения upload URL от Bot API фактическая загрузка локального файла на этот URL выполняется отдельным транспортом на базе http/https.request.

Поэтому clientOptions.fetch не следует считать полноценной поддержкой proxy для всего исходящего трафика SDK.

Обработка ошибок

Если во время обработки события произойдёт ошибка, Bot вызовет метод bot.handleError. По умолчанию bot.handleError просто завершает работу программы, но вы можете переопределить это поведение, используя bot.catch.

⚠️ Завершайте работу программы при неизвестных ошибках, иначе бот может зависнуть в состоянии ошибки.

ℹ️ pm2 может автоматически перезапустить вашего бота, если он остановится по какой-либо причине.