Фреймворк для настройки ботов

• Фреймворк для настройки ботов
  • Описание
  • Установка фреймворка
  • Пример быстрого старта
  • Настройка работы бота
    • Подключение подписок на события
    • Обработка событий
    • Обработка команд
    • Обработка сообщений
    • Обработка Callback-запросов
    • Объект Context
    • Промежуточный обработчик (Middleware)
      • Обработка ошибок в Middleware
  • Пример
  • Как предложить улучшение или идею
  • Лицензия

Описание

Это Golang — фреймворк для настройки работы ботов для MAX. С помощью него вы можете настраивать бота, обрабатывать сообщения, команды, callback-запросы и события

• Обработка команд — маршрутизация для событий бота
• Контекстная обработка — каждое обновление обрабатывается с контекстом, который содержит данные, специфичные для запроса
• Поддержка Middleware — создание промежуточных обработчиков для логирования, аутентификации, ограничения частоты запросов и других задач
• Модульная архитектура — бот расширяется и настраивается под запросы

Установка фреймворка

Для установки используйте команду go get:

go get github.com/max-messenger/maxbot

Пример быстрого старта

1. Создайте бота на платформе MAX для партнёров
2. Получите токен бота (access_token) и установите его как переменную окружения BOT_TOKEN
3. Создайте файл main.go и вставьте следующий код:

package main

import (
	"log"
	"os"

	"github.com/max-messenger/maxbot"
)

func main() {
	// Получение токена бота из переменных окружения
	access_token:= os.Getenv("BOT_TOKEN")

	// Создание нового экземпляра бота
	bot, err := maxbot.NewApi(access_token)
	if err != nil {
		log.Fatal(err)
	}

	// Определение обработчика для команды /start
	bot.Handle("/start", func(ctx *maxbot.Context) error {
		return ctx.Reply("Привет! Я MaxBot. Чем я могу помочь?")
	})

	// Запуск бота и начало мониторинга событий
	log.Println("Бот запускается...")
	bot.Start()
}

4. Для запуска бота в терминале выполните команду:

go run main.go

После выполнения команды в терминале отобразится сообщение: Бот запускается...

5. Откройте диалог с вашим ботом в MAX и отправьте команду /start. Бот ответит вам приветственным сообщением: Привет! Я MaxBot. Чем я могу помочь?

Готово! Ваш бот работает

Настройка работы бота

Подключение подписок на события

Чтобы бот получал обновления через Webhook - подписку, укажите access_token, URL и список типов событий для подписки:

bot, err := maxbot.NewApi(access_token, maxbot.WithWebhook("https://your-domain.com/webhook"))
// Типы событий: создание сообщений, получение callback
maxbot.OnMessageCreated,
maxbot.OnMessageCallback,

Обработка событий

Для регистрации обработчика необходимых событий используйте метод Handle:

// Обработка события изменения названия чата
bot.Handle(maxbot.OnChatTitleChangedEvent, func (c maxbot.Context) error {
    return c.Send("Заголовок чата изменён")
})

Обработка команд

Для регистрации обработчика необходимых команд используйте метод Handle:

// Обработка команды
bot.Handle("/start", startHandler)
bot.Handle("/help", helpHandler)

Обработка сообщений

Для регистрации обработчика необходимых сообщений используйте метод Handle:

// Обработка всех текстовых сообщений (не начинающихся с '/')
bot.Handle(maxbot.OnMessageCreated, textHandler)

Обработка Callback-запросов

Для регистрации обработчика callback-запросов используйте метод Handle:

// Связь callback-данных "pushBtn" с обработчиком `Context`
bot.HandleCallback("pushBtn", func (c maxbot.Context))

Объект Context

Объект maxbot.Context передаётся в каждый обработчик и содержит всю информацию о сообщении, а также методы для ответа

func myHandler(ctx *maxbot.Context) error {
    // Получение текстового сообщения
    text := ctx.Message.Text
    
    // Ответ сообщением
    return ctx.Reply("Вы сказали: " + text)
}

Промежуточный обработчик (Middleware)

Промежуточные обработчики (Middleware) позволяют выполнять код до или после основных обработчиков. Используются для логирования, аутентификации или сбора метрик

// Определение middleware для логирования
loggingMiddleware := func (next maxbot.HandlerFunc) maxbot.HandlerFunc {
    return func (ctx *maxbot.Context) error {
        log.Printf("Получено обновление от пользователя %d", ctx.Message.From.ID)
        return next(ctx)
	}
}

// Применение middleware к конкретному обработчику
bot.Handle("/secret", secretHandler, loggingMiddleware)

// Глобальное применение middleware
bot.Use(loggingMiddleware)

Обработка ошибок в Middleware

Чтобы перехватить и классифицировать ошибки с помощью middleware, используйте код:

errorMiddleware := func(next maxbot.HandlerFunc) maxbot.HandlerFunc {
    return func(ctx *maxbot.Context) error {
        err := next(ctx)
        if err != nil {
            if errors.Is(err, ErrUserNotFound) {
                return ctx.Reply("Пользователь не найден")
            }
            return ctx.Reply("Внутренняя ошибка")
        }
        return nil
    }
}

bot.Use(errorMiddleware)

Пример

Пример базового бота, демонстрирующего обработку команд и ответы

Как предложить улучшение или идею

Проект имеет открытый исходный код — вы можете сделать в проект Pull Request со своими доработками:

1. Сделайте Fork репозитория
2. Создайте ветку для вашей функции: git checkout -b feature/amazing-feature
3. Зафиксируйте изменения: git commit -m 'Add some amazing feature'
4. Отправьте изменения в ветку: git push origin feature/amazing-feature
5. Откройте Pull Request

Лицензия

Этот проект лицензирован под Apache License 2.0 - подробности смотрите в файле LICENSE