translate Có sẵn bằng: EN RU
info Dịch bằng AI

Inboxes & Bridges của QuotyAI

Inboxes & Bridges Đa Kênh

QuotyAI sử dụng kiến trúc hai kênh để xử lý hội thoại khách hàng trên mọi nền tảng. Dù bạn muốn toàn quyền sở hữu dữ liệu với Native Inboxes, hay ưu tiên tận dụng thiết lập Chatwoot hiện có thông qua Inbox Bridges, QuotyAI mang đến sự linh hoạt để bạn chọn cách tiếp cận phù hợp cho doanh nghiệp của mình.


Hai Cách Xử Lý Hội Thoại

QuotyAI triển khai hai phương pháp riêng biệt để quản lý các kênh hội thoại:

  1. Native Inboxes: Các kênh nơi lịch sử hội thoại được lưu trữ trực tiếp trong cơ sở dữ liệu MongoDB của QuotyAI — bạn hoàn toàn sở hữu dữ liệu.
  2. Inbox Bridges: Kết nối proxy tới các phiên bản Chatwoot bên ngoài — QuotyAI xử lý tin nhắn nhưng lịch sử hội thoại được lưu trữ bên ngoài.

Tổng Quan Kiến Trúc

┌─────────────────────────────────────────────────────┐
│                    Tầng Kênh (Channel Layer)                    │
│  Telegram │ Facebook │ WhatsApp │ Instagram │ Voice/LiveKit   │
└──────────────────────┬────────────────────────────────┘

         ┌──────────────┴──────────────┐
         │                           │
┌───────▼────────┐    ┌───────▼────────┐
│ Native Inboxes │    │ Inbox Bridges  │
│ (Sở hữu DL)   │    │ (Tầng Proxy)  │
└───────┬────────┘    └───────┬────────┘
        │                           │
        ▼                           ▼
┌───────────────┐    ┌────────────────┐
│ QuotyAI DB   │    │ Chatwoot API  │
│ (Lưu toàn bộ) │    │ (Lưu bên ngoài) │
└───────┬───────┘    └───────┬────────┘
        │                           │
        └──────────────┬──────────┘

        ┌──────────────────────────────┐
        │  Xử Lý AI Thống Nhất       │
        │  (Sales + Management        │
        │   Assistants)              │
        └──────────────────────────────┘

Native Inboxes: Toàn Quyền Sở Hữu Dữ Liệu

Native Inboxes Là Gì?

Native inboxes là các kênh giao tiếp nơi QuotyAI sở hữu toàn bộ vòng đời hội thoại. Mọi tin nhắn, luồng hội thoại và hồ sơ liên hệ đều được lưu trữ trực tiếp trong cơ sở dữ liệu MongoDB của bạn. Bạn có toàn quyền kiểm soát, nhật ký kiểm toán đầy đủ và xử lý tệp đính kèm phong phú với OCR.

Các Kênh Được Hỗ Trợ

Kênh Giá trị Enum Trạng thái
Telegram TELEGRAM ✅ Hoạt động
Facebook Messenger FACEBOOK ✅ Hoạt động
Instagram INSTAGRAM ✅ Hoạt động
WhatsApp WHATSAPP ✅ Hoạt động
Voice (LiveKit) LIVEKIT ✅ Hoạt động

Kiến Trúc Lưu Trữ Dữ Liệu

┌─────────────────────────────────────────────────────┐
│                  MongoDB (QuotyAI DB)                  │
├─────────────────────────────────────────────────────┤
│ native-inboxes           → Cấu hình inbox & thông tin xác thực  │
│ native-inbox-conversations → Luồng hội thoại                    │
│ native-inbox-contacts    → Hồ sơ liên hệ hợp nhất              │
│ native-inbox-telegram-messages → Tin nhắn Telegram             │
│ native-inbox-facebook-messages → Tin nhắn Facebook             │
│ voice-inboxes           → Cấu hình inbox thoại         │
│ voice-inbox-sessions     → Phiên gọi thoại                     │
└─────────────────────────────────────────────────────┘

