73 lines
4.9 KiB
Markdown
73 lines
4.9 KiB
Markdown
|
# MAX Bot + n8n (СПРФ / Клиент)
|
|||
|
|
|
|||
|
|
Интеграция бота в мессенджере **MAX** с **n8n**: webhook, нормализация входящих, отправка сообщений и кнопок, работа с БД (PostgreSQL, схемы sprf_ / clpr_).
|
|||
|
|
|
|||
|
|
## Содержимое репозитория
|
|||
|
|
|
|||
|
|
### Скрипты
|
|||
|
|
|
|||
|
|
| Файл | Назначение |
|
|||
|
|
|------|------------|
|
|||
|
|
| **register_max_webhook.py** | Регистрация webhook бота MAX на URL n8n (читает .env: MAX_BOT_TOKEN, N8N_MAX_WORKFLOW, MAX_WEBHOOK_SECRET). |
|
|||
|
|
| **fetch_schema.py** | Выгрузка структуры таблиц `sprf_*` из PostgreSQL в `sprf_tables_schema.md`. |
|
|||
|
|
|
|||
|
|
### Ноды для n8n (Code node)
|
|||
|
|
|
|||
|
|
| Файл | Назначение |
|
|||
|
|
|------|------------|
|
|||
|
|
| **n8n-code-node-max-normalize.js** | Нормализация входящего Webhook MAX: один объект с `max_id`, `max_chat_id`, `answer_text`, `answer_type` (text, command, callback, contact, voice, photo, file и т.д.), `callback_id`, `callback_message_text`, `contact_payload` и др. Личные чаты (dialog); при callback пользователь берётся из `callback.user`. |
|
|||
|
|
| **n8n-code-add-menu-buttons.js** | Формирование тела сообщения с меню: текст + inline_keyboard (callback-кнопки, request_contact, кнопка «Главное меню» type message). Выход: `message_body` для POST /messages. |
|
|||
|
|
|
|||
|
|
### Документация
|
|||
|
|
|
|||
|
|
| Путь | Описание |
|
|||
|
|
|------|----------|
|
|||
|
|
| **docs/max-webhook.md** | Настройка Webhook в n8n, регистрация в MAX, отправка ответа (POST /messages), ответ на callback (POST /answers), удаление кнопок. |
|
|||
|
|
| **docs/max-curl-http-request.md** | Примеры curl и настройка HTTP Request в n8n: отправка сообщения, кнопки, ответ на callback, удаление кнопок. |
|
|||
|
|
| **docs/max-api/** | Локальная копия/выжимка MAX Bot API: обзор, методы (messages, updates, subscriptions, answers), объекты (Update, Message, MessageBody, NewMessageBody), форматы текста (markdown/html), кнопки (inline_keyboard: callback, message, link, request_contact и др.), контакт (vcf_info, max_info). |
|
|||
|
|
| **docs/clpr-vs-sprf-schema-diff.md** | Сравнение структуры таблиц БД с префиксами clpr_ и sprf_. |
|
|||
|
|
| **SITUATION.md** | Текущая ситуация: что настроено, команды, файлы. |
|
|||
|
|
|
|||
|
|
### Схемы БД
|
|||
|
|
|
|||
|
|
| Файл | Описание |
|
|||
|
|
|------|----------|
|
|||
|
|
| **sprf_tables_schema.md** | Структура таблиц с префиксом `sprf_` (public). |
|
|||
|
|
| **clpr_tables_schema.md** | Структура таблиц с префиксом `clpr_` (public). |
|
|||
|
|
|
|||
|
|
## Требования
|
|||
|
|
|
|||
|
|
- Python 3, зависимости: `psycopg2-binary` (для fetch_schema).
|
|||
|
|
- В корне файл **.env** (не коммитить): `MAX_BOT_TOKEN`, `N8N_MAX_WORKFLOW`, `MAX_WEBHOOK_SECRET`, при необходимости `MAX_API_BASE`; для выгрузки схемы: `PGHOST`, `PGPORT`, `PGDATABASE`, `PGUSER`, `PGPASSWORD`.
|
|||
|
|
|
|||
|
|
## Быстрый старт
|
|||
|
|
|
|||
|
|
1. Настроить Webhook в n8n (path = `sprf_max`, POST), включить воркфлоу.
|
|||
|
|
2. Выполнить: `python3 register_max_webhook.py`.
|
|||
|
|
3. В воркфлоу после Webhook вставить Code node с содержимым `n8n-code-node-max-normalize.js`.
|
|||
|
|
4. Ответ пользователю: HTTP Request — POST `https://platform-api.max.ru/messages?user_id={{ $json.max_id }}`, body из `message_body` или свой JSON (текст, кнопки — см. docs).
|
|||
|
|
|
|||
|
|
Подробнее: **docs/max-webhook.md**, **docs/max-curl-http-request.md**, **docs/max-api/04-formats-and-buttons.md**.
|
|||
|
|
|
|||
|
|
## Ограничения MAX API
|
|||
|
|
|
|||
|
|
- Редактирование (PUT /messages) и удаление (DELETE /messages) — только для сообщений **моложе 24 часов**.
|
|||
|
|
- POST /answers (обновление сообщения с кнопками) — по факту тоже редактирование; при старше 24 ч может не сработать.
|
|||
|
|
|
|||
|
|
## Git
|
|||
|
|
|
|||
|
|
Репозиторий инициализирован, первый коммит на ветке `main`. Remote: `origin` → Gitea (при необходимости измените URL).
|
|||
|
|
|
|||
|
|
Чтобы отправить код на сервер (после создания репозитория MAX в Gitea при необходимости):
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd /dev/MAX
|
|||
|
|
git push -u origin main
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Логин/пароль Gitea запросит при первом push.
|
|||
|
|
|
|||
|
|
## Лицензия / конфиденциальность
|
|||
|
|
|
|||
|
|
Скрипты и доки — для внутреннего использования. Не коммитить .env и токены.
|