Омниканальные входящие и мосты

QuotyAI использует двухканальную архитектуру для обработки разговоров с клиентами на всех платформах. Хотите ли вы полного владения данными с помощью Нативных входящих или предпочитаете использовать существующую инфраструктуру Chatwoot с мостами входящих — QuotyAI дает вам гибкость выбора подходящего подхода для вашего бизнеса.

Два способа управления разговорами

QuotyAI реализует два различных подхода к управлению каналами общения:

1. Нативные входящие (Native Inboxes): Каналы, где история переписки хранится непосредственно в MongoDB QuotyAI — вы полностью владеете данными.
2. Мосты входящих (Inbox Bridges): Прокси-соединения с внешними экземплярами Chatwoot — QuotyAI обрабатывает сообщения, но история переписки хранится внешне.

Обзор архитектуры

                   ┌─────────────────────────────────────────────────────┐
                   │                    Канальный слой                              │
                   │  Telegram │ Facebook │ WhatsApp │ Instagram │ Voice/LiveKit   │
                   └──────────────────────┬────────────────────────────────┘
                                          │
                         ┌──────────────┴──────────────┐
                         │                             │
                  ┌──────▼────────┐          ┌───────▼────────┐
                  │ Нативные     │          │  Мосты        │
                  │ входящие     │          │  входящих     │
                  │ (владелец    │          │  (прокси-слой)│
                  │  данных)     │          │               │
                  └──────┬────────┘          └───────┬────────┘
                         │                           │
                         ▼                           ▼
                  ┌───────────────┐          ┌────────────────┐
                  │ БД QuotyAI  │          │ API Chatwoot  │
                  │ (полное      │          │ (внешнее      │
                  │  хранение)   │          │  хранилище)   │
                  └───────┬───────┘          └───────┬────────┘
                         │                           │
                         └──────────────┬─────────────┘
                                        ▼
                         ┌──────────────────────────────┐
                         │  Единая AI-обработка          │
                         │  (Продающие + Управляющие     │
                         │   ассистенты)                 │
                         └──────────────────────────────┘

Нативные входящие: Полное владение данными

Что такое нативные входящие?

Нативные входящие — это каналы связи, в которых QuotyAI владеет полным жизненным циклом разговора. Каждое сообщение, цепочка переписки и профиль контакта хранятся непосредственно в вашей MongoDB. Вы получаете полный контроль, исчерпывающие аудиторские журналы и богатую обработку вложений с OCR.

Поддерживаемые каналы

Архитектура хранения данных

┌──────────────────────────────────────────────────────┐
│                    MongoDB (БД QuotyAI)                │
├──────────────────────────────────────────────────────┤
│ native-inboxes                → Конфиги и учетные данные входящих    │
│ native-inbox-conversations    → Цепочки переписки                     │
│ native-inbox-contacts         → Единые профили контактов             │
│ native-inbox-telegram-messages → Сообщения Telegram                  │
│ native-inbox-facebook-messages → Сообщения Facebook                  │
│ voice-inboxes                 → Конфиги голосовых входящих           │
│ voice-inbox-sessions          → Сессии голосовых звонков             │
└──────────────────────────────────────────────────────┘

Основные модели данных

NativeInboxDoc (Конфигурация входящих)

export interface NativeInboxDoc {
  _id: ObjectId;
  tenantId: ObjectId;
  businessEntityId: ObjectId;  // Ссылка на вашу бизнес-сущность
  name: string;
  channel: NativeInboxChannelType;  // TELEGRAM, FACEBOOK и т.д.
  status: NativeInboxStatus;  // 'active' | 'disabled' | 'disconnected'
  
  // Учетные данные для конкретного канала (встроенные)
  credentials: NativeInboxChannelCredentialsDoc;
  // Telegram: { botToken, botUsername }
  // Facebook:  { pageId, accessToken, appSecret }
  // WhatsApp: { phoneNumberId, businessAccountId }
  
  webhookUrl: string;
  webhookSecret?: string;  // Для верификации
  
  // AI-конфигурация
  defaultAiReplyAssistantAssignment?: ConversationAiAssignmentDoc;
  
  createdAt: Date;
  updatedAt?: Date;
  deletedAt?: Date;  // Мягкое удаление
}

