Omnichannel Inboxes & Bridges

QuotyAI uses a dual-channel architecture to handle customer conversations across every platform. Whether you want complete data ownership with Native Inboxes, or prefer to leverage your existing Chatwoot setup with Inbox Bridges, QuotyAI gives you the flexibility to choose the right approach for your business.

Two Ways to Handle Conversations

QuotyAI implements two distinct approaches for managing conversational channels:

1. Native Inboxes: Channels where conversation history is stored natively within QuotyAI’s MongoDB database — you own the data completely.
2. Inbox Bridges: Proxy connections to external Chatwoot instances — QuotyAI processes messages but conversation history lives externally.

Architecture Overview

┌─────────────────────────────────────────────────────┐
│                    Channel Layer                              │
│  Telegram │ Facebook │ WhatsApp │ Instagram │ Voice/LiveKit   │
└──────────────────────┬────────────────────────────────┘
                           │
        ┌──────────────┴──────────────┐
        │                           │
┌───────▼────────┐    ┌───────▼────────┐
│ Native Inboxes │    │ Inbox Bridges  │
│ (Data Owner)  │    │ (Proxy Layer)  │
└───────┬────────┘    └───────┬────────┘
        │                           │
        ▼                           ▼
┌───────────────┐    ┌────────────────┐
│ QuotyAI DB   │    │ Chatwoot API  │
│ (Full Store)  │    │ (Ext. Store) │
└───────┬───────┘    └───────┬────────┘
        │                           │
        └──────────────┬──────────┘
                       ▼
        ┌──────────────────────────────┐
        │  Unified AI Processing       │
        │  (Sales + Management      │
        │   Assistants)             │
        └──────────────────────────────┘

Native Inboxes: Complete Data Ownership

What Are Native Inboxes?

Native inboxes are communication channels where QuotyAI owns the complete conversation lifecycle. Every message, conversation thread, and contact profile is stored directly in your MongoDB database. You get full control, complete audit trails, and rich attachment processing with OCR.

Supported Channels

Data Storage Architecture

┌─────────────────────────────────────────────────────┐
│                  MongoDB (QuotyAI DB)                  │
├─────────────────────────────────────────────────────┤
│ native-inboxes           → Inbox configs & credentials    │
│ native-inbox-conversations → Conversation threads          │
│ native-inbox-contacts    → Unified contact profiles      │
│ native-inbox-telegram-messages → Telegram messages     │
│ native-inbox-facebook-messages → Facebook messages     │
│ voice-inboxes           → Voice inbox configs          │
│ voice-inbox-sessions     → Voice call sessions         │
└─────────────────────────────────────────────────────┘

Core Data Models

NativeInboxDoc (Inbox Configuration)

export interface NativeInboxDoc {
  _id: ObjectId;
  tenantId: ObjectId;
  businessEntityId: ObjectId;  // Links to your business
  name: string;
  channel: NativeInboxChannelType;  // TELEGRAM, FACEBOOK, etc.
  status: NativeInboxStatus;  // 'active' | 'disabled' | 'disconnected'
  
  // Channel-specific credentials (embedded)
  credentials: NativeInboxChannelCredentialsDoc;
  // Telegram: { botToken, botUsername }
  // Facebook:  { pageId, accessToken, appSecret }
  // WhatsApp: { phoneNumberId, businessAccountId }
  
  webhookUrl: string;
  webhookSecret?: string;  // For verification
  
  // AI configuration
  defaultAiReplyAssistantAssignment?: ConversationAiAssignmentDoc;
  
  createdAt: Date;
  updatedAt?: Date;
  deletedAt?: Date;  // Soft delete
}

NativeInboxConversationDoc (Conversation Thread)

export interface NativeInboxConversationDoc {
  _id: ObjectId;
  tenantId: ObjectId;
  inboxId: ObjectId;
  contactId: ObjectId;
  channel: NativeInboxChannelType;
  
  // AI assignment (can override inbox-level default)
  aiReplyAssistantAssignment?: ConversationAiAssignmentDoc;
  
  customAttributes?: Record<string, unknown>;
  externalId: string;  // Telegram chat ID, Facebook PSID, etc.
  
  lastInboundMessage?: { text?: string; createdAt: Date };
  lastOutboundMessage?: { text?: string; createdAt: Date };
  
  createdAt: Date;
  updatedAt?: Date;
  deletedAt?: Date;
}

