Работа с библиотекой JavaScript

MAX предоставляет официальную библиотеку на JavaScript/TypeScript — она находится в открытом доступе на GitHub и закрывает всю рутину взаимодействия с Bot API. Если ты пишешь на Node.js — это твой выбор по умолчанию.

GitHub: github.com/max-messenger/max-bot-api-client-ts

Честно скажу: когда я начинал писать «Мои друзья», этой библиотеки ещё не было, и я всё делал через чистый fetch. Сейчас бы я взял её не раздумывая — типизация TypeScript сама по себе экономит часы отладки.

Установка

Библиотека доступна через npm. Установить проще простого:

npm install @max-ru/bot-api-client

Или через yarn:

yarn add @max-ru/bot-api-client

Базовое использование

Вот минимальный работающий пример — бот отвечает «Привет!» на любое сообщение. Обрати внимание: библиотека сама парсит входящие события и предоставляет удобные методы для отправки ответов.

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

const bot = new Bot({
    token: process.env.MAX_BOT_TOKEN,
});

bot.on('message', async (ctx) => {
    await ctx.reply(`Привет, ${ctx.from?.first_name}! 👋`);
});

bot.start();

Библиотека поддерживает все методы Bot API: отправку сообщений, работу с клавиатурами, файлы, чаты, колбэки. Под капотом — типизированные запросы, автоматический retry, обработка ошибок.

Как я советую структурировать проект

На основе своего опыта — вот структура, которая не превратится в кашу, когда бот вырастет:

my-max-bot/
├── src/
│   ├── index.ts          ← точка входа, инициализация бота
│   ├── handlers/
│   │   ├── commands.ts   ← обработка команд (/start, /help)
│   │   ├── messages.ts   ← обработка текстовых сообщений
│   │   └── callbacks.ts  ← обработка inline-колбэков
│   ├── keyboards/
│   │   └── index.ts      ← все клавиатуры в одном месте
│   ├── services/
│   │   ├── api.ts        ← внешние API-интеграции
│   │   └── db.ts         ← работа с базой данных
│   └── config.ts         ← конфигурация (токен, настройки)
├── package.json
├── tsconfig.json
└── .env

Не пихай всё в один файл. Даже если кажется «да тут всего 100 строк». Через месяц это будет 2000 строк, и разбираться будет больно. Разделяй сразу.

Подробная документация

Полную документацию по всем методам библиотеки смотри на GitHub — там описаны все классы, методы и типы. А примеры использования (включая более сложные сценарии) я собрал на странице Примеры создания ботов.

Если пишешь на Go — у MAX есть библиотека для Golang.