Golang чат-бот для официального API MAX#

maxbot-chatbot-library — это фреймворк для создания масштабируемых ботов для MAX Bot API на языке Go. Построенная на основе maxbot-api-client-go. Эта библиотека предоставляет чистый маршрутизатор, автоматическое обновление данных и надежный менеджер состояний (FSM) для построения многошаговых диалоговых сценариев.

API#

Документация к REST API MAX находится по ссылке. Библиотека является обёрткой к REST API, поэтому документация по ссылке выше применима и к самой библиотеке.

Авторизация#

Для использования библиотеки потребуется получить токен бота в консоли разработчика MAX API.

Содержание#

Как импортировать библиотеку и инициировать своего бота #

Маршрутизация команд и сообщений #

Управление состояниями и сцены #

Ответ с медиафайлами #

Пример эхо-бота #

Лицензия #

Как импортировать библиотеку и инициировать своего бота#

Убедитесь, что у вас установлена версия Go не ниже 1.25:

go version

Не забудьте создать модуль:

go mod init my-bot-project

Установка библиотеки:

go get github.com/green-api/maxbot-chatbot-library

Как инициализировать объект#

Для инициализации бота нужно воспользоваться методом NewBot из библиотеки и указать адрес платформы MaxBot, MAX token, а так же задать значения для RateLimiter и Timeout.

Параметры конфигурации:

BaseURL - Базовый URL-адрес серверов платформы MaxBot. Все методы API будут маршрутизироваться по этому корневому адресу. Актуальный адрес указан в официальной документации.
Token - Уникальный секретный ключ авторизации (API-ключ) вашего бота. Получить его можно в личном кабинете после регистрации или создании бота на платформе business.max.ru. Читайте перед началом работы, чтобы получить токен.
RateLimiter - Встроенный ограничитель частоты запросов. Он контролирует количество исходящих запросов в секунду (RPS), защищая бота от блокировки со стороны сервера за превышение лимитов. Рекомендуемое значение — не менее 25, но не более 30.
Timeout - Максимальное время ожидания ответа от сервера (в секундах). Если сервер не ответит в течение этого времени, запрос будет завершен с ошибкой. Оптимальное значение — 30 секунд.

    myBot, err := bot.NewBot(client.Config{
            BaseURL: "https://platform-api.max.ru",
            Token:   "YOUR_BOT_TOKEN",              // Замените на ваш токен
            RateLimiter: 25,
            Timeout: 30 * time.Second,
        })

Пример инициализации бота#

Чтобы начать получать и отвечать на сообщения, настройте бота, используя ваш BaseURL и Token, затем запустите механизм опроса.

    package main

    import (
        "context"
        "time"

        "github.com/green-api/maxbot-api-client-go/pkg/client"
        "github.com/green-api/maxbot-chatbot-library/pkg/bot"
    )

    func main() {
        myBot, err := bot.NewBot(client.Config{
            BaseURL: "https://platform-api.max.ru",
            Token:   "YOUR_BOT_TOKEN",              // Замените на ваш токен
            RateLimiter: 25,
            Timeout: 30 * time.Second,
        })

        if err != nil {
            panic(err)
        }

        myBot.StartPolling(context.Background())
    }

Маршрутизация команд и сообщений#

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

  package main

  import (
    "context"

    "github.com/green-api/maxbot-api-client-go/pkg/client"
    "github.com/green-api/maxbot-api-client-go/pkg/models"

    "github.com/green-api/maxbot-chatbot-library/pkg/bot"
    n "github.com/green-api/maxbot-chatbot-library/pkg/notification"
  )

  func main() {
    myBot, err := bot.NewBot(client.Config{
      BaseURL: "https://platform-api.max.ru",
      Token:   "YOUR_BOT_TOKEN",              // Замените на ваш токен
      RateLimiter: 25,
        Timeout: 30 * time.Second,
    })

    myBot.Router.Command("/start", func(n *n.Notification) {
      n.Reply("Hello! Welcome to the MAX Bot.")
    })

    myBot.Router.Register(models.TypeMessageCreated, func(n *n.Notification) {
      text, err := n.Text()
      if err == nil && text == "ping" {
        n.Reply("pong", m.Format(""))
      }
    })

    myBot.Router.Callback("accept_rules_payload", func(n *n.Notification) {
      n.Reply("*Thank you for accepting the rules!*", m.Markdown)
    })

    myBot.StartPolling(context.Background())
  }