BaseNativeInboxMessageDoc (Message)

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' }
  
  // Rich attachments (all stored with GCS URLs)
  attachedImages?: NativeInboxMessageImageAttachmentDoc[];     // + OCR data
  attachedVideos?: NativeInboxMessageVideoAttachmentDoc[];
  attachedAudios?: NativeInboxMessageAudioAttachmentDoc[];
  attachedFiles?: NativeInboxMessageFileAttachmentDoc[];
  attachedLocations?: NativeInboxMessageLocationAttachmentDoc[];
  attachedContacts?: NativeInboxMessageContactAttachmentDoc[];
  attachedStickers?: NativeInboxMessageStickerAttachmentDoc[];
  
  externalId?: string;  // Platform message ID
  metadata?: NativeInboxMessageMetadata;  // { runId for observability }
  
  visibleForCustomer: boolean;
  visibleForAi: boolean;
  
  createdAt: Date;
  deletedAt?: Date;
}

How Native Inboxes Work

Message Receiving Flow

Customer sends message
        ↓
Telegram/Facebook API sends webhook to QuotyAI
        ↓
Webhook Receiver (verify secret, check rate limits)
        ↓
Event Queue (priority-based, async processing)
        ↓
Conversation Workflow Service
        ↓
        ├─→ Find/Create Contact (unified profile)
        ├─→ Find/Create Conversation
        ├─→ Store Message (with OCR for images)
        └─→ Call AI Assistant
                ↓
        AI generates response
                ↓
        Send via Channel SDK (Telegram SDK, Facebook SDK)
                ↓
        Store outbound message in MongoDB

Event Queue System

The UnifiedEventQueueService provides robust asynchronous processing:

export enum QueuedEventType {
  MESSAGE = 'message',
  EDITED_MESSAGE = 'edited_message',
  CALLBACK_QUERY = 'callback_query',
  POSTBACK = 'postback',
  // ... 20+ event types supported
}

export enum EventPriority {
  HIGH = 0,    // User messages, payments
  NORMAL = 1,  // Delivery confirmations
  LOW = 2,     // Read receipts, reactions
}

Features:

• Priority-based processing (HIGH → NORMAL → LOW)
• Automatic retry with exponential backoff (max 3 retries)
• Rate limiting per chat ID
• Idempotency (prevents duplicate processing)
• Concurrent processing with configurable limits

Key Services

Inbox Bridges: Proxy Architecture

What Are Inbox Bridges?

Inbox bridges are proxy connections to external Chatwoot instances. Unlike native inboxes, QuotyAI does NOT store conversation history. Instead, it proxies requests to the Chatwoot API in real-time while handling AI processing locally.

Key Concept: Proxy vs Storage

┌─────────────────────────────────────────────────────┐
│                    QuotyAI Stores                        │
├─────────────────────────────────────────────────────┤
│ chatwoot-inbox-bridges → Bridge configs only           │
│ external-chatwoot-accounts → External account credentials │
│ external-chatwoot-reviewed-conversations → Review markers│
└──────────────────────┬────────────────────────────────┘
                       │
                       │ Proxies requests
                       ▼
┌─────────────────────────────────────────────────────┐
│                  Chatwoot Instance                        │
├─────────────────────────────────────────────────────┤
│ Conversations (lives here)                            │
│ Messages (lives here)                                 │
│ Contacts (lives here)                                 │
└─────────────────────────────────────────────────────┘

Supported via Chatwoot

Since Chatwoot supports 10+ channels, inbox bridges indirectly support:

• Facebook Messenger, Instagram, WhatsApp
• Email, Website chat widgets
• Slack, Microsoft Teams
• Any custom channel via API

Data Models

ChatwootInboxBridgeDoc (Bridge Configuration)

export interface ChatwootInboxBridgeDoc {
  _id: ObjectId;
  tenantId: ObjectId;
  name: string;
  isActive: boolean;
  
  // Reference to external Chatwoot account
  parentExternalAccountId?: ObjectId;
  
  // Chatwoot connection details
  chatwootHost?: string;              // e.g., "https://chatwoot.example.com"
  chatwootUserAdminToken?: string;     // Admin API token
  chatwootAccountId?: number;          // Numeric account ID
  chatwootAgentBotId?: number;         // Bot ID in Chatwoot
  chatwootAgentBotAccessToken?: string; // Bot access token
  
  // Inbox identification
  createdChatwootInboxId?: number;       // For internal QuotyAI Chatwoot
  latestConnectedChatwootInboxId?: number; // Last connected inbox
  
  // AI Assistant connection
  apiKeyId: ObjectId;                   // For webhook authentication
  assistantRole?: AssistantRole;          // 'sales' | 'accountant'
  assistantId?: ObjectId;                 // Reference to SalesAssistantDoc
  