NativeInboxConversationDoc (Цепочка переписки)

export interface NativeInboxConversationDoc {
  _id: ObjectId;
  tenantId: ObjectId;
  inboxId: ObjectId;
  contactId: ObjectId;
  channel: NativeInboxChannelType;
  
  // Назначение AI (может переопределять настройки входящих)
  aiReplyAssistantAssignment?: ConversationAiAssignmentDoc;
  
  customAttributes?: Record<string, unknown>;
  externalId: string;  // ID чата Telegram, PSID Facebook и т.д.
  
  lastInboundMessage?: { text?: string; createdAt: Date };
  lastOutboundMessage?: { text?: string; createdAt: Date };
  
  createdAt: Date;
  updatedAt?: Date;
  deletedAt?: Date;
}

BaseNativeInboxMessageDoc (Сообщение)

export interface BaseNativeInboxMessageDoc {
  _id: ObjectId;
  tenantId: ObjectId;
  conversationId: ObjectId;
  inboxId: ObjectId;
  
  direction: MessageDirection;  // 'inbound' | 'outbound'
  status: MessageStatusEnum;  // 'sent' | 'delivered' | 'read' | 'failed'
  text?: string;
  
  sender: NativeInboxMessageSenderDoc;
  // { id: string; type: 'customer' | 'ai' | 'human_agent' | 'system' }
  
  // Расширенные вложения (все хранятся с URL в GCS)
  attachedImages?: NativeInboxMessageImageAttachmentDoc[];     // + данные OCR
  attachedVideos?: NativeInboxMessageVideoAttachmentDoc[];
  attachedAudios?: NativeInboxMessageAudioAttachmentDoc[];
  attachedFiles?: NativeInboxMessageFileAttachmentDoc[];
  attachedLocations?: NativeInboxMessageLocationAttachmentDoc[];
  attachedContacts?: NativeInboxMessageContactAttachmentDoc[];
  attachedStickers?: NativeInboxMessageStickerAttachmentDoc[];
  
  externalId?: string;  // ID сообщения на платформе
  metadata?: NativeInboxMessageMetadata;  // { runId для observability }
  
  visibleForCustomer: boolean;
  visibleForAi: boolean;
  
  createdAt: Date;
  deletedAt?: Date;
}

Как работают нативные входящие

Flow получения сообщений

Клиент отправляет сообщение
        ↓
API Telegram/Facebook отправляет вебхук в QuotyAI
        ↓
Приемник вебхуков (проверка секрета, ограничение частоты запросов)
        ↓
Очередь событий (на основе приоритета, асинхронная обработка)
        ↓
Сервис воркфлоу разговоров
        ↓
        ├─→ Найти/Создать контакт (единый профиль)
        ├─→ Найти/Создать разговор
        ├─→ Сохранить сообщение (с OCR для изображений)
        └─→ Вызвать AI-ассистента
                ↓
        AI генерирует ответ
                ↓
        Отправка через SDK канала (Telegram SDK, Facebook SDK)
                ↓
        Сохранение исходящего сообщения в MongoDB

Система очередей событий

UnifiedEventQueueService обеспечивает надежную асинхронную обработку:

export enum QueuedEventType {
  MESSAGE = 'message',
  EDITED_MESSAGE = 'edited_message',
  CALLBACK_QUERY = 'callback_query',
  POSTBACK = 'postback',
  // ... 20+ поддерживаемых типов событий
}

export enum EventPriority {
  HIGH = 0,    // Сообщения пользователей, платежи
  NORMAL = 1,  // Подтверждения доставки
  LOW = 2,     // Уведомления о прочтении, реакции
}

Возможности:

• Обработка на основе приоритета (HIGH → NORMAL → LOW)
• Автоматические повторные попытки с экспоненциальной задержкой (макс. 3 попытки)
• Ограничение частоты по ID чата
• Идемпотентность (предотвращает дублирующую обработку)
• Конкурентная обработка с настраиваемыми лимитами

Ключевые сервисы

Мосты входящих: Прокси-архитектура

Что такое мосты входящих?

