NextBot ↔ Chatwoot: Технический план интеграции

Версия: 1.0
Дата: 2026-02-13
Автор: CTO / System Architect
Статус: На согласовании

1. Постановка задачи

1.1 Текущая ситуация

1.2 Целевое состояние

Единая система, в которой:

1. NextBot остаётся «мозгом» — вся ИИ-логика, функции и память работают без изменений
2. Chatwoot становится «глазами и руками» — оператор видит все диалоги в реальном времени, может вмешаться
3. Оператор пишет сообщение в Chatwoot → клиент получает в Telegram → NextBot знает об этом
4. Ни одно сообщение не теряется — ни от клиента, ни от ИИ, ни от оператора
5. Все функции NextBot продолжают работать при вмешательстве оператора

2. Архитектура решения

2.1 Ограничение Telegram Bot API

[!CAUTION] Telegram Bot Token даёт ОДНО соединение. Один токен не может быть подключён к NextBot и к Chatwoot одновременно. Если подключить токен к Chatwoot — NextBot потеряет связь с ботом и перестанет работать.

Следствие: Chatwoot НЕ подключается как Telegram-канал. Вместо этого создаётся API-канал (API Inbox), куда данные попадают программно.

2.2 Общая схема потоков данных

                    ┌────────────────────────────────────────────┐
                    │              TELEGRAM BOT                   │
                    │         (Token подключён ТОЛЬКО             │
                    │          к NextBot)                          │
                    └──────────┬────────────────────▲─────────────┘
                               │                    │
                    Входящее   │                    │ Исходящее
                    сообщение  │                    │ (от ИИ)
                               │                    │
                    ┌──────────▼────────────────────┤─────────────┐
                    │           NEXTBOT CLOUD                      │
                    │  ┌─────────┐ ┌──────────┐ ┌────────┐       │
                    │  │ИИ-Агент │ │Сценарии  │ │Функции │       │
                    │  │Александр│ │          │ │(10 шт) │       │
                    │  └─────────┘ └──────────┘ └────────┘       │
                    │                                              │
                    │  Сценарий «sync_to_chatwoot» ──────────┐    │
                    │  (триггер: каждое сообщение)           │    │
                    │                                        │    │
                    │  Webhook → Chatwoot Sync               │    │
                    └────────────────────────────────┬───────┘────┘
                                                     │
                                           Webhook POST
                                 (dialog_id, text, sender, type)
                                                     │
                    ┌────────────────────────────────▼────────────┐
                    │             n8n (ОРКЕСТРАТОР)                │
                    │                                              │
                    │  ┌────────────────────────────────────┐     │
                    │  │ Workflow 1: NextBot → Chatwoot Sync│     │
                    │  │  1. Получить Webhook из NextBot    │     │
                    │  │  2. Найти/создать Contact          │     │
                    │  │  3. Найти/создать Conversation     │     │
                    │  │  4. Отправить Message              │     │
                    │  └────────────────────────────────────┘     │
                    │                                              │
                    │  ┌────────────────────────────────────┐     │
                    │  │ Workflow 2: Chatwoot → NextBot Sync│     │
                    │  │  1. Получить Webhook из Chatwoot   │     │
                    │  │  2. Фильтр: sender.type === "user" │     │
                    │  │  3. Отправить в Telegram (Bot API) │     │
                    │  │  4. Webhook в NextBot (message)    │     │
                    │  └────────────────────────────────────┘     │
                    └──────────────────┬─────────────────────────┘
                                       │
                              Chatwoot API
                                       │
                    ┌──────────────────▼─────────────────────────┐
                    │            CHATWOOT (Docker)                 │
                    │                                              │
                    │  ┌──────────────┐  ┌────────────────────┐  │
                    │  │ API Inbox    │  │ Operator Dashboard │  │
                    │  │ "NextBot TG" │  │ (Web UI)           │  │
                    │  └──────────────┘  └────────────────────┘  │
                    │                                              │
                    │  Webhook → n8n (message_created)            │
                    └────────────────────────────────────────────┘

2.3 Ключевые принципы

3. Детальная спецификация компонентов

3.1 Chatwoot: Создание API Inbox

API Inbox — это «виртуальный канал» в Chatwoot, куда мы программно отправляем сообщения. Он не привязан ни к какому мессенджеру напрямую.

Шаги настройки:

1. Войти в Chatwoot → Settings → Inboxes → Add Inbox
2. Выбрать тип: API
3. Указать название: NextBot Telegram
4. Сохранить → записать inbox_id
5. Настроить callback_webhook_url для отправки событий в n8n

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