Các Mô Hình Dữ Liệu Cốt Lõi

NativeInboxDoc (Cấu hình Inbox)

export interface NativeInboxDoc {
  _id: ObjectId;
  tenantId: ObjectId;
  businessEntityId: ObjectId;  // Liên kết tới doanh nghiệp của bạn
  name: string;
  channel: NativeInboxChannelType;  // TELEGRAM, FACEBOOK, v.v.
  status: NativeInboxStatus;  // 'active' | 'disabled' | 'disconnected'
  
  // Thông tin xác thực theo từng kênh (nhúng)
  credentials: NativeInboxChannelCredentialsDoc;
  // Telegram: { botToken, botUsername }
  // Facebook:  { pageId, accessToken, appSecret }
  // WhatsApp: { phoneNumberId, businessAccountId }
  
  webhookUrl: string;
  webhookSecret?: string;  // Dùng để xác minh
  
  // Cấu hình AI
  defaultAiReplyAssistantAssignment?: ConversationAiAssignmentDoc;
  
  createdAt: Date;
  updatedAt?: Date;
  deletedAt?: Date;  // Xóa mềm
}

NativeInboxConversationDoc (Luồng Hội Thoại)

export interface NativeInboxConversationDoc {
  _id: ObjectId;
  tenantId: ObjectId;
  inboxId: ObjectId;
  contactId: ObjectId;
  channel: NativeInboxChannelType;
  
  // Phân công AI (có thể ghi đè mặc định cấp inbox)
  aiReplyAssistantAssignment?: ConversationAiAssignmentDoc;
  
  customAttributes?: Record<string, unknown>;
  externalId: string;  // ID chat Telegram, PSID Facebook, v.v.
  
  lastInboundMessage?: { text?: string; createdAt: Date };
  lastOutboundMessage?: { text?: string; createdAt: Date };
  
  createdAt: Date;
  updatedAt?: Date;
  deletedAt?: Date;
}

BaseNativeInboxMessageDoc (Tin Nhắn)

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' }
  
  // Tệp đính kèm đa dạng (tất cả được lưu với URL GCS)
  attachedImages?: NativeInboxMessageImageAttachmentDoc[];     // + dữ liệu OCR
  attachedVideos?: NativeInboxMessageVideoAttachmentDoc[];
  attachedAudios?: NativeInboxMessageAudioAttachmentDoc[];
  attachedFiles?: NativeInboxMessageFileAttachmentDoc[];
  attachedLocations?: NativeInboxMessageLocationAttachmentDoc[];
  attachedContacts?: NativeInboxMessageContactAttachmentDoc[];
  attachedStickers?: NativeInboxMessageStickerAttachmentDoc[];
  
  externalId?: string;  // ID tin nhắn từ nền tảng
  metadata?: NativeInboxMessageMetadata;  // { runId để quan sát }
  
  visibleForCustomer: boolean;
  visibleForAi: boolean;
  
  createdAt: Date;
  deletedAt?: Date;
}

Cách Native Inboxes Hoạt Động

Luồng Nhận Tin Nhắn

Khách hàng gửi tin nhắn

Telegram/Facebook API gửi webhook tới QuotyAI

Webhook Receiver (xác minh secret, kiểm tra giới hạn tốc độ)

Hàng đợi sự kiện (dựa trên ưu tiên, xử lý bất đồng bộ)

Conversation Workflow Service

        ├─→ Tìm/Tạo Liên hệ (hồ sơ hợp nhất)
        ├─→ Tìm/Tạo Hội thoại
        ├─→ Lưu tin nhắn (kèm OCR cho hình ảnh)
        └─→ Gọi AI Assistant

        AI tạo phản hồi

        Gửi qua Channel SDK (Telegram SDK, Facebook SDK)

        Lưu tin nhắn gửi đi trong MongoDB

Hệ Thống Hàng Đợi Sự Kiện

UnifiedEventQueueService cung cấp khả năng xử lý bất đồng bộ mạnh mẽ:

