Как сделать бота в 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. Так проще понять, где сломалось: в самом боте, в обработчике сообщений или уже в интеграции с моделью.

Как добавить кнопки

Одних текстовых ответов иногда мало.

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

В библиотеке MAX для этого есть Keyboard.

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

bot.command('start', async (ctx) => {
  const keyboard = Keyboard.inlineKeyboard([
    [
      Keyboard.button.message('Что ты умеешь?'),
      Keyboard.button.message('Задать вопрос')
    ],
    [
      Keyboard.button.link('Открыть сайт', 'https://pxstudio.pw')
    ]
  ])

  await ctx.reply('Привет! Выберите действие или напишите вопрос.', {
    attachments: [keyboard]
  })
})

Кнопки хорошо использовать там, где нужно направить пользователя.

Но если вы подключаете GigaChat, не стоит пытаться заменить кнопками весь диалог. Лучше совместить: кнопки для быстрых сценариев, свободный текст - для вопросов, где человеку проще написать своими словами.

Что важно продумать до production

На простом примере все выглядит довольно легко.

Но production-бот - это уже не просто "принял текст, отправил в модель, вернул ответ". Там быстро появляются вопросы, о которых в демо обычно не думаешь.

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

История диалога

В примере мы отправляем в GigaChat только одно сообщение пользователя.

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

• user_id;
• последние сообщения;
• тему обращения;
• статус сценария;
• контекст заявки или заказа.

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

Ограничения и безопасность

Тут лучше заранее решить:

• кто может писать боту;
• сколько запросов может отправить один пользователь;
• какие темы бот не должен обсуждать;
• какие данные нельзя передавать в модель;
• что делать с персональными данными;
• какие ответы нужно логировать.

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

Стоимость и лимиты

Каждый запрос к языковой модели расходует токены.

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

• лимит длины входящего сообщения;
• ограничение количества запросов;
• понятные fallback-ответы;
• логирование ошибок;
• мониторинг расходов.

Webhook вместо Long Polling

Для разработки Long Polling удобен.

Но для production MAX рекомендует использовать Webhook. В документации также указано, что для вебхуков поддерживается HTTPS, включая самоподписанные сертификаты, а HTTP не поддерживается.

То есть если вы выкатываете бота на сервер, нужно подумать о домене, HTTPS, обработчике входящих событий и стабильном деплое. Это уже не та часть, которую хочется доделывать ночью после релиза, когда пользователи уже начали писать боту.

Где границы такого подхода

Пример выше хорош для старта.

Он помогает понять механику:

• как принять сообщение;
• как отправить его в GigaChat;
• как вернуть ответ;
• где хранить токены;
• как обработать ошибку.

Но такой бот еще не готов для серьезного клиентского сервиса. Я бы относился к нему как к техническому прототипу, который доказывает саму связку MAX + GigaChat.

В нем нет:

• базы данных;
• истории диалога;
• очереди задач;
• защиты от спама;
• админки;
• аналитики;
• проверки прав пользователя;
• нормальной обработки персональных данных;
• тестов;
• fallback-сценариев для недоступности GigaChat.

И это нормально.

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

Если задача простая - FAQ, быстрые ответы, первичная консультация - такого подхода может хватить для MVP.

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

Полезные источники

Если хотите копнуть глубже, лучше начинать с официальной документации:

• MAX для разработчиков: подготовка и настройка бота - токен, уведомления, Long Polling, Webhook и базовые ограничения;
• MAX Bot API: JavaScript-библиотека - установка @maxhub/max-bot-api, обработчики сообщений, кнопки и отправка ответов;
• MAX API: отправка сообщений - метод POST /messages, параметры и лимит текста;
• GigaChat API - описание продукта, подключение и возможности моделей;
• GigaChat SDK: использование в JS/TS - установка gigachat, параметры credentials, scope, model и пример giga.chat.

В итоге

Бот в MAX с GigaChat - это довольно понятная связка.

MAX отвечает за канал общения с пользователем: сообщения, команды, кнопки, чаты и уведомления.

GigaChat отвечает за генерацию осмысленного ответа на обычном языке.

А Node.js-приложение становится прослойкой между ними: принимает событие, чистит текст, задает контекст модели, обрабатывает ошибки и возвращает ответ.

Самое важное здесь не просто "подключить AI".

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

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

Я бы начинал именно с маленькой версии: команда /start, проверочный ping, один запрос в GigaChat, нормальная обработка ошибок. А уже после этого добавлял историю, базу данных, роли и сложные сценарии.

Так меньше магии и больше контроля. Для ботов это, как ни странно, часто важнее всего.