# Создание API Inbox через API (альтернатива UI)
curl -X POST "${CHATWOOT_BASE_URL}/api/v1/accounts/${ACCOUNT_ID}/inboxes" \
  -H "api_access_token: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NextBot Telegram",
    "channel": {
      "type": "api",
      "webhook_url": "https://<n8n-host>/webhook/chatwoot-inbound"
    }
  }'

[!NOTE] callback_webhook_url на инбоксе отличается от глобального вебхука Chatwoot. Глобальный webhook в Settings → Integrations → Webhooks лучше подходит, так как позволяет фильтровать по событиям.

3.2 Chatwoot: Настройка Webhook (исходящий)

Вебхук Chatwoot будет отправлять события о действиях оператора в n8n.

Настройка:

1. Settings → Integrations → Webhooks → Add New Webhook
2. URL: https://<n8n-host>/webhook/chatwoot-operator-message
3. Подписаться на события: message_created

Payload message_created от Chatwoot:

{
  "event": "message_created",
  "id": "456",
  "content": "Текст сообщения оператора",
  "message_type": "outgoing",
  "private": false,
  "sender": {
    "id": "1",
    "name": "Operator Serg",
    "email": "serg@eastpay.com",
    "type": "user"
  },
  "conversation": {
    "id": 42,
    "additional_attributes": {}
  },
  "account": {
    "id": "1",
    "name": "EastPay"
  }
}

[!IMPORTANT] Ключевой фильтр: sender.type === "user" — означает, что сообщение написал оператор (человек). Если sender.type === "contact" — это сообщение клиента (которое мы же и продублировали), его нужно ИГНОРИРОВАТЬ, чтобы не создать петлю.

3.3 NextBot: Сценарий «Sync to Chatwoot»

Для передачи сообщений из NextBot в Chatwoot используем встроенные Сценарии с действием «Отправить вебхук» или Custom API.

Вариант A: Сценарий с действием «Отправить вебхук»

URL вебхука: https://<n8n-host>/webhook/nextbot-message-sync

Данные в вебхуке NextBot:

NextBot при действии «Отправить вебхук» передаёт стандартные поля:

• dialog_id — ID диалога
• message_text — текст сообщения
• message_type — input (клиент) / output (агент) / operator (менеджер)
• Системные данные: {{user_name}}, {{user_phone}}, {{user_id}}

Вариант B: Два отдельных сценария (рекомендуемый)

Более точный контроль — создаём два сценария:

Сценарий 1: «CW Sync — Входящее от клиента»

Payload вебхука:

{
  "event": "client_message",
  "dialog_id": "{{dialog_id}}",
  "text": "{{message_text}}",
  "user_name": "{{user_name}}",
  "user_phone": "{{user_phone}}",
  "user_id": "{{user_external_id}}",
  "timestamp": "{{current_datetime}}"
}

Сценарий 2: «CW Sync — Исходящее от агента»

Payload вебхука:

{
  "event": "agent_message",
  "dialog_id": "{{dialog_id}}",
  "text": "{{message_text}}",
  "timestamp": "{{current_datetime}}"
}

[!TIP] Два отдельных сценария позволяют точно маркировать тип сообщения (incoming / outgoing) при создании в Chatwoot и избежать ошибок маппинга.

3.4 n8n: Workflow 1 — NextBot → Chatwoot Sync

Воркфлоу принимает вебхук от NextBot и синхронизирует сообщение в Chatwoot.

Пошаговая логика нод:

[Webhook Trigger]
    │
    ▼
[Switch: event type]
    ├── "client_message" → incoming flow
    └── "agent_message"  → outgoing flow
          │
          ▼
    [HTTP Request: Поиск контакта в Chatwoot]
    GET /api/v1/accounts/{id}/contacts/search?q={{user_id}}
          │
          ├── Контакт найден → contact_id
          └── Контакт НЕ найден
                │
                ▼
          [HTTP Request: Создать контакт]
          POST /api/v1/accounts/{id}/contacts
          Body: {
            "inbox_id": API_INBOX_ID,
            "name": "{{user_name}}",
            "phone_number": "{{user_phone}}",
            "identifier": "tg_{{user_id}}"
          }
          → contact_id
                │
                ▼
    [HTTP Request: Поиск существующей Conversation]
    GET /api/v1/accounts/{id}/contacts/{{contact_id}}/conversations
          │
          ├── Открытая conversation найдена → conversation_id
          └── НЕ найдена
                │
                ▼
          [HTTP Request: Создать Conversation]
          POST /api/v1/accounts/{id}/conversations
          Body: {
            "inbox_id": API_INBOX_ID,
            "contact_id": {{contact_id}},
            "status": "open"
          }
          → conversation_id
                │
                ▼
    [HTTP Request: Отправить сообщение]
    POST /api/v1/accounts/{id}/conversations/{{conversation_id}}/messages
    Body: {
      "content": "{{text}}",
      "message_type": "incoming" / "outgoing",
      "private": false
    }

