Support Inbox Controller

Controller: support.inbox.controller.js
Module: Conversation-v2
Purpose: Manages support inboxes for routing customer conversations to agent teams

Overview

The Support Inbox controller handles the creation and management of support inboxes (teams). Inboxes route incoming support requests to appropriate agent groups using configurable algorithms (round-robin, load-based, etc.).

Methods

1. Get Inboxes (getInboxes)

Retrieves all support inboxes for the account.

Endpoint: GET /api/conversation-v2/support/inbox

Authentication: Required (JWT + conversation context)

Query Parameters:

{
  src?: string;  // Source filter
}

Response:

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Technical Support",
      "icon": "🛠️",
      "members": [
        {
          "conversation_id": "507f1f77bcf86cd799439012",
          "role": "agent"
        }
      ],
      "algorithm": "round_robin",
      "live_routing_visibility": true,
      "active_conversations": 12,
      "total_handled": 450
    }
  ]
}

MongoDB Operations:

Collection	Operation	Query	Purpose
support_inboxes	find	{ account_id }	Get all inboxes

Use Cases:

• Displaying inbox list in admin panel
• Routing dashboard
• Agent assignment overview

---

2. Get Inbox (getInbox)

Retrieves a single inbox by ID.

Endpoint: GET /api/conversation-v2/support/inbox/:inboxId

Authentication: Required (JWT + conversation context)

Response:

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Technical Support",
    "icon": "🛠️",
    "members": [
      {
        "conversation_id": "507f1f77bcf86cd799439012",
        "user": {
          "name": "John Doe",
          "email": "john@example.com"
        },
        "role": "agent",
        "capacity": 5,
        "current_load": 2
      }
    ],
    "algorithm": "load_based",
    "statistics": {
      "total_conversations": 450,
      "active_conversations": 12,
      "avg_response_time": 180
    }
  }
}

MongoDB Operations:

Collection	Operation	Query	Purpose
support_inboxes	findOne	{ _id: inboxId }	Get inbox details

Use Cases:

• Inbox configuration page
• Viewing inbox statistics
• Member management

---

3. Create Inbox (createInbox)

Creates a new support inbox.

Endpoint: POST /api/conversation-v2/support/inbox

Authentication: Required (JWT + conversation context)

Request Body:

{
  "name": "Technical Support",
  "icon": "🛠️",
  "members": ["507f1f77bcf86cd799439012", "507f1f77bcf86cd799439013"],
  "algorithm": "round_robin",
  "live_routing_visibility": true
}

Response:

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439020",
    "name": "Technical Support",
    "icon": "🛠️",
    "members": [
      {
        "conversation_id": "507f1f77bcf86cd799439012",
        "role": "agent",
        "added_at": "2025-10-08T10:30:00.000Z"
      }
    ],
    "algorithm": "round_robin",
    "created_by": "507f1f77bcf86cd799439015",
    "created_at": "2025-10-08T10:30:00.000Z"
  }
}

MongoDB Operations:

Collection	Operation	Query	Purpose
support_inboxes	insertOne	New inbox	Create inbox

Business Logic:

• Creator automatically added as inbox admin
• All specified members added as agents
• Emits Socket.IO event to notify team
• Algorithm determines routing strategy

Routing Algorithms:

• round_robin - Distribute evenly in sequence
• load_based - Assign to least busy agent
• random - Random assignment
• manual - No automatic routing

Use Cases:

• Creating specialized support teams
• Departmental inbox setup
• Skill-based routing groups

---

4. Update Inbox (updateInbox)

Updates inbox settings.

Endpoint: PATCH /api/conversation-v2/support/inbox/:inboxId

Authentication: Required (JWT + conversation context)

Request Body:

{
  "name": "Premium Technical Support",
  "algorithm": "load_based",
  "live_routing_visibility": false
}

Response:

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Premium Technical Support",
    "algorithm": "load_based",
    "updated_at": "2025-10-08T10:30:00.000Z"
  }
}

MongoDB Operations:

Collection	Operation	Query/Update	Purpose
support_inboxes	updateOne	$set fields	Update settings

Updatable Fields:

• name - Inbox display name
• icon - Emoji icon
• algorithm - Routing algorithm
• live_routing_visibility - Show real-time assignments

---

5. Delete Inbox (deleteInbox)

Deletes a support inbox.

Endpoint: DELETE /api/conversation-v2/support/inbox/:inboxId

Authentication: Required (JWT + conversation context)

Response:

{
  "success": true
}

MongoDB Operations:

Collection	Operation	Query	Purpose
support_inboxes	deleteOne	{ _id: inboxId }	Remove inbox

Business Logic:

• Only inbox creator or admin can delete
• Active conversations reassigned or remain unassigned
• Member access revoked immediately

---

6. Add Member (addMember)

Adds an agent to the inbox.

Endpoint: POST /api/conversation-v2/support/inbox/:inboxId/member

Authentication: Required (JWT + conversation context)

Query Parameters:

{
  memberId: string; // Conversation ID to add
}

Response:

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "members": [
      {
        "conversation_id": "507f1f77bcf86cd799439020",
        "role": "agent",
        "added_at": "2025-10-08T10:30:00.000Z"
      }
    ]
  }
}

MongoDB Operations:

Collection	Operation	Query/Update	Purpose
support_inboxes	updateOne	$addToSet member	Add member

Business Logic:

• Member added as "agent" role by default
• Prevents duplicate additions
• Member can now receive routed conversations

---

7. Remove Member (removeMember)

Removes an agent from the inbox.

Endpoint: DELETE /api/conversation-v2/support/inbox/:inboxId/member

Authentication: Required (JWT + conversation context)

Query Parameters:

{
  memberId: string; // Conversation ID to remove
}

Response:

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "members": [
      // Remaining members
    ]
  }
}

MongoDB Operations:

Collection	Operation	Query/Update	Purpose
support_inboxes	updateOne	$pull member	Remove member

Business Logic:

• Removes member from routing pool
• Active conversations remain assigned
• Cannot remove last member

---

Data Models

Support Inbox Schema

{
  _id: ObjectId;
  account_id: ObjectId;
  name: string;
  icon: string;

  // Membership
  members: Array<{
    conversation_id: ObjectId;
    role: 'admin' | 'agent';
    capacity?: number; // Max concurrent chats
    added_at: Date;
  }>;

  // Routing
  algorithm: 'round_robin' | 'load_based' | 'random' | 'manual';
  live_routing_visibility: boolean;

  // Statistics
  total_conversations: number;
  active_conversations: number;

  // Metadata
  created_by: ObjectId;
  created_at: Date;
  updated_at: Date;
}

---

Socket.IO Integration

// New inbox event
socket.to(accountId).emit('inbox:created', {
  inbox: inboxObject,
});

// Member added event
socket.to(inboxId).emit('inbox:member_added', {
  inbox_id: inboxId,
  member: memberObject,
});

---

Performance Considerations

Indexing

db.support_inboxes.createIndex({ account_id: 1 });
db.support_inboxes.createIndex({ 'members.conversation_id': 1 });

---

Last Updated: October 8, 2025
Documented By: AI Documentation System
Source: internal/api/v1/conversation-v2/controllers/support.inbox.controller.js