  // URLs
  managementUrl?: string;   // Chatwoot management URL
  messengerUrl?: string;  // Public bot URL
  
  createdAt: Date;
  updatedAt?: Date;
  deletedAt?: Date;
}

ExternalChatwootAccountDoc (External Account)

export interface ExternalChatwootAccountDoc {
  _id: ObjectId;
  tenantId: ObjectId;
  name: string;
  host: string;                    // Chatwoot instance URL
  accountId: number;                // Chatwoot account ID
  userAdminAccessToken: string;     // Admin API token
  createdAt: Date;
  deletedAt?: Date;
}

How Inbox Bridges Work

Bridge Creation Flow

User creates bridge in QuotyAI
        ↓
ExternalChatwootService.createExternalChatwootInboxBridge()
        ↓
1. Get external account (host, token from QuotyAI DB)
2. Create MongoDB bridge document (get _id for webhook URL)
        ↓
3. Create agent bot in Chatwoot via API
   POST /api/v1/widget/bots
        ↓
4. Update bridge with access token & bot ID
5. Return bridge data to user

Webhook Processing (Incoming Messages)

When Chatwoot receives a message, it sends a webhook to 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,  // Channel type
          tenantId,
          assistantId,
          { 
            payload, 
            chatwootInboxBridge,
            attachments: [...] 
          },
          signal
        );
      }
      break;
    // ... handle other events
  }
}

Reading Conversations (Proxy Pattern)

// ChatwootConversationsService
async getExternalConversations(
  externalAccountId: string,
  tenantId: ObjectId,
  query: Record<string, unknown>
): Promise<Conversation[]> {
  
  // Get account credentials from QuotyAI DB
  const fullAccount = await this.getFullExternalChatwootAccountById(...);
    
  // Direct proxy to Chatwoot API (NOT from QuotyAI DB)
  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 || [];
}

Marking Conversations as Reviewed

QuotyAI stores a marker in its own DB:

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

Unified AI Processing

Both native inboxes and inbox bridges use the same AI processing pipeline through channel-specific adapters.

UnifiedSalesAssistantChatbotService

export class UnifiedSalesAssistantChatbotService {
  private readonly adapters: Map<UnifiedInboxChannelType, IChatAdapter>;
  
  constructor() {
    // Register adapters for each channel type
    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,  // Different for each channel
    abortSignal: AbortSignal
  ): Promise<ProcessedMessageResult> {
    
    const adapter = this.adapters.get(channelType);
    // Adapter handles:
    // 1. Building AI context (conversation history, etc.)
    // 2. Calling LLM
    // 3. Sending response back to the channel
  }
}

Channel Input Types

Different channels have different input structures:

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

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

// For Chatwoot Bridge
export interface ChatwootChannelInput {
  tenantId: ObjectId;
  conversationId: number;  // Chatwoot conversation ID
  message: string;
  payload: ChatwootWebhookPayload;  // Full webhook payload
  chatwootInboxBridge: ExternalChatwootInboxBridge;
  attachments?: ChatwootAttachment[];
}

Integration with Business Entities

Both inbox types connect to business entities for AI context and configuration.

┌─────────────────────────────────────────────────────┐
│                   Business Entity                         │
├─────────────────────────────────────────────────────┤
│ • Pricing rules & formulas                         │
│ • Service offerings & catalog                       │
│ • Business facts (FAQs, policies)                  │
│ • Instructions for AI assistants                    │
│ • Configuration (timezone, currency, industry)    │
└──────────────┬──────────────────────────────────────┘
               │
        ┌──────┴──────┐
        │             │
        ▼             ▼
┌───────▼────────┐ ┌────────────────┐
│ Sales        │ │ Management    │
│ Assistant   │ │ Assistant    │
└───────┬────────┘ └────────┬─────────┘
       │                 │
       ▼                 ▼
┌───────▼────────┐ ┌────────────────┐
│ Native       │ │ Inbox        │
│ Inboxes      │ │ Bridges      │
│ (Telegram,   │ │ (Chatwoot)   │
│  Facebook...) │ │              │
└────────────────┘ └────────────────┘

AI Assistant Assignment

Native Inbox level:

// NativeInboxDoc.defaultAiReplyAssistantAssignment
{
  mode: "fixed_assistant",  // or "dynamic_latest"
  assistantId: ObjectId,        // Reference to SalesAssistantDoc
  assistantRole: "sales",       // or "accountant"
  businessEntityId: ObjectId,
  sendingMessageMode: "ai_only",  // or "human_only", "ai_with_handover"
  handover?: { handedOverAt, handedOverBy, reason }
}

Conversation level (overrides inbox):

