📋 NextBot → Chatwoot: Полная карта сценариев

Проект: EastPay (ID: 276a96dd-9dea-41f6-8828-3666a84d85c1)
n8n Webhook URL: https://n8n.flowzzy.com/webhook/nextbot-message-sync
Документ для ручной настройки в NextBot UI

🏗️ Архитектура потоков данных

┌──────────────────────────────────────────────────────────────────┐
│                     ПОЛНАЯ КАРТА ПОТОКОВ                         │
│                                                                  │
│  👤 Клиент                                                       │
│    │                                                             │
│    ▼ (Telegram Bot)                                              │
│  ┌──────────┐    Сценарий 1-4     ┌──────┐     ┌───────────┐   │
│  │ NextBot  │ ──── Custom API ──→ │ n8n  │ ──→ │ Chatwoot   │   │
│  │ (AI Bot) │                     │ WF-1 │     │ (Менеджер) │   │
│  └──────────┘                     └──────┘     └───────────┘   │
│    ▲    │                                            │          │
│    │    │ (бот отправляет                ┌──────┐    │          │
│    │    │  через TG API)                │ n8n  │ ←──┘          │
│    │    └─ клиент видит ←──────────────│ WF-2 │  CW webhook   │
│    │                                    └──────┘               │
│    │ Webhook: forwarded_output              │                   │
│    └────────────────────────────────────────┘                   │
│                                                                  │
│  ⚠️ НИКОГДА не слать в Telegram напрямую!                        │
│  Все сообщения клиенту → ТОЛЬКО через NextBot webhook.           │
└──────────────────────────────────────────────────────────────────┘

📋 Справочник: Доступные system_data переменные

🔧 Общие настройки (для ВСЕХ сценариев одинаковые)

Перед созданием каждого сценария:

Шаг A: Создание сценария

1. Перейдите: Scenarios → + Create scenario
2. Введите название (указано ниже для каждого)
3. Выберите Condition (триггер) (указан ниже)
4. Нажмите + Add action → выберите Custom API

Шаг B: Настройка Custom API (одинаково для всех)

Шаг C: Request headers

Нажмите + NEW PARAMETER и добавьте:

Шаг D: Request body

Заполняется по таблице ниже для каждого сценария.

⚠️ ВАЖНО: Типы значений (Value type):

• Text — вы сами вводите фиксированный текст (например, название события)
• System data — выбираете из dropdown переменную NextBot (динамическое значение)

📦 Сценарий 1: CW Sync: Старт диалога

Настройки сценария

Request body — добавьте 6 параметров:

Нажимайте + NEW PARAMETER для каждой строки:

✅ JSON structure preview должен выглядеть так:

{
  "event": "dialog_start",
  "dialog_id": "<System data: Dialog ID>",
  "text": "<System data: Dialog start (text)>",
  "user_id": "<System data: User ID>",
  "user_name": "<System data: Telegram: user name>",
  "messenger": "<System data: Messenger name>"
}

Проверка:

1. Нажмите RUN TEST
2. Откройте n8n → Executions для WF-1: должно появиться новое выполнение
3. Если ответ 200 OK — сценарий работает ✅

📦 Сценарий 2: CW Sync: Входящее от клиента

Настройки сценария

Request body — 5 параметров:

✅ JSON structure preview:

{
  "event": "client_message",
  "dialog_id": "<System data: Dialog ID>",
  "full_dialog": "<System data: Full dialog>",
  "user_id": "<System data: User ID>",
  "user_name": "<System data: Telegram: user name>"
}

💡 Почему Full dialog, а не отдельное сообщение?
В system_data нет переменной "текст текущего сообщения клиента".
Full dialog содержит всю историю, и n8n Code node автоматически извлечёт последнюю реплику.

📦 Сценарий 3: CW Sync: Ответ агента

Настройки сценария

Request body — 5 параметров:

✅ JSON structure preview:

{
  "event": "agent_message",
  "dialog_id": "<System data: Dialog ID>",
  "text": "<System data: AI agent reply>",
  "user_id": "<System data: User ID>",
  "messenger": "<System data: Messenger name>"
}

