Для разработчиков

Привет! Меня зовут Алексей Чуркин, я разработал бота «Мои друзья» для мессенджера MAX. Если ты тоже хочешь создать своего бота — ты попал по адресу.

Когда я начинал, мне пришлось перелопатить кучу документации, набить шишки на реальных ошибках и провести не одну бессонную ночь за отладкой. В этом разделе я собрал всё, что реально пригодилось мне — от первого «Hello, World!» до продакшен-бота с тысячами пользователей.

Здесь ты найдёшь не сухие спецификации, а живые примеры из моей практики. Я расскажу, как устроен API MAX, как обрабатывать колбэки, строить клавиатуры, работать с чатами и файлами. И главное — как не наступить на грабли, на которые наступал я.

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

Вот минимальный код, чтобы запустить бота в MAX. Я использую Node.js, потому что на нём написан мой бот — но API вызывается обычными HTTP-запросами, так что подойдёт любой язык.

1. Получи токен

Зайди в настройки своего бота в личном кабинете MAX для бизнеса и скопируй токен. Он выглядит примерно так:

abc123def456ghi789jkl012mno345pqr678stu901vwx234

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

Базовый запрос к API MAX — проще некуда:

const TOKEN = 'твой_токен_бота';
const CHAT_ID = 'id_чата_или_пользователя';

await fetch(`https://api.max.ru/bot/${TOKEN}/sendMessage`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        chat_id: CHAT_ID,
        text: 'Привет! Я твой первый бот в MAX 🚀'
    })
});

3. Настрой вебхук

Чтобы бот реагировал на сообщения, нужно принимать входящие запросы. Я использую вебхук — MAX будет отправлять POST-запросы на твой сервер при каждом событии:

// Пример обработчика на Express
app.post('/webhook', express.json(), async (req, res) => {
    const { user_id, payload, text } = req.body;

    if (text === '/start') {
        await sendMessage(user_id, 'Добро пожаловать! 👋');
    }

    res.sendStatus(200); // обязательно ответь 200!
});

Как устроен мой бот

Чтобы ты понимал архитектуру реального бота, вот упрощённая схема «Мои друзья»:

мой-сервер/
├── bot.js          ← точка входа, вебхук, роутинг колбэков
├── keyboard.js     ← все клавиатуры (inline + reply)
├── database.js     ← SQLite: пользователи, мэтчи, жалобы
├── matching.js     ← алгоритм подбора по интересам
├── safety.js       ← фильтр мата, модерация, жалобы
├── tasks.js        ← система заданий и бонусов
└── virtual-friend.js ← нейросетевой друг с памятью

Каждый модуль — отдельный файл. bot.js — диспетчер: получает событие, определяет тип (команда, колбэк, сообщение) и передаёт нужному обработчику.

Почему SQLite, а не PostgreSQL?

Когда я начинал, мне нужно было быстро прототипировать без поднятия отдельной базы. SQLite работает прямо в процессе Node.js, не требует настройки и справляется с тысячами пользователей. Для старта — идеально. Если пользователей станет сильно больше — мигрируешь на PostgreSQL, заменив одну строчку подключения.

Работа с клавиатурами

Клавиатуры — это то, с чем ты будешь работать чаще всего. В MAX есть два типа:

Inline-клавиатура (под сообщением)

Кнопки прикрепляются к конкретному сообщению. При нажатии бот получает колбэк с данными — не новое текстовое сообщение, а структурированный payload:

const keyboard = {
    inline: [
        [{ text: '🔍 Найти друзей', callback: 'find_match' }],
        [
            { text: '👤 Анкета', callback: 'my_profile' },
            { text: '👥 Друзья', callback: 'my_matches' }
        ],
        [{ text: '⚙️ Настройки', callback: 'settings' }]
    ]
};