export enum QueuedEventType {
  MESSAGE = 'message',
  EDITED_MESSAGE = 'edited_message',
  CALLBACK_QUERY = 'callback_query',
  POSTBACK = 'postback',
  // ... hơn 20 loại sự kiện được hỗ trợ
}

export enum EventPriority {
  HIGH = 0,    // Tin nhắn người dùng, thanh toán
  NORMAL = 1,  // Xác nhận gửi
  LOW = 2,     // Biên nhận đã đọc, phản hồi
}

Tính năng:

  • Xử lý theo ưu tiên (HIGH → NORMAL → LOW)
  • Tự động thử lại với backoff theo cấp số nhân (tối đa 3 lần)
  • Giới hạn tốc độ theo từng chat ID
  • Tính đơn nhất (ngăn xử lý trùng lặp)
  • Xử lý đồng thời với giới hạn có thể cấu hình

Các Dịch Vụ Chính

Dịch vụ Trách nhiệm
TelegramChannelLifecycleService CRUD inbox, xác thực bot token, thiết lập/xóa webhook
TelegramWebhookReceiverService Nhận webhook, xác minh secret, xếp hàng đợi sự kiện
TelegramConversationWorkflowService Xử lý tin nhắn, lưu vào DB, quản lý liên hệ
FacebookChannelLifecycleService Tương tự cho Facebook/Instagram
UnifiedNativeInboxLifecycleService Thao tác đọc hợp nhất trên tất cả native inboxes
UnifiedNativeInboxConversationService Tìm kiếm hội thoại, phân trang, phân công AI

Inbox Bridges: Kiến Trúc Proxy

Inbox Bridges Là Gì?

Inbox bridges là kết nối proxy tới các phiên bản Chatwoot bên ngoài. Không giống native inboxes, QuotyAI KHÔNG lưu trữ lịch sử hội thoại. Thay vào đó, nó chuyển tiếp yêu cầu tới Chatwoot API theo thời gian thực trong khi xử lý AI tại chỗ.

Khái Niệm Chính: Proxy vs Lưu Trữ

┌─────────────────────────────────────────────────────┐
│                    QuotyAI Lưu Trữ                        │
├─────────────────────────────────────────────────────┤
│ chatwoot-inbox-bridges → Chỉ cấu hình bridge           │
│ external-chatwoot-accounts → Thông tin xác thực tài khoản ngoài │
│ external-chatwoot-reviewed-conversations → Đánh dấu đã xem xét│
└──────────────────────┬────────────────────────────────┘

                       │ Chuyển tiếp yêu cầu

┌─────────────────────────────────────────────────────┐
│                  Phiên bản Chatwoot                        │
├─────────────────────────────────────────────────────┤
│ Hội thoại (được lưu tại đây)                            │
│ Tin nhắn (được lưu tại đây)                              │
│ Liên hệ (được lưu tại đây)                              │
└─────────────────────────────────────────────────────┘

Được Hỗ Trợ Thông Qua Chatwoot

Do Chatwoot hỗ trợ 10+ kênh, inbox bridges hỗ trợ gián tiếp:

  • Facebook Messenger, Instagram, WhatsApp
  • Email, Website chat widgets
  • Slack, Microsoft Teams
  • Bất kỳ kênh tùy chỉnh nào qua API

Mô Hình Dữ Liệu

ChatwootInboxBridgeDoc (Cấu hình Bridge)

export interface ChatwootInboxBridgeDoc {
  _id: ObjectId;
  tenantId: ObjectId;
  name: string;
  isActive: boolean;
  
  // Tham chiếu tới tài khoản Chatwoot bên ngoài
  parentExternalAccountId?: ObjectId;
  
  // Thông tin kết nối Chatwoot
  chatwootHost?: string;              // Ví dụ: "https://chatwoot.example.com"
  chatwootUserAdminToken?: string;     // Token API quản trị
  chatwootAccountId?: number;          // ID tài khoản dạng số
  chatwootAgentBotId?: number;         // ID bot trong Chatwoot
  chatwootAgentBotAccessToken?: string; // Token truy cập bot
  