📦 Сценарий 4: CW Sync: Ошибка отправки

Настройки сценария

Request body — 4 параметра:

✅ JSON structure preview:

{
  "event": "send_error",
  "dialog_id": "<System data: Dialog ID>",
  "text": "<System data: Error message>",
  "user_id": "<System data: User ID>"
}

📦 Сценарий 5: CW Sync: Менеджер в NextBot (⚠️ создавать ПОСЛЕ тестов 1-4!)

Настройки сценария

Request body — 4 параметра:

⚠️ ОСТОРОЖНО с петлями! Создавайте только после того, как сценарии 1-4 протестированы и работают стабильно.

⚠️ Частые ошибки (НЕ допускайте!)

❌ Ошибка 1: Неправильный Value type для event

НЕПРАВИЛЬНО:
  event | System data | Dialog start (text)    ← Это текст сообщения, НЕ имя события!

ПРАВИЛЬНО:
  event | Text | dialog_start                  ← Статический текст

❌ Ошибка 2: Перепутан источник текста

НЕПРАВИЛЬНО:
  text | System data | Full dialog              ← Это ВСЯ история! Огромная строка!

ПРАВИЛЬНО (для Сценария 1):
  text | System data | Dialog start (text)       ← Первое сообщение

ПРАВИЛЬНО (для Сценария 3):
  text | System data | AI agent reply            ← Ответ агента

ПРАВИЛЬНО (для Сценария 2):
  full_dialog | System data | Full dialog        ← n8n сам извлечёт последнее

❌ Ошибка 3: Забыли Content-Type в headers

Без Content-Type: application/json n8n не сможет разобрать body.

❌ Ошибка 4: Создали сценарий для другого проекта

Убедитесь, что в шапке NextBot написано EastPay (а не другой проект!).

🔄 Обратный поток: Chatwoot → NextBot

⚠️ АРХИТЕКТУРНОЕ ПРАВИЛО: Все сообщения клиенту идут ТОЛЬКО через NextBot webhook.
НИКОГДА не через Telegram API (sendMessage) напрямую!

Когда менеджер пишет из Chatwoot:

Chatwoot → Global Webhook → n8n WF-2 → NextBot Webhook API → бот отправляет клиенту

NextBot Webhook URL:

https://app.nextbot.kz/api/webhooks/v1/276a96dd-9dea-41f6-8828-3666a84d85c1/41a58518d5a44d66bb656df141ad0963

n8n отправляет в NextBot:

{
  "dialog_id": 10177062,
  "text": "Подтверждаю ваш заказ.",
  "message_type": "forwarded_output"
}

Типы message_type:

🛡️ Защита от петель

5 уровней защиты:

1. NextBot: forwarded_output через HTTP webhook — НЕ триггерит сценарий "Manager message"
2. n8n WF-1: event: manager_message → private note в CW (видно, но не пересылается)
3. n8n WF-2: фильтр sender.type === "user" + message_type === 1 + private === false
4. Supabase: idempotency по message_id + direction
5. n8n WF-2: проверка content_attributes.external_id — свои игнорируем

⚙️ Настройки оператора (T9)

Где: NextBot → EastPay → Agent Settings → Управление активностью

📝 Чек-лист выполнения

Фаза 1: Создание сценариев

• Сценарий 1 создан (Dialog start) → JSON preview корректный
• Сценарий 1: RUN TEST → n8n execution появился
• Сценарий 2 создан (New client message) → JSON preview корректный
• Сценарий 3 создан (New agent message) → JSON preview корректный
• Сценарий 4 создан (Message send error) → JSON preview корректный

Фаза 2: Проверка на реальном боте

• Отправить сообщение боту в Telegram
• В n8n Executions (WF-1): появились 2 execution (client + agent)
• В Chatwoot: создался контакт и разговор с сообщениями
• В Supabase: записи в channel_mapping и sync_message_log

Фаза 3: Настройки оператора (T9)

• Автозасыпание включено
• Авто-возобновление 30 мин
• (Позже) Сценарий 5 создан и протестирован

Обновлено: 2026-03-05 16:10
Версия: 3.0 (Real UI — Request body form)
Автор: CTO Architecture Team