Мосты входящих — это прокси-соединения с внешними экземплярами Chatwoot. В отличие от нативных входящих, QuotyAI НЕ хранит историю переписки. Вместо этого он проксирует запросы к API Chatwoot в реальном времени, обрабатывая AI локально.

Ключевая концепция: Прокси vs Хранение

┌──────────────────────────────────────────────────────┐
│                    QuotyAI хранит                          │
├──────────────────────────────────────────────────────┤
│ chatwoot-inbox-bridges             → Только конфиги мостов   │
│ external-chatwoot-accounts         → Учетные данные внешних аккаунтов │
│ external-chatwoot-reviewed-conversations → Маркеры проверки   │
└──────────────────────┬────────────────────────────────┘
                       │
                       │ Прокси-запросы
                       ▼
┌──────────────────────────────────────────────────────┐
│                  Экземпляр Chatwoot                        │
├──────────────────────────────────────────────────────┤
│ Разговоры (хранятся здесь)                               │
│ Сообщения (хранятся здесь)                               │
│ Контакты (хранятся здесь)                                │
└──────────────────────────────────────────────────────┘

Поддержка через Chatwoot

Поскольку Chatwoot поддерживает 10+ каналов, мосты входящих косвенно поддерживают:

• Facebook Messenger, Instagram, WhatsApp
• Email, веб-виджеты чата
• Slack, Microsoft Teams
• Любые кастомные каналы через API

Модели данных

ChatwootInboxBridgeDoc (Конфигурация моста)

export interface ChatwootInboxBridgeDoc {
  _id: ObjectId;
  tenantId: ObjectId;
  name: string;
  isActive: boolean;
  
  // Ссылка на внешний аккаунт Chatwoot
  parentExternalAccountId?: ObjectId;
  
  // Данные для подключения к Chatwoot
  chatwootHost?: string;              // Например, "https://chatwoot.example.com"
  chatwootUserAdminToken?: string;     // API-токен администратора
  chatwootAccountId?: number;          // Числовой ID аккаунта
  chatwootAgentBotId?: number;         // ID бота в Chatwoot
  chatwootAgentBotAccessToken?: string; // Токен доступа бота
  
  // Идентификация входящих
  createdChatwootInboxId?: number;       // Для внутреннего Chatwoot QuotyAI
  latestConnectedChatwootInboxId?: number; // Последний подключенный входящий
  
  // Подключение AI-ассистента
  apiKeyId: ObjectId;                   // Для аутентификации вебхуков
  assistantRole?: AssistantRole;          // 'sales' | 'accountant'
  assistantId?: ObjectId;                 // Ссылка на SalesAssistantDoc
  
  // URL
  managementUrl?: string;   // URL управления Chatwoot
  messengerUrl?: string;  // Публичный URL бота
  
  createdAt: Date;
  updatedAt?: Date;
  deletedAt?: Date;
}

ExternalChatwootAccountDoc (Внешний аккаунт)

export interface ExternalChatwootAccountDoc {
  _id: ObjectId;
  tenantId: ObjectId;
  name: string;
  host: string;                    // URL экземпляра Chatwoot
  accountId: number;                // ID аккаунта Chatwoot
  userAdminAccessToken: string;     // API-токен администратора
  createdAt: Date;
  deletedAt?: Date;
}

Как работают мосты входящих

Flow создания моста

Пользователь создает мост в QuotyAI
        ↓
ExternalChatwootService.createExternalChatwootInboxBridge()
        ↓
1. Получение внешнего аккаунта (host, токен из БД QuotyAI)
2. Создание документа моста в MongoDB (получение _id для URL вебхука)
        ↓
3. Создание бота-агента в Chatwoot через API
   POST /api/v1/widget/bots
        ↓
4. Обновление моста с токеном доступа и ID бота
5. Возврат данных моста пользователю

Обработка вебхуков (входящие сообщения)

Когда Chatwoot получает сообщение, он отправляет вебхук в QuotyAI:

