Библиотека MAX Bot API

Если вы пишете ботов на TypeScript или JavaScript, рекомендуем использовать нашу официальную библиотеку MAX Bot API. Расширенную версию библиотеки с примерами реализации смотрите на GitHub

В этом разделе разберём как подключить библиотеку MAX Bot API и эффективно использовать инструменты, разные стандартные методы и утилиты, которыми она располагает

Устанавливаем MAX Bot API

Чтобы установить библиотеку MAX Bot API, зарегистрируйте бота в MAX и подключитесь к API MAX — следуйте подсказкам в разделе «Подготовка и управление»

Все примеры в этом разделе написаны на JavaScript с переменными окружения в Node.js 1. Создайте новый проект в терминале и установите библиотеку для своего менеджера пакетов. Используйте скрипт curl или wget

BASH

# Создайте папку и перейдите в неё
mkdir my-first-bot
cd my-first-bot


# Установите MAX Bot API

# Для npm
npm install --save @maxhub/max-bot-api
# Для yarn
yarn add @maxhub/max-bot-api
# Для pnpm
pnpm add @maxhub/max-bot-api
# Для deno
deno add npm:@maxhub/max-bot-api

# Установите и настройте TypeScript (опционально)
yarn add -D typescript
npx tsc --init

2. Создайте файл. Для JavaScript — bot.js, для TypeScript — bot.ts

3. Создайте экземпляр класса Bot и передайте токен из @MasterBot в его конструктор через переменные окружения, можно использовать библиотеку dotenv

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

// Создайте экземпляр класса Bot и передайте ему токен 
const bot = new Bot(process.env.BOT_TOKEN);

// Добавьте слушатели обновлений
// MAX Bot API будет вызывать их, когда пользователи взаимодействуют с ботом

// Обработчик для команды '/start'
bot.command('start', (ctx) => ctx.reply('Добро пожаловать!'));

// Обработчик для любого другого сообщения
bot.on('message_created', (ctx) => ctx.reply('Новое сообщение'));

// Теперь можно запустить бота, чтобы он подключился к серверам MAX и ждал обновлений
bot.start();

bot.js

4. Запустите бота

BASH

# Скомпилируйте код, если вы использовали TypeScript
npx tsc

# Передайте переменную окружения и запустите бота
BOT_TOKEN="<your_token_here>" node bot.js

Работаем с обновлениями

После запуска вы начнёте получать обновления от MAX — следите за подсказками в редакторе кода. MAX Bot API позволяет прослушивать эти обновления

// Обработчик начала диалога с ботом
bot.on('bot_started', (ctx) => {/* ... */});

// Обработчик новых сообщений
bot.on('message_created', (ctx) => {/* ... */});

// Обработчик добавления пользователя в беседу
bot.on('user_added', (ctx) => {/* ... */});

Входящие сообщения

Вы можете подписаться на обновления message_created

bot.on('message_created', (ctx) => {
  const message = ctx.message; // Полученное сообщение
});

Или воспользуйтесь специальными методами

// Обработчик команды '/start'
bot.command('start', async (ctx) => {/* ... */});

// Сравнение текста сообщения со строкой или регулярным выражением
bot.hears('hello', async (ctx) => {/* ... */});
bot.hears(/echo (.+)?/, async (ctx) => {/* ... */});

// Обработчик нажатия на callback-кнопку с указанным payload
bot.action('connect_wallet', async (ctx) => {/* ... */});
bot.action(/color:(.+)/, async (ctx) => {/* ... */});

Исходящие сообщения

Воспользуйтесь методами из bot.api

// Отправить сообщение пользователю с id=12345
await bot.api.sendMessageToUser(12345, "Привет!");
// Опционально можно передать дополнительные параметры
await bot.api.sendMessageToUser(12345, "Привет!", {/* доп. параметры */});

// Отправить сообщение в чат с id=54321
await bot.api.sendMessageToChat(54321, "Всем привет!");

// Получить отправленное сообщение
const message = await bot.api.sendMessageToUser(12345, "Привет!");
console.log(message.body.mid);

Если MAX Bot API не поддерживает какой-то метод, вызовите его через ctx.api.raw

Форматы методов Raw API

ctx.api.raw.get('method', {/* параметры запроса */});
ctx.api.raw.post('method', {/* параметры запроса */});
ctx.api.raw.put('method', {/* параметры запроса */});
ctx.api.raw.patch('method', {/* параметры запроса */});
ctx.api.raw.delete('method', {/* параметры запроса */});
// Вызов метода редактирования чата с id=123
await ctx.api.raw.patch('chats/{chat_id}', {  
    path: { chat_id: 123 }, // Параметры ссылки
    body: { title: 'New Title' }, // Тело запроса
    query: { notify: false }, // Параметры поиска
});

Можно обратиться к методу контекста reply

bot.hears('ping', async (ctx) => {
    // 'reply' — псевдоним метода 'ctx.api.sendMessageToChat' в этом же чате
    await ctx.reply('pong', {
        // 'link' прикрепляет оригинальное сообщение
        link: { type: 'reply', mid: ctx.message.body.mid },
    });
});

Форматирование сообщений

Чтобы выделить в сообщениях важную информацию, используйте разные способы оформления текста — жирный шрифт, курсив, ссылки и другое. Есть два типа форматирования — Markdown и HTML