  // Nhận dạng inbox
  createdChatwootInboxId?: number;       // Cho Chatwoot nội bộ của QuotyAI
  latestConnectedChatwootInboxId?: number; // Inbox đã kết nối gần nhất
  
  // Kết nối AI Assistant
  apiKeyId: ObjectId;                   // Xác thực webhook
  assistantRole?: AssistantRole;          // 'sales' | 'accountant'
  assistantId?: ObjectId;                 // Tham chiếu tới SalesAssistantDoc
  
  // URL
  managementUrl?: string;   // URL quản lý Chatwoot
  messengerUrl?: string;  // URL bot công khai
  
  createdAt: Date;
  updatedAt?: Date;
  deletedAt?: Date;
}

ExternalChatwootAccountDoc (Tài Khoản Bên Ngoài)

export interface ExternalChatwootAccountDoc {
  _id: ObjectId;
  tenantId: ObjectId;
  name: string;
  host: string;                    // URL phiên bản Chatwoot
  accountId: number;                // ID tài khoản Chatwoot
  userAdminAccessToken: string;     // Token API quản trị
  createdAt: Date;
  deletedAt?: Date;
}

Cách Inbox Bridges Hoạt Động

Luồng Tạo Bridge

Người dùng tạo bridge trong QuotyAI

ExternalChatwootService.createExternalChatwootInboxBridge()

1. Lấy tài khoản ngoài (host, token từ DB QuotyAI)
2. Tạo tài liệu bridge trong MongoDB (lấy _id cho URL webhook)

3. Tạo agent bot trong Chatwoot qua API
   POST /api/v1/widget/bots

4. Cập nhật bridge với access token & bot ID
5. Trả dữ liệu bridge cho người dùng

Xử Lý Webhook (Tin Nhắn Đến)

Khi Chatwoot nhận được tin nhắn, nó gửi webhook tới 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,  // Loại kênh
          tenantId,
          assistantId,
          { 
            payload, 
            chatwootInboxBridge,
            attachments: [...] 
          },
          signal
        );
      }
      break;
    // ... xử lý các sự kiện khác
  }
}

Đọc Hội Thoại (Mẫu Proxy)

// ChatwootConversationsService
async getExternalConversations(
  externalAccountId: string,
  tenantId: ObjectId,
  query: Record<string, unknown>
): Promise<Conversation[]> {
  
  // Lấy thông tin xác thực từ DB QuotyAI
  const fullAccount = await this.getFullExternalChatwootAccountById(...);
    
  // Proxy trực tiếp tới Chatwoot API (KHÔNG từ DB 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 || [];
}

Đánh Dấu Hội Thoại Đã Xem Xét

QuotyAI lưu dấu hiệu trong DB của riêng mình:

// 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()
});

Xử Lý AI Thống Nhất

Cả native inboxes và inbox bridges đều sử dụng cùng một pipeline xử lý AI thông qua các bộ điều hợp (adapters) theo từng kênh.

UnifiedSalesAssistantChatbotService

export class UnifiedSalesAssistantChatbotService {
  private readonly adapters: Map<UnifiedInboxChannelType, IChatAdapter>;
  
  constructor() {
    // Đăng ký adapter cho từng loại kênh
    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,  // Khác nhau cho mỗi kênh
    abortSignal: AbortSignal
  ): Promise<ProcessedMessageResult> {
    
    const adapter = this.adapters.get(channelType);
    // Adapter xử lý:
    // 1. Xây dựng ngữ cảnh AI (lịch sử hội thoại, v.v.)
    // 2. Gọi LLM
    // 3. Gửi phản hồi về kênh tương ứng
  }
}

Các Loại Đầu Vào Kênh

Các kênh khác nhau có cấu trúc đầu vào khác nhau:

// Cho Native Telegram Inbox
export interface TelegramChannelInput {
  tenantId: ObjectId;
  conversationId: string;
  message: string;
  chatId: string;
  senderId: string;
  inbox: NativeInboxDoc;
  inboxId: string;
}