Маппинг типов сообщений

Дополнительно: Private Notes для функций

Можно добавить третий сценарий в NextBot с триггером «Выполнение функции», который будет отправлять в Chatwoot private note с информацией о вызванной функции:

{
  "content": "🤖 Функция: create_order\nПараметры: from=USD, to=CNY, amount=5000\nРезультат: Order #EP-2456 создан",
  "message_type": "outgoing",
  "private": true
}

Это позволит оператору видеть, какие действия ИИ совершал «за кулисами».

3.5 n8n: Workflow 2 — Chatwoot → NextBot + Telegram Sync

Воркфлоу обрабатывает сообщения оператора из Chatwoot и доставляет их клиенту + информирует NextBot.

Пошаговая логика нод:

[Webhook Trigger: Chatwoot message_created]
    │
    ▼
[IF: sender.type === "user" AND private === false]
    │
    ├── FALSE → STOP (это incoming от клиента или private note — игнорируем)
    │
    └── TRUE (сообщение оператора для клиента)
          │
          ▼
    [Get Mapping: conversation_id → telegram_chat_id]
    (из хранилища n8n или из custom_attributes контакта Chatwoot)
          │
          ▼
    [HTTP Request: Отправка в Telegram]
    POST https://api.telegram.org/bot<TOKEN>/sendMessage
    Body: {
      "chat_id": "{{telegram_chat_id}}",
      "text": "{{content}}"
    }
          │
          ▼
    [HTTP Request: Webhook в NextBot]
    POST https://app.nextbot.ru/api/webhooks/v1/{agent_hash}/{url_token}
    Body: {
      "dialog_id": {{nextbot_dialog_id}},
      "text": "{{content}}",
      "message_type": "output"
    }

[!WARNING] Предотвращение петли (feedback loop): Когда оператор пишет в Chatwoot → n8n отправляет в Telegram и NextBot → NextBot получает сообщение → Сценарий «CW Sync» пытается снова отправить в Chatwoot → ПЕТЛЯ.

Решение: В сценарии NextBot «CW Sync — Исходящее от агента» добавить условие: НЕ срабатывать, если message_type === "output" (сообщение оператора, вброшенное через webhok). Альтернативно, в n8n при отправке в NextBot использовать message_type: "notification", который NextBot сохранит в контексте, но НЕ отправит клиенту и НЕ вызовет сценарий нового сообщения.

3.6 Маппинг IDs: NextBot dialog_id ↔ Chatwoot conversation_id ↔ Telegram chat_id

Центральная проблема интеграции — маппинг идентификаторов между тремя системами.

Стратегия хранения

Рекомендация: Вариант C (Supabase) — создать таблицу маппинга:

CREATE TABLE public.channel_mapping (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  telegram_chat_id BIGINT NOT NULL UNIQUE,
  nextbot_dialog_id BIGINT NOT NULL UNIQUE,
  chatwoot_contact_id INTEGER,
  chatwoot_conversation_id INTEGER,
  user_name TEXT,
  user_phone TEXT,
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ DEFAULT now()
);

-- Индексы для быстрого поиска в любую сторону
CREATE INDEX idx_mapping_tg_chat ON public.channel_mapping(telegram_chat_id);
CREATE INDEX idx_mapping_nb_dialog ON public.channel_mapping(nextbot_dialog_id);
CREATE INDEX idx_mapping_cw_conv ON public.channel_mapping(chatwoot_conversation_id);

Как заполняется:

1. Первое сообщение от нового клиента → NextBot Webhook в n8n содержит dialog_id и user_id (telegram_chat_id)
2. n8n создаёт контакт и conversation в Chatwoot → получает contact_id и conversation_id
3. n8n записывает все 4 ID в таблицу channel_mapping
4. При последующих сообщениях — n8n ищет маппинг по dialog_id (NextBot→Chatwoot) или conversation_id (Chatwoot→NextBot)

