Как сделать бота в MAX с GigaChat: простой пример на JavaScript

Раньше бот часто был набором кнопок и заранее написанных сценариев: нажал кнопку, получил ответ, перешел на следующий шаг. Для многих задач этого хватало, особенно если нужно было просто принять заявку или показать FAQ.

Но в реальной поддержке или продажах пользователь редко идет строго по сценарию. Он может написать "а сколько стоит?", "а можно завтра?", "а если у меня уже есть сайт?" - и вот тут обычное дерево кнопок начинает быстро разрастаться.

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

Например, для небольшой студии такой бот может закрывать первые вопросы по услугам: что входит в разработку сайта, сколько примерно занимает MVP, какие материалы нужны для старта. Не финально продавать за человека, а хотя бы не оставлять пользователя без ответа вечером или в выходной.

В этой статье разберем простой пример: бот в MAX принимает сообщение пользователя, отправляет текст в GigaChat и возвращает ответ обратно в чат.

Если вам нужен не только кодовый пример, а бизнес-разбор сценариев, можно отдельно посмотреть статью о GigaChat для бизнеса: там больше про заявки, поддержку, базу знаний, MVP и внедрение.

Не будем сразу строить сложную систему с базой данных, CRM, историей диалога и админкой. Я бы в такой задаче сначала проверил самый простой поток:

пользователь -> MAX bot -> Node.js приложение -> GigaChat API -> MAX bot -> пользователь

Если он работает, уже можно спокойно добавлять память, роли, ограничения, интеграции и нормальную production-архитектуру.

Что понадобится

Для базового примера нам нужно совсем немного:

• бот в MAX;
• токен бота MAX;
• ключ авторизации GigaChat API;
• Node.js;
• библиотека @maxhub/max-bot-api;
• SDK gigachat;
• файл .env для секретов.

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

По документации MAX, подключение к платформе для партнеров и создание чат-ботов доступно для юрлиц и ИП, которые являются резидентами РФ. Также для создания бота нужен верифицированный профиль организации на платформе MAX для партнеров.

То есть это не совсем история "за 2 минуты создал любого бота с личного аккаунта". Сначала нужно пройти организационную часть, создать бота, дождаться модерации и получить токен. Лучше заложить это в сроки заранее, чтобы потом не удивляться: код уже готов, а проверить его на реальном боте еще нельзя.

Как работает бот в MAX

MAX Bot API позволяет боту взаимодействовать с платформой через HTTPS-запросы. Если говорить проще, ваше приложение слушает события от MAX и отвечает обратно от имени бота.

Через API бот получает обновления от пользователей, отправляет сообщения, работает с чатами, кнопками, вложениями и другими объектами.

В документации MAX отдельно указано, что токен нужно передавать через заголовок:

Authorization: <token>

Передавать токен через query-параметры больше не нужно.

Также есть два способа получать уведомления о действиях пользователей:

• Long Polling - удобно для разработки и тестирования;
• Webhook - вариант для production.

Использовать оба режима одновременно нельзя, поэтому на старте лучше не усложнять. Для локальной разработки Long Polling обычно проще: запустили процесс, бот слушает обновления, можно проверять логи и быстро менять код. Для первого прототипа этого более чем достаточно.

Можно ходить в REST API напрямую через fetch, но для первого проекта я бы не усложнял. Если пишете на JavaScript или TypeScript, MAX рекомендует использовать официальную библиотеку @maxhub/max-bot-api. Она дает класс Bot, обработчики команд, входящих сообщений, callback-кнопок и методы для отправки ответов.

Создаем проект

Создадим папку и установим зависимости:

mkdir max-gigachat-bot
cd max-gigachat-bot
npm init -y
npm install @maxhub/max-bot-api gigachat dotenv

Чтобы использовать import, добавим в package.json поле type и простой script:

{
  "type": "module",
  "scripts": {
    "dev": "node --watch bot.js",
    "start": "node bot.js"
  }
}

node --watch удобен для разработки: поменяли код, сервер перезапустился. Не главная магия в мире, но когда вы десятый раз правите обработчик сообщения, это уже начинает радовать.

Настраиваем переменные окружения

Создадим файл .env:

MAX_BOT_TOKEN=ваш_токен_бота_max
GIGACHAT_CREDENTIALS=ваш_ключ_авторизации_gigachat
GIGACHAT_SCOPE=GIGACHAT_API_PERS
GIGACHAT_MODEL=GigaChat

И сразу добавим .env в .gitignore:

.env

На этом месте лучше не торопиться и не оставлять "потом разберусь".