// Cho Native Facebook Inbox
export interface FacebookChannelInput {
  tenantId: ObjectId;
  conversationId: string;
  message: string;
  pageId: string;
  psid: string;
  senderId: string;
  inbox: NativeInboxDoc;
  inboxId: string;
}

// Cho Chatwoot Bridge
export interface ChatwootChannelInput {
  tenantId: ObjectId;
  conversationId: number;  // ID hội thoại Chatwoot
  message: string;
  payload: ChatwootWebhookPayload;  // Tải trọng webhook đầy đủ
  chatwootInboxBridge: ExternalChatwootInboxBridge;
  attachments?: ChatwootAttachment[];
}

Tích Hợp với Business Entities

Cả hai loại inbox đều kết nối tới business entities để lấy ngữ cảnh và cấu hình AI.

┌─────────────────────────────────────────────────────┐
│                   Business Entity                         │
├─────────────────────────────────────────────────────┤
│ • Quy tắc & công thức định giá                      │
│ • Danh mục dịch vụ                                   │
│ • Thông tin doanh nghiệp (FAQs, chính sách)          │
│ • Hướng dẫn cho AI assistants                        │
│ • Cấu hình (múi giờ, tiền tệ, ngành nghề)          │
└──────────────┬──────────────────────────────────────┘

         ┌──────┴──────┐
         │             │
         ▼             ▼
┌───────▼────────┐ ┌────────────────┐
│ Sales         │ │ Management    │
│ Assistant     │ │ Assistant    │
└───────┬────────┘ └────────┬─────────┘
        │                 │
        ▼                 ▼
┌───────▼────────┐ ┌────────────────┐
│ Native        │ │ Inbox        │
│ Inboxes       │ │ Bridges      │
│ (Telegram,    │ │ (Chatwoot)   │
│  Facebook...) │ │              │
└────────────────┘ └────────────────┘

Phân Công AI Assistant

Cấp Native Inbox:

// NativeInboxDoc.defaultAiReplyAssistantAssignment
{
  mode: "fixed_assistant",  // hoặc "dynamic_latest"
  assistantId: ObjectId,        // Tham chiếu tới SalesAssistantDoc
  assistantRole: "sales",       // hoặc "accountant"
  businessEntityId: ObjectId,
  sendingMessageMode: "ai_only",  // hoặc "human_only", "ai_with_handover"
  handover?: { handedOverAt, handedOverBy, reason }
}

Cấp Hội thoại (ghi đè inbox):

// NativeInboxConversationDoc.aiReplyAssistantAssignment
// Cấu trúc tương tự - có thể ghi đè phân công cấp inbox

Cấp Inbox Bridge:

// ChatwootInboxBridgeDoc
{
  assistantRole: "sales",
  assistantId: ObjectId,
  // ... URL webhook sử dụng apiKeyId để xác thực
}

So Sánh Tính Năng

Tính năng Native Inbox Inbox Bridge (Chatwoot)
Quyền sở hữu dữ liệu MongoDB của QuotyAI DB Chatwoot bên ngoài
Lưu trữ hội thoại Native (MongoDB) Bên ngoài (Chatwoot API)
Truy xuất tin nhắn Từ DB nội bộ Proxy tới Chatwoot API
Xử lý Webhook Nhận → Lưu → Xử lý Nhận → Xử lý (không lưu)
Kênh hỗ trợ Telegram, Facebook, Instagram, WhatsApp, Voice Bất kỳ kênh nào Chatwoot hỗ trợ (10+)
Độ phức tạp thiết lập Tích hợp API trực tiếp Yêu cầu phiên bản Chatwoot
Lưu trữ tệp đính kèm URL GCS + OCR Chatwoot xử lý lưu trữ
Hội thoại đã xem xét Không áp dụng Dấu hiệu lưu trong QuotyAI
Hợp nhất liên hệ Có (trên nhiều kênh) Chatwoot xử lý liên hệ
Hỗ trợ Voice Có (LiveKit) Qua Chatwoot
Bàn giao AI Triển khai native Qua Chatwoot UI + API
Xử lý OCR Tích hợp sẵn (hình ảnh) Không khả dụng
Nhật ký kiểm toán Đầy đủ (tất cả trong MongoDB) Giới hạn (QuotyAI chỉ lưu dấu hiệu)