[!NOTE] Альтернативно, если Supabase кажется излишним для этой задачи, можно использовать Chatwoot identifier поле контакта (tg_{{user_id}}) для поиска контакта и через него получать conversation. А nextbot_dialog_id хранить в custom_attributes контакта. Это упрощает архитектуру, но делает reverse-lookup (Chatwoot→NextBot) сложнее.

4. Управление состоянием оператора (Handoff)

4.1 Когда оператор вмешивается

4.2 Настройка NextBot: Контроль вмешательства

В настройках агента «Александр» необходимо сконфигурировать:

[!IMPORTANT] Критический момент: Когда n8n отправляет сообщение оператора в NextBot через webhook, нужно использовать message_type: "output". Это сообщение NextBot засчитает как «сообщение менеджера», и ИИ автоматически «заснёт». Это именно то поведение, которое нам нужно — оператор взял диалог на себя.

4.3 Возврат к ИИ

Три сценария возврата:

1. Автоматический — таймер 30 мин (настроено в NextBot)
2. Ручной из Chatwoot — оператор нажимает «Resolve» → Chatwoot webhook conversation_status_changed → n8n → NextBot API снять паузу
3. Ручной из NextBot — в интерфейсе диалогов NextBot нажать «Снять паузу»

5. Предотвращение петель и дублирования

5.1 Карта потенциальных петель

5.2 Реализация защиты

В n8n Workflow 2 (Chatwoot → NextBot):

// Нода "IF" — фильтр петли
const senderType = $json.sender?.type;
const isPrivate = $json.private;
const messageType = $json.message_type; // 0=incoming, 1=outgoing

// Обрабатываем ТОЛЬКО если:
// 1. Отправитель — оператор (user), НЕ контакт
// 2. Сообщение НЕ private (не internal note)
// 3. message_type — outgoing (1)
return senderType === "user" && !isPrivate && messageType === 1;

В NextBot (message_type для webhook):

При отправке сообщения оператора в NextBot через webhook, использовать:

• message_type: "output" — если нужно, чтобы ИИ «заснул» (оператор взял диалог)
• message_type: "notification" — если нужно просто добавить контекст (системное сообщение)

Рекомендация: Использовать notification для вброса сообщения оператора в контекст NextBot, чтобы ИИ знал, что именно написал оператор, но при этом не вызывались сценарии и не создавалась петля. А засыпание ИИ обеспечить отдельно через output message_type.

Оптимальная комбинация:

1. n8n → Telegram API: отправить текст оператора клиенту (обязательно, т.к. API Inbox Chatwoot не подключён к TG)
2. n8n → NextBot Webhook: message_type: "output" — ИИ заснёт и увидит текст в контексте

6. Порядок реализации (Step-by-step)

Фаза 1: Подготовка Chatwoot (30 мин)

Фаза 2: Создание таблицы маппинга в Supabase (15 мин)

Фаза 3: n8n Workflow 1 — NextBot → Chatwoot (2-3 часа)

Фаза 4: Настройка NextBot сценариев (30 мин)

Фаза 5: Настройка NextBot — Контроль оператора (15 мин)

Фаза 6: n8n Workflow 2 — Chatwoot → NextBot + TG (2-3 часа)

Фаза 7: Тестирование и отладка (1-2 часа)

7. Требуемые данные и доступы

8. Риски и митигация

9. Расширения на будущее

10. Résumé архитектуры

Клиент (Telegram)
       │
       ▼
   NextBot Cloud ──── [ИИ «Александр», функции, KB, сценарии]
       │                       │
       │              Сценарии «CW Sync»
       │              (webhook на каждое сообщение)
       │                       │
       │                       ▼
       │                n8n Workflow 1
       │              (NextBot → Chatwoot)
       │                       │
       │                       ▼
       │                Chatwoot (API Inbox)
       │                       │
       │              Оператор видит всё,
       │              может ответить
       │                       │
       │              Chatwoot Webhook
       │              (message_created)
       │                       │
       │                       ▼
       │                n8n Workflow 2
       │              (Chatwoot → TG + NextBot)
       │                       │
       ├───────────────────────┤
       │                       │
  Telegram Bot API     NextBot Webhook
  (sendMessage)        (message_type: "output")
       │                       │
       ▼                       ▼
  Клиент получает         ИИ «засыпает»,
  сообщение оператора     контекст обновлён

Итого: Система работает как единое целое. NextBot — мозг. Chatwoot — интерфейс оператора. n8n — нервная система, передающая сигналы между компонентами. Telegram Bot Token остаётся привязан только к NextBot, а Chatwoot получает данные через API.