// NativeInboxConversationDoc.aiReplyAssistantAssignment
// Same structure - can override inbox-level assignment

Inbox Bridge level:

// ChatwootInboxBridgeDoc
{
  assistantRole: "sales",
  assistantId: ObjectId,
  // ... webhook URL uses apiKeyId for authentication
}

Feature Comparison

Technical Implementation Details

Database Collections

Service Architecture

┌─────────────────────────────────────────────────────┐
│                    API Layer (Hono)                        │
├─────────────────────────────────────────────────────┤
│ /omnichannel/inbox-lifecycles/* → Inbox CRUD routes      │
│ /omnichannel/conversations/* → Conversation routes         │
│ /omnichannel/webhooks/* → Webhook endpoints             │
└──────────────┬──────────────────────────────────────────┘
               │
        ┌──────┴──────┐
        │             │
        ▼             ▼
┌───────▼────────┐ ┌────────────────┐
│ Native       │ │ Chatwoot     │
│ Services     │ │ Services     │
├───────┬────────┤ ├────────┬─────────┤
│ Telegram     │ │ External-    │
│ Facebook    │ │ Chatwoot     │
│ Lifecycle    │ │ Service      │
│ Workflow    │ │ Bridge       │
│ Webhook     │ │ Conversations│
└────────────────┘ └────────────────┘
        │             │
        └──────┬──────┘
               ▼
┌─────────────────────────────────────────────────────┐
│              Unified AI Processing                       │
│        UnifiedSalesAssistantChatbotService              │
├─────────────────────────────────────────────────────┤
│ • Channel Adapters (Chatwoot, Facebook, Telegram)    │
│ • Skills System (8 modular skills with tools)          │
│ • Dynamic Runner (Sandboxed TypeScript execution)      │
│ • Observability (Full audit trails)                    │
└─────────────────────────────────────────────────────┘

Configuration Example: Creating a 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'
  })
});

// Response includes:
// - Inbox ID
// - Bot info (id, username)
// - Webhook status
// - Auto-created business entity & assistant (if requested)

Configuration Example: Creating a 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'
  })
});

// This:
// 1. Creates MongoDB bridge document
// 2. Creates agent bot in Chatwoot
// 3. Configures webhook URL
// QuotyAI does NOT store conversations - only bridge config

Reading Conversations: Native vs Bridge

// Native Inbox: From local 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'
  })
});

// Inbox Bridge: Proxied from Chatwoot API
// GET /omnichannel/conversations/chatwoot-bridge-conversations/conversations/:bridgeId
const bridgeConv = await fetch(`/api/omnichannel/conversations/chatwoot-bridge-conversations/conversations/${bridgeId}?limit=20`);
// This calls Chatwoot API internally and returns conversations

When to Use Which?

Choose Native Inboxes When You Want:

• ✅ Complete data ownership — all data in your MongoDB
• ✅ Direct channel integration — no middleware
• ✅ Rich attachment processing — OCR, image analysis
• ✅ Unified contact profiles across channels
• ✅ Voice/chat convergence — same assistant handles both
• ✅ Full audit trails — every message in your DB
• ✅ Custom workflows — full control over processing

Best for: Businesses that want full control, need OCR processing, or handle sensitive data.

Choose Inbox Bridges When You:

• ✅ Already use Chatwoot — leverage existing setup
• ✅ Need broader channel support — Chatwoot supports 10+ channels
• ✅ Want Chatwoot’s UI/features — conversation management, agent interface
• ✅ Prefer not to duplicate data — conversations stay in Chatwoot
• ✅ Have complex routing needs — Chatwoot’s advanced routing rules

Best for: Businesses already on Chatwoot, or those needing channels QuotyAI doesn’t natively support yet.

The Power of Unified AI

Both approaches provide the same AI assistant capabilities through the unified UnifiedSalesAssistantChatbotService, ensuring consistent customer experience regardless of the underlying inbox type.

Customer sends message via Telegram
        ↓
Native Inbox (stores message)
        ↓                    OR
Customer sends message via Chatwoot
        ↓
Inbox Bridge (proxies to Chatwoot)
        ↓
        ┌────────────────────────────────┐
        │  Same AI Processing Pipeline         │
        │  • 80+ languages                  │
        │  • 1-2 second response time       │
        │  • Deterministic pricing           │
        │  • Handover to human agents     │
        └────────────────────────────────┘
        ↓
Customer receives consistent, high-quality response

Summary

QuotyAI’s dual inbox architecture gives you the flexibility to choose the right approach:

Both approaches are first-class citizens in QuotyAI, with full AI assistant integration, business entity support, and comprehensive observability.