Markdown

await bot.api.sendMessageToChat(
  12345,
  '**Привет!** _Добро пожаловать_ в [MAX](https://dev.max.ru).',
  { format: 'markdown' },
);

HTML

await bot.api.sendMessageToChat(
  12345,
  '<b>Привет!</b> <i>Добро пожаловать</i> в <a href="https://dev.max.ru">MAX</a>.',
  { format: 'html' },
);

Подробности про форматирование смотрите в официальной документации.

Отправляем вложения

Упростите работу с вложениями классом Attachment. Благодаря функции toJson объект вложения будет возвращаться отформатированным

Файлы

С помощью токена — для файлов, которые уже загружены в MAX

const image = new ImageAttachment({ token: 'existingImageToken' });
await ctx.reply('', { attachments: [image.toJson()] });
const video = new VideoAttachment({ token: 'existingVideoToken' });
await ctx.reply('', { attachments: [video.toJson()] });
const audio = new AudioAttachment({ token: 'existingAudioToken' });
await ctx.reply('', { attachments: [audio.toJson()] });
const file = new FileAttachment({ token: 'existingFileToken' });
await ctx.reply('', { attachments: [file.toJson()] });

Чтобы загрузить файлы на серверы MAX, воспользуйтесь методом ctx.api

uploadImage
uploadVideo
uploadAudio
uploadFile

Загруженные файлы возвращают экземпляр класса Attachment

const image = await ctx.api.uploadImage({ source: '/path/to/image' });
await ctx.reply('Это фото загружено из файла', {
  attachments: [image.toJson()],
});

С помощью ссылки — доступно только для изображений

const image = await ctx.api.uploadImage({ url: 'https://upload.wikimedia.org/wikipedia/commons/7/72/Maxmessenger.png' });
await ctx.reply('', { attachments: [image.toJson()] });

Другие типы вложений

const sticker = new StickerAttachment({ code: "stickerCode" });
await ctx.reply('', { attachments: [sticker.toJson()] });

const location = new LocationAttachment({ lon: 0, lat: 0 });
await ctx.reply('', { attachments: [location.toJson()] });

const share = new ShareAttachment({ url: "messagePublicUrl", token: "attachmentToken" });
await ctx.reply('', { attachments: [share.toJson()] });

Клавиатура

Клавиатура отображается в сообщениях бота и похожа на пульт управления. Пользователям не нужно печатать ответ на запрос, достаточно нажать на кнопку. Параметры и оформление клавиатуры можно настроить — используйте KeyboardBuilder

const keyboard = Keyboard.inlineKeyboard([
  // Первая строка с тремя кнопками
  [
    Keyboard.button.callback('default'),
    Keyboard.button.callback('positive', { intent: 'positive' }),
    Keyboard.button.callback('negative', { intent: 'negative' }),
  ], 
  // Вторая строка с одной кнопкой
  [Keyboard.button.link('Открыть MAX', 'https://max.ru')],
]);

Параметры клавиатуры по умолчанию

Чтобы клавиатура оставалась удобной для пользователей, рекомендуем заранее продумать её наполнение и учитывать следующие параметры:

Текст на кнопке выравнивается по центру и обрезается, если выходит за её границы
Кнопки в одной строке должны быть одинаковой ширины
Ширина каждого ряда кнопок равна ширине клавиатуры
Высота у всех кнопок по умолчанию одинаковая

Inline-клавиатура

Такая клавиатура может иметь до 210 кнопок, сгруппированных в 30 рядов — до 7 кнопок в каждом. Если ряды кнопок не помещаются в плейсхолдер клавиатуры, автоматически подключается скролл

Inline-клавиатура в чат-боте

Типы кнопок

Кнопки для клавиатуры различаются по типу

Callback
Информирует сервер о действиях в чат-боте и вызывает обновление message_callback

TYPESCRIPT

button.callback(text: string, payload: string, extra?: { 
  intent?: 'default' 
});

Link Позволяет открыть ссылку в новой вкладке

TYPESCRIPT

button.link(text: string, url: string);

RequestContact Запрашивает разрешение на доступ к контактам телефонной книги, чтобы пользователь мог отправить в чат телефон или ник

TYPESCRIPT

button.requestContact(text: string);

RequestGeoLocation Открывает окно с информацией о местоположении пользователя, чтобы он мог поделиться координатами в чате

TYPESCRIPT

button.requestGeoLocation(text: string, extra?: { quick?: boolean });

Chat Позволяет создать новый групповой чат для бота и пользователя

TYPESCRIPT

button.chat(text: string, chatTitle: string, extra?: { 
  chat_description?: string | null;
  start_payload?: string | null;
  uuid?: string | null; 
});

Расширяем контекст

TYPESCRIPT

interface MyContext extends Context {
  isAdmin?: boolean;
}
const ADMIN_ID = 12345;
const bot = new Bot<MyContext>(process.env.BOT_TOKEN);
bot.use(async (ctx, next) => {
  ctx.isAdmin = ctx.user?.user_id === ADMIN_ID;
  return next();
});
bot.command('start', async (ctx) => {
  if (ctx.isAdmin) {
        return ctx.reply('Привет, админ!');

  }
  return ctx.reply('Привет!');
});

Если у вас возникли вопросы, посмотрите раздел с ответами