Управление состояниями и сцены#

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

    package main

    import (
      "context"
      "fmt"

      "github.com/green-api/maxbot-api-client-go/pkg/models"
      "github.com/green-api/maxbot-chatbot-library/pkg/bot"
      n "github.com/green-api/maxbot-chatbot-library/pkg/notification"
      "github.com/green-api/maxbot-chatbot-library/pkg/state"
    )

    func main() {
      myBot, err := bot.NewBot(client.Config{
        BaseURL: "https://platform-api.max.ru",
        Token:   "YOUR_BOT_TOKEN",              // Замените на ваш токен
        RateLimiter: 25,
          Timeout: 30 * time.Second,
      })

      myBot.StateManager = state.NewMapStateManager(map[string]any{
        "step": "start",
      })

      myBot.StateManager.SetStartScene(RegistrationScene{})

      myBot.Router.Register(models.TypeMessageCreated, func(n *n.Notification) {
        currentScene := n.GetCurrentScene()
        if currentScene != nil {
          currentScene.Start(n)
        }
      })

      myBot.StartPolling(context.Background())
    }

    type RegistrationScene struct{}

    func (s RegistrationScene) Start(n *n.Notification) {
      text, _ := n.Text()

      if text == "/start" {
        n.Reply("Let's register! What is your *login*?", m.Markdown)
        return 
      }

      if len(text) >= 4 {
        n.StateManager.UpdateStateData(n.StateId, map[string]any{"login": text})

        n.Reply(fmt.Sprintf("**Login** `%s` accepted. Now enter your **password**:", text), m.Markdown)
        n.ActivateNextScene(PasswordScene{})
      } else {
        n.Reply("Login must be **at least 4 characters long**.", m.Markdown)
      }
    }

    type PasswordScene struct{}

    func (s PasswordScene) Start(n *n.Notification) {
      password, _ := n.Text()

      stateData := n.StateManager.GetStateData(n.StateId)
      login := stateData["login"].(string)

      n.Reply(fmt.Sprintf("Success! Profile created.\nLogin: `%s`\nPass: `%s`", login, password), m.Markdown)

      n.ActivateNextScene(RegistrationScene{})
    }

Ответ с медиафайлами#

Оболочка Notification предоставляет удобные методы для ответа текстом и вложениями.

    myBot.Router.Command("/photo", func(n *n.Notification) {
        n.ReplyWithMedia(
        "Check out this image!", 
        m.Markdown, 
        "https://example.com/image.png"
      )
    })

Пример эхо-бота#

Для примера того, как работать с MAX BOT API, предлагаем вам код эхо чат-бота:

    func main() {
      myBot, err := bot.NewBot(client.Config{
        BaseURL: "https://platform-api.max.ru",
        Token:   "YOUR_BOT_TOKEN",              // Замените на ваш токен
        RateLimiter: 25,
          Timeout: 30 * time.Second,
      })
      if err != nil {
        log.Error().Msgf("Bot initialization error: %v", err)
      }

      myBot.StateManager = state.NewMapStateManager(map[string]any{})

      myBot.Router.Register(models.TypeMessageCreated, func(n *c.Notification) {
        text, err := n.Text()
        if err != nil {
          return
        }
        n.Reply("Echo: " + text, "")
      })

      ctx, cancel := context.WithCancel(context.Background())
      defer cancel()

      go myBot.StartPolling(ctx)

      stop := make(chan os.Signal, 1)
      signal.Notify(stop, syscall.SIGINT, syscall.SIGTERM)
      <-stop

      log.Info().Msg("Bot shutting down...")
    }

Лицензия#

Лицензировано в соответствии с MIT.