Chi Tiết Triển Khai Kỹ Thuật

Các Bộ Sưu Tập (Collections) trong Database

Bộ sưu tập Mục đích Lưu trữ
native-inboxes Cấu hình inbox tenantId, channel, thông tin xác thực, webhookUrl, phân công AI
native-inbox-conversations Luồng hội thoại tenantId, inboxId, contactId, externalId, phân công AI
native-inbox-contacts Hồ sơ liên hệ hợp nhất tenantId, name, email, channelIdentifiers[]
native-inbox-telegram-messages Tin nhắn Telegram conversationId, text, events[], attachedImages[], dữ liệu OCR
native-inbox-facebook-messages Tin nhắn Facebook Cấu trúc tương tự Telegram
voice-inboxes Cấu hình inbox thoại tenantId, name, voiceSettings, assistantId
voice-inbox-sessions Phiên gọi thoại voiceInboxId, roomName, transcript[], callStatus
chatwoot-inbox-bridges Cấu hình bridge host, accountId, agentBotId, access token, phân công assistant
external-chatwoot-accounts Thông tin xác thực tài khoản ngoài host URL, accountId, admin access token
external-chatwoot-reviewed-conversations Dấu hiệu đã xem xét accountId, inboxId, conversationId, ghi chú người xem xét

Kiến Trúc Dịch Vụ

