MAX BOT API Demo chatbot (TypeScript)

Пример чат-бота, написанного на TypeScript с использованием SDK maxbot-chatbot-ts и maxbot-api-client-ts от GREEN-API.

Этот чат-бот демонстрирует возможности MAX API по отправке текстовых сообщений, медиафайлов (картинки, аудио, видео, PDF), геолокаций и контактов с использованием системы сцен и интерактивных кнопок.

Содержание

• Установка среды для запуска
• Настройка чат-бота
• Использование
• Структура кода
• Управление сообщениями
• Лицензия

Установка среды для запуска

Для работы бота требуется Node.js версии 20.x или выше. Скачать актуальную версию можно с официального сайта nodejs.org.

Проверьте корректность установки, введя в терминале:

node --version

Клонирование проекта

Скачайте репозиторий и перейдите в папку проекта:

git clone https://github.com/green-api/maxbot-demo-chatbot-ts
cd maxbot-demo-chatbot-ts

Установка зависимостей

Установите необходимые пакеты с помощью npm:

npm install

Запуск чат-бота

Для интеграции с MAX API вам понадобятся параметры доступа:

BASE_URL // базовый адрес отправки запросов (например, https://platform-api.max.ru)
TOKEN    // токен для бота MAX

1. Создайте файл .env в корневой директории проекта.
2. Добавьте в него ваши данные:

BASE_URL=https://platform-api.max.ru
TOKEN=1A2B3C4D5E6F7G8H9I0J9K8L7M6N5O4P3Q3R2S1T2U3V4W5X6Y7Z

3. Запустите бота с помощью tsx (выполняет TypeScript без предварительной компиляции):

npx tsx src/main.ts

Программа инициализирует клиент, настроит менеджер состояний и запустит polling для получения уведомлений в реальном времени. Для остановки нажмите Ctrl + C.

Настройка чат-бота

Вы можете изменить медиафайлы, которые бот отправляет пользователям. Ссылки на файлы находятся в файле src/endpoints.ts.

Например, для изменения PDF-файла найдите следующий блок:

case "2":
case "/file":
    await n.showAction("sending_file");
    await n.replyWithMedia(
        T(lang, "send_file_message") + T(lang, "links.send_file_documentation"),
        "https://storage.yandexcloud.net/sw-prod-03-test/ChatBot/corgi.pdf",
        Format.Markdown,
        this.getControlButtons(lang)
    );
    break;

Замените URL "https://storage.yandexcloud.net/.../corgi.pdf" на прямую ссылку вашего файла.

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

Если предыдущие шаги были выполнены, ваш бот будет готов к приему сообщений.

Напишите боту любое текстовое сообщение (например, /start). Чат-бот поддерживает 2 языка, поэтому сначала он предложит выбрать язык с помощью клавиатуры:

Please select your language: 
Пожалуйста, выберите язык:
[English] [Русский]

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

Добро пожаловать в GREEN-API MAX чат-бот, {Имя_Пользователя}! 

GREEN-API предоставляет отправку данных следующих видов. 
Выберите цифру или нажмите кнопку!

1. Текст 📩
2. Файл 📋
3. Картинка 🖼
4. Аудио 🎵
5. Видео 📽
6. Контакт 📱
7. Геолокация 🌎
8. О боте 🦎

Чтобы вернуться в начало, напишите *стоп* или *0*

Нажимая на кнопки (или отправляя соответствующие цифры), бот будет присылать вам демонстрационные сообщения с использованием различных методов MAX API и прикреплять ссылки на официальную документацию.

Структура кода

Основной файл чат-бота — это src/main.ts. В нем находится функция main, с которой начинается выполнение программы.

Данный бот использует паттерн сцен для организации кода. Логика разделена на фрагменты (сцены), каждая из которых соответствует определенному состоянию диалога:

• src/start_scene.ts — приветственная сцена. Отвечает за выбор языка.
• src/menu_scene.ts — формирует главное меню, отправляет приветственное изображение и переключает контекст на рабочие эндпоинты.
• src/endpoints.ts — содержит логику обработки всех функциональных кнопок (отправка текста, медиа, контактов).

Тексты сообщений хранятся в объекте translations в файле src/utils.ts. Для получения нужной строки используется функция T(lang, path).

Управление сообщениями

Все взаимодействия реализованы через MAX API с использованием библиотек:

• maxbot-chatbot-ts — фреймворк для создания ботов со сценами и состояниями.
• maxbot-api-client-ts — базовый клиент для работы с низкоуровневыми методами API.

Отправка сообщений максимально упрощена благодаря методам объекта Notification. Например, отправка локации:

await n.replyWithLocation(35.888171, 14.440230);

Или отправка медиафайла:

await n.replyWithMedia(
    text,
    fileUrl,
    Format.Markdown,
    buttons
);

Все доступные методы API описаны в официальной документации.
Полную документацию по MAX API можно найти на официальном портале разработчиков: dev.max.ru/docs-api.

Лицензия

LICENCE MIT