Токен MAX - это прямой доступ к управлению ботом. Ключ GigaChat - это доступ к генерации через API. Такие вещи нельзя хранить в публичном репозитории, отправлять в чат команды или вставлять в примеры кода без замены.

Подключаем GigaChat

По документации SDK GigaChat для JS устанавливается пакетом gigachat, а объект создается с параметрами credentials, scope и model.

Сделаем отдельный файл gigachat.js. Так код бота останется читаемым, а всю работу с моделью можно будет потом отдельно расширять:

import GigaChat from 'gigachat'

const giga = new GigaChat({
  credentials: process.env.GIGACHAT_CREDENTIALS,
  scope: process.env.GIGACHAT_SCOPE || 'GIGACHAT_API_PERS',
  model: process.env.GIGACHAT_MODEL || 'GigaChat'
})

export async function askGigaChat(userText) {
  const response = await giga.chat({
    messages: [
      {
        role: 'system',
        content: [
          'Ты помощник компании в чат-боте MAX.',
          'Отвечай кратко, понятно и по делу.',
          'Если вопрос неясный, задай один уточняющий вопрос.',
          'Не выдумывай факты, цены и сроки, если их нет в сообщении пользователя.'
        ].join(' ')
      },
      {
        role: 'user',
        content: userText
      }
    ]
  })

  return response.choices[0]?.message?.content || 'Не получилось подготовить ответ.'
}

Здесь уже появляется первая важная настройка - system-сообщение.

Без него модель будет отвечать слишком свободно. А для бота обычно нужно задать рамки: кто он, как отвечает, что делать при неопределенности и чего не нужно придумывать.

Я бы не пропускал этот шаг даже в тестовом проекте. Потом именно такие мелочи определяют, будет бот похож на помощника или на случайный генератор ответов.

Если бот нужен для конкретной компании, в system-сообщение можно добавить тон общения, список услуг, ограничения по темам и правило "если не уверен - предложи связаться с менеджером". Это часто полезнее, чем пытаться сделать один универсальный промпт на все случаи.

Пишем бота MAX

Теперь создадим bot.js:

import 'dotenv/config'
import { Bot } from '@maxhub/max-bot-api'
import { askGigaChat } from './gigachat.js'

const bot = new Bot(process.env.MAX_BOT_TOKEN)

bot.command('start', async (ctx) => {
  await ctx.reply(
    'Привет! Напишите вопрос, а я попробую ответить с помощью GigaChat.'
  )
})

bot.hears('ping', async (ctx) => {
  await ctx.reply('pong')
})

bot.on('message_created', async (ctx) => {
  const text = ctx.message?.body?.text?.trim()

  if (!text) {
    return ctx.reply('Пока я умею отвечать только на текстовые сообщения.')
  }

  if (text.startsWith('/')) {
    return
  }

  try {
    await ctx.reply('Думаю над ответом...')

    const answer = await askGigaChat(text)

    await ctx.reply(limitMaxMessage(answer), {
      link: {
        type: 'reply',
        mid: ctx.message.body.mid
      }
    })
  } catch (error) {
    console.error(error)
    await ctx.reply('Что-то пошло не так. Попробуйте повторить запрос чуть позже.')
  }
})

function limitMaxMessage(text) {
  const limit = 3900

  if (text.length <= limit) {
    return text
  }

  return `${text.slice(0, limit)}\n\nОтвет получился длинным, поэтому я его сократил.`
}

bot.start()

Тут уже есть минимальный рабочий бот. Он пока простой, но это как раз хорошо:

• bot.command('start') отвечает на команду /start;
• bot.hears('ping') нужен для простой проверки, что бот вообще живой;
• bot.on('message_created') ловит обычные сообщения;
• текст пользователя отправляется в askGigaChat;
• ответ возвращается через ctx.reply;
• длинный ответ заранее обрезается.

Отдельный момент про limitMaxMessage.

Почему я поставил лимит 3900, если в методе отправки сообщений MAX у текста указан лимит до 4000 символов?

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

Позже лучше сделать нормальное разбиение длинных ответов на несколько сообщений. Но для первого прототипа мягко обрезать ответ проще и безопаснее.

Запускаем локально

Запускаем:

npm run dev

Проверяем в MAX:

/start

Потом:

ping

И уже после этого обычный вопрос:

Расскажи простыми словами, чем API отличается от webhook

Если все настроено правильно, бот примет сообщение, отправит его в GigaChat и вернет ответ в чат.

Я бы проверял именно в таком порядке: сначала /start, потом ping, и только потом GigaChat. Так проще понят