// ChatwootWebhookProcessorService
async processWebhookEvent(
  payload: ChatwootWebhookPayload,
  tenantId: ObjectId,
  chatwootInboxBridge: ExternalChatwootInboxBridge
): Promise<void> {
  
  switch (payload.event) {
    case 'message_created':
      if (chatwootInboxBridge.assistantRole === 'sales') {
        await this.unifiedChatbotService.processIncomingMessage(
          InboxBridgeType.CHATWOOT,  // Тип канала
          tenantId,
          assistantId,
          { 
            payload, 
            chatwootInboxBridge,
            attachments: [...] 
          },
          signal
        );
      }
      break;
    // ... обработка других событий
  }
}

Чтение разговоров (прокси-паттерн)

// ChatwootConversationsService
async getExternalConversations(
  externalAccountId: string,
  tenantId: ObjectId,
  query: Record<string, unknown>
): Promise<Conversation[]> {
  
  // Получение учетных данных аккаунта из БД QuotyAI
  const fullAccount = await this.getFullExternalChatwootAccountById(...);
    
  // Прямой прокси к API Chatwoot (НЕ из БД QuotyAI)
  const response = await conversationList({
    baseUrl: fullAccount.host,
    headers: { 'api_access_token': fullAccount.userAdminAccessToken },
    path: { account_id: fullAccount.accountId },
    query: query
  });
    
  return response.data?.data?.payload || [];
}

Отметка разговоров как проверенных

QuotyAI хранит маркер в своей собственной БД:

// ChatwootConversationsService.markConversationAsReviewed()
await this.reviewedConversationsCollection.insertOne({
  tenantId,
  businessEntityId: new ObjectId(dto.businessEntityId),
  accountId: dto.accountId,
  inboxId: dto.inboxId,
  conversationId: dto.conversationId,
  reviewerNotes: dto.reviewerNotes,
  reviewedAt: new Date(),
  createdAt: new Date()
});

Единая AI-обработка

Как нативные входящие, так и мосты входящих используют один и тот же конвейер AI-обработки через адаптеры для конкретных каналов.

UnifiedSalesAssistantChatbotService

export class UnifiedSalesAssistantChatbotService {
  private readonly adapters: Map<UnifiedInboxChannelType, IChatAdapter>;
  
  constructor() {
    // Регистрация адаптеров для каждого типа канала
    this.adapters.set(InboxBridgeType.CHATWOOT, this.chatwootAdapter);
    this.adapters.set(NativeInboxChannelType.FACEBOOK, this.facebookAdapter);
    this.adapters.set(NativeInboxChannelType.TELEGRAM, this.telegramAdapter);
    this.adapters.set(StatelessApiChannelType.STATELESS_API, this.statelessApiAdapter);
  }
  
  async processIncomingMessage(
    channelType: UnifiedInboxChannelType,
    tenantId: ObjectId,
    assistantId: ObjectId,
    input: ChannelInput,  // Разный для каждого канала
    abortSignal: AbortSignal
  ): Promise<ProcessedMessageResult> {
    
    const adapter = this.adapters.get(channelType);
    // Адаптер обрабатывает:
    // 1. Построение AI-контекста (история переписки и т.д.)
    // 2. Вызов LLM
    // 3. Отправку ответа обратно в канал
  }
}

Типы входных данных каналов

Разные каналы имеют разные структуры входных данных:

// Для нативного Telegram входящего
export interface TelegramChannelInput {
  tenantId: ObjectId;
  conversationId: string;
  message: string;
  chatId: string;
  senderId: string;
  inbox: NativeInboxDoc;
  inboxId: string;
}

// Для нативного Facebook входящего
export interface FacebookChannelInput {
  tenantId: ObjectId;
  conversationId: string;
  message: string;
  pageId: string;
  psid: string;
  senderId: string;
  inbox: NativeInboxDoc;
  inboxId: string;
}

// Для моста Chatwoot
export interface ChatwootChannelInput {
  tenantId: ObjectId;
  conversationId: number;  // ID разговора в Chatwoot
  message: string;
  payload: ChatwootWebhookPayload;  // Полный payload вебхука
  chatwootInboxBridge: ExternalChatwootInboxBridge;
  attachments?: ChatwootAttachment[];
}

Интеграция с бизнес-сущностями

Оба типа входящих подключаются к бизнес-сущностям для AI-контекста и конфигурации.