┌─────────────────────────────────────────────────────┐
│                    Tầng API (Hono)                        │
├─────────────────────────────────────────────────────┤
│ /omnichannel/inbox-lifecycles/* → Route CRUD inbox       │
│ /omnichannel/conversations/* → Route hội thoại           │
│ /omnichannel/webhooks/* → Endpoint webhook             │
└──────────────┬──────────────────────────────────────────┘

         ┌──────┴──────┐
         │             │
         ▼             ▼
┌───────▼────────┐ ┌────────────────┐
│ Native        │ │ Chatwoot     │
│ Services      │ │ Services     │
├───────┬────────┤ ├────────┬─────────┤
│ Telegram      │ │ External-    │
│ Facebook     │ │ Chatwoot     │
│ Lifecycle     │ │ Service      │
│ Workflow     │ │ Bridge       │
│ Webhook      │ │ Conversations│
└────────────────┘ └────────────────┘
        │             │
        └──────┬──────┘

┌─────────────────────────────────────────────────────┐
│              Xử Lý AI Thống Nhất                        │
│        UnifiedSalesAssistantChatbotService              │
├─────────────────────────────────────────────────────┤
│ • Bộ điều hợp kênh (Chatwoot, Facebook, Telegram)    │
│ • Hệ thống kỹ năng (8 kỹ năng mô-đun với công cụ)     │
│ • Dynamic Runner (Thực thi TypeScript trong sandbox)    │
│ • Khả năng quan sát (Nhật ký kiểm toán đầy đủ)         │
└─────────────────────────────────────────────────────┘

Ví dụ Cấu hình: Tạo Native Telegram Inbox

// 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: 'My Telegram Bot',
    businessEntityId: '507f1f77bcf86cd799439011',
    apiKeyId: '507f1f77bcf86cd799439012'
  })
});

// Phản hồi bao gồm:
// - ID Inbox
// - Thông tin bot (id, username)
// - Trạng thái webhook
// - Business entity & assistant được tạo tự động (nếu được yêu cầu)

Ví dụ Cấu hình: Tạo Chatwoot Inbox Bridge

// 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: 'My Chatwoot Bridge',
    parentExternalAccountId: '507f1f77bcf86cd799439013',
    assistantRole: 'sales',
    assistantId: '507f1f77bcf86cd799439014',
    apiKeyId: '507f1f77bcf86cd799439015'
  })
});

// Việc này:
// 1. Tạo tài liệu bridge trong MongoDB
// 2. Tạo agent bot trong Chatwoot
// 3. Cấu hình URL webhook
// QuotyAI KHÔNG lưu hội thoại - chỉ lưu cấu hình bridge

Đọc Hội Thoại: Native vs Bridge

// Native Inbox: Từ MongoDB nội bộ
// 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'
  })
});

// Inbox Bridge: Proxy từ Chatwoot API
// GET /omnichannel/conversations/chatwoot-bridge-conversations/conversations/:bridgeId
const bridgeConv = await fetch(`/api/omnichannel/conversations/chatwoot-bridge-conversations/conversations/${bridgeId}?limit=20`);
// Cái này gọi Chatwoot API nội bộ và trả về hội thoại

Khi Nào Nên Dùng Loại Nào?

Chọn Native Inboxes Khi Bạn Muốn:

  • Toàn quyền sở hữu dữ liệu — tất cả dữ liệu trong MongoDB của bạn
  • Tích hợp kênh trực tiếp — không qua trung gian
  • Xử lý tệp đính kèm phong phú — OCR, phân tích hình ảnh
  • Hồ sơ liên hệ hợp nhất trên nhiều kênh
  • Hội tụ Voice/chat — cùng một assistant xử lý cả hai
  • Nhật ký kiểm toán đầy đủ — mọi tin nhắn trong DB của bạn
  • Quy trình làm việc tùy chỉnh — kiểm soát hoàn toàn quá trình xử lý

Phù hợp nhất cho: Doanh nghiệp muốn kiểm soát hoàn toàn, cần xử lý OCR hoặc xử lý dữ liệu nhạy cảm.

Chọn Inbox Bridges Khi Bạn:

  • Đã sử dụng Chatwoot — tận dụng thiết lập hiện có
  • Cần hỗ trợ nhiều kênh hơn — Chatwoot hỗ trợ 10+ kênh
  • Muốn dùng giao diện/tính năng Chatwoot — quản lý hội thoại, giao diện đại lý
  • Không muốn trùng lặp dữ liệu — hội thoại ở lại trong Chatwoot
  • Có nhu cầu định tuyến phức tạp — quy tắc định tuyến nâng cao của Chatwoot

Phù hợp nhất cho: Doanh nghiệp đã dùng Chatwoot hoặc cần các kênh mà QuotyAI chưa hỗ trợ trực tiếp.


Sức Mạnh Của AI Thống Nhất

Cả hai phương pháp đều cung cấp cùng khả năng AI Assistant thông qua UnifiedSalesAssistantChatbotService thống nhất, đảm bảo trải nghiệm khách hàng nhất quán bất kể loại inbox bên dưới.

Khách hàng gửi tin nhắn qua Telegram

Native Inbox (lưu tin nhắn)
        ↓                    HOẶC
Khách hàng gửi tin nhắn qua Chatwoot

Inbox Bridge (chuyển tiếp tới Chatwoot)

        ┌────────────────────────────────┐
        │  Cùng Pipeline Xử Lý AI              │
        │  • 80+ ngôn ngữ                    │
        │  • Thời gian phản hồi 1-2 giây       │
        │  • Định giá xác định                 │
        │  • Bàn giao cho đại lý người        │
        └────────────────────────────────┘

Khách hàng nhận phản hồi nhất quán, chất lượng cao

Tóm Tắt

Kiến trúc inbox kép của QuotyAI mang đến sự linh hoạt để bạn chọn cách tiếp cận phù hợp:

Yếu tố cần cân nhắc Khuyến nghị
Quyền riêng tư dữ liệu quan trọng Sử dụng Native Inboxes
Đã dùng Chatwoot Sử dụng Inbox Bridges
Cần xử lý OCR/tệp đính kèm Sử dụng Native Inboxes
Cần nhanh chóng có 10+ kênh Sử dụng Inbox Bridges
Hội tụ Voice + chat Sử dụng Native Inboxes
Muốn thiết lập đơn giản Cả hai — đều dễ dàng như nhau

Cả hai phương pháp đều là công dân hạng nhất trong QuotyAI, với tích hợp AI Assistant đầy đủ, hỗ trợ business entity và khả năng quan sát toàn diện.