┌──────────────────────────────────────────────────────┐
│                   Бизнес-сущность                          │
├──────────────────────────────────────────────────────┤
│ • Правила и формулы ценообразования                   │
│ • Услуги и каталог                                    │
│ • Факты о бизнесе (FAQ, политики)                     │
│ • Инструкции для AI-ассистентов                       │
│ • Конфигурация (часовой пояс, валюта, отрасль)     │
└──────────────┬───────────────────────────────────────┘
               │
         ┌──────┴──────┐
         │             │
         ▼             ▼
  ┌──────▼────────┐  ┌────────────────┐
  │ Продающий    │  │ Управляющий    │
  │ ассистент    │  │ ассистент      │
  └──────┬────────┘  └────────┬─────────┘
         │                 │
         ▼                 ▼
  ┌──────▼────────┐  ┌────────────────┐
  │ Нативные     │  │ Мосты         │
  │ входящие     │  │ входящих      │
  │ (Telegram,   │  │ (Chatwoot)    │
  │  Facebook...) │  │               │
  └────────────────┘  └────────────────┘

Назначение AI-ассистента

На уровне нативных входящих:

// NativeInboxDoc.defaultAiReplyAssistantAssignment
{
  mode: "fixed_assistant",  // или "dynamic_latest"
  assistantId: ObjectId,        // Ссылка на SalesAssistantDoc
  assistantRole: "sales",       // или "accountant"
  businessEntityId: ObjectId,
  sendingMessageMode: "ai_only",  // или "human_only", "ai_with_handover"
  handover?: { handedOverAt, handedOverBy, reason }
}

На уровне разговора (переопределяет входящие):

// NativeInboxConversationDoc.aiReplyAssistantAssignment
// Та же структура — может переопределять назначение на уровне входящих

На уровне моста входящих:

// ChatwootInboxBridgeDoc
{
  assistantRole: "sales",
  assistantId: ObjectId,
  // ... URL вебхука использует apiKeyId для аутентификации
}

Сравнение возможностей

Детали технической реализации

Коллекции базы данных

Архитектура сервисов

┌──────────────────────────────────────────────────────┐
│                    API слой (Hono)                         │
├──────────────────────────────────────────────────────┤
│ /omnichannel/inbox-lifecycles/* → Маршруты CRUD входящих    │
│ /omnichannel/conversations/* → Маршруты разговоров          │
│ /omnichannel/webhooks/* → Эндпоинты вебхуков              │
└──────────────┬──────────────────────────────────────────┘
               │
         ┌──────┴──────┐
         │             │
         ▼             ▼
  ┌──────▼────────┐  ┌────────────────┐
  │ Нативные     │  │ Сервисы       │
  │ сервисы      │  │ Chatwoot      │
  ├──────┬────────┤  ├────────┬─────────┤
  │ Telegram     │  │ Внешний        │
  │ Facebook    │  │ Chatwoot       │
  │ Жизненный   │  │ Сервис         │
  │ цикл        │  │ Мост           │
  │ Воркфлоу   │  │ Разговоры     │
  │ Вебхук      │  │               │
  └────────────────┘  └────────────────┘
         │             │
         └──────┬──────┘
                ▼
┌──────────────────────────────────────────────────────┐
│              Единая AI-обработка                       │
│        UnifiedSalesAssistantChatbotService              │
├──────────────────────────────────────────────────────┤
│ • Адаптеры каналов (Chatwoot, Facebook, Telegram)     │
│ • Система навыков (8 модульных навыков с инструментами)   │
│ • Динамический раннер (изолированное выполнение TypeScript) │
│ • Наблюдаемость (Полные аудиторские журналы)               │
└──────────────────────────────────────────────────────┘

Пример конфигурации: Создание нативного входящего Telegram

// POST /omnichannel/inbox-lifecycles/telegram/inboxes/
const response = await fetch('/api/omnichannel/inbox-lifecycles/telegram/inboxes/', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    telegramApiToken: '123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11',
    name: 'Мой Telegram бот',
    businessEntityId: '507f1f77bcf86cd799439011',
    apiKeyId: '507f1f77bcf86cd799439012'
  })
});

// Ответ включает:
// - ID входящего
// - Информацию о боте (id, username)
// - Статус вебхука
// - Автоматически созданные бизнес-сущность и ассистент (если запрошено)

Пример конфигурации: Создание моста входящих Chatwoot

// POST /omnichannel/inbox-lifecycles/chatwoot/external-instance/inbox-bridges/
const response = await fetch('/api/omnichannel/inbox-lifecycles/chatwoot/external-instance/inbox-bridges/', {
  method: 'POST',
  body: JSON.stringify({
    name: 'Мой мост Chatwoot',
    parentExternalAccountId: '507f1f77bcf86cd799439013',
    assistantRole: 'sales',
    assistantId: '507f1f77bcf86cd799439014',
    apiKeyId: '507f1f77bcf86cd799439015'
  })
});

// Это действие:
// 1. Создает документ моста в MongoDB
// 2. Создает бота-агента в Chatwoot
// 3. Настраивает URL вебхука
// QuotyAI НЕ хранит разговоры — только конфигурацию моста

Чтение разговоров: Нативные vs Мосты

// Нативные входящие: Из локальной MongoDB
// POST /omnichannel/conversations/native-inbox-conversations/search
const nativeConv = await fetch('/api/omnichannel/conversations/native-inbox-conversations/search', {
  method: 'POST',
  body: JSON.stringify({
    page: 1,
    limit: 20,
    channel: 'TELEGRAM',
    sort: 'lastMessageAt',
    order: 'desc'
  })
});

// Мост входящих: Прокси из API Chatwoot
// GET /omnichannel/conversations/chatwoot-bridge-conversations/conversations/:bridgeId
const bridgeConv = await fetch(`/api/omnichannel/conversations/chatwoot-bridge-conversations/conversations/${bridgeId}?limit=20`);
// Внутренне вызывает API Chatwoot и возвращает разговоры

Когда что использовать?

Выбирайте нативные входящие, если хотите:

• ✅ Полное владение данными — все данные в вашей MongoDB
• ✅ Прямую интеграцию с каналом — без посредников
• ✅ Богатую обработку вложений — OCR, анализ изображений
• ✅ Единые профили контактов по всем каналам
• ✅ Конвергенцию голоса и чата — один и тот же ассистент обрабатывает оба
• ✅ Полные аудиторские журналы — каждое сообщение в вашей БД
• ✅ Кастомные воркфлоу — полный контроль над обработкой

Лучше всего для: Бизнеса, который хочет полного контроля, нуждается в OCR-обработке или работает с чувствительными данными.

Выбирайте мосты входящих, если вы:

• ✅ Уже используете Chatwoot — используйте существующую инфраструктуру
• ✅ Нуждаетесь в более широкой поддержке каналов — Chatwoot поддерживает 10+ каналов
• ✅ Хотите UI/функции Chatwoot — управление разговорами, интерфейс агента
• ✅ Предпочитаете не дублировать данные — разговоры остаются в Chatwoot
• ✅ Имеете сложные потребности в маршрутизации — продвинутые правила маршрутизации Chatwoot

Лучше всего для: Бизнеса, уже работающего на Chatwoot, или тех, кому нужны каналы, которые QuotyAI пока не поддерживает нативно.

Сила единого AI

Оба подхода предоставляют одинаковые возможности AI-ассистента через единый UnifiedSalesAssistantChatbotService, обеспечивая неизменное качество обслуживания клиентов независимо от типа входящих.

Клиент отправляет сообщение через Telegram
        ↓
Нативные входящие (сохраняют сообщение)
        ↓                    ИЛИ
Клиент отправляет сообщение через Chatwoot
        ↓
Мост входящих (прокси к Chatwoot)
        ↓
        ┌────────────────────────────────────────────┐
        │  Один и тот же конвейер AI-обработки              │
        │  • 80+ языков                                │
        │  • Время ответа 1-2 секунды                  │
        │  • Детерминированное ценообразование           │
        │  • Передача управления человеку            │
        └────────────────────────────────────────────┘
        ↓
Клиент получает неизменно качественный ответ

Итог

Двухканальная архитектура входящих QuotyAI дает вам гибкость выбора подходящего подхода:

Оба подхода являются полноправными участниками экосистемы QuotyAI с полной интеграцией AI-ассистентов, поддержкой бизнес-сущностей и всесторонней наблюдаемостью.