Support Room Controller

Controller: support.room.controller.js
Module: Conversation-v2
Purpose: Manages support chat rooms including customer-agent assignments, room status, priorities, and widget statistics

Overview

The Support Room controller handles support ticket/room lifecycle management. It enables creating support rooms from customer sessions, assigning agents, managing status (open/pending/closed), setting priorities, and tracking support metrics.

Methods Summary

#	Method	Endpoint	Purpose
1	getRooms	GET /room	List agent's assigned rooms
2	getRoomId	GET /room/id	Find room by contact info
3	getRoom	GET /room/:room_id	Get room details
4	getUserRooms	GET /user/room	List customer's rooms (widget)
5	createRoom	POST /user/room	Customer creates room
6	createInternalRoom	POST /room/internal	Agent creates room for contact
7	updateRoom	PATCH /room	Update room status/priority
8	updateAssignee	PATCH /room/assignee	Reassign agents
9	updateStatus	PATCH /room/status	Change room status
10	toggleFavorite	POST /room/:roomId/favorite	Favorite/unfavorite
11	snooze	POST /room/:roomId/snooze	Snooze notifications
12	widget	GET /widget	Get widget statistics

---

Core Methods

1. Get Rooms (Agent View) (getRooms)

Retrieves support rooms assigned to or visible by the agent.

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

Query Parameters:

{
  page?: number;
  search?: string;
  sort?: 'created_at' | 'updated_at' | 'priority';
  filter?: {
    status?: 'open' | 'pending' | 'closed';
    priority?: 'low' | 'medium' | 'high' | 'urgent';
    inbox_id?: string;
  };
  limit?: number;
  conversation_id?: string;  // View another agent's rooms (admin)
}

Response:

{
  "rooms": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "contact": {
        "name": "John Doe",
        "email": "john@example.com"
      },
      "inbox": {
        "_id": "507f1f77bcf86cd799439012",
        "name": "Technical Support"
      },
      "status": "open",
      "priority": "high",
      "assignees": ["507f1f77bcf86cd799439013"],
      "last_message": {
        "content": "I need help with...",
        "created_at": "2025-10-08T10:30:00.000Z"
      },
      "unread_count": 3,
      "created_at": "2025-10-08T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45
  }
}

Filtering & Sorting:

• Filter by status, priority, inbox
• Sort by creation date, update time, priority level
• Search across contact names and messages

---

2. Get Room ID (getRoomId)

Finds or creates a room ID based on contact information.

Endpoint: GET /api/conversation-v2/support/room/id

Query Parameters:

{
  email?: string;
  phone?: string;
  contact_id?: string;
}

Response:

{
  "success": true,
  "data": {
    "room_id": "507f1f77bcf86cd799439011",
    "exists": true
  }
}

Business Logic:

• Searches for existing room by contact
• Returns room ID if found
• Used before creating duplicate rooms

---

3. Get Room (getRoom)

Retrieves detailed information about a specific support room.

Endpoint: GET /api/conversation-v2/support/room/:room_id

Response:

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "conversation_id": "507f1f77bcf86cd799439031",
    "contact": {
      "_id": "507f1f77bcf86cd799439032",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1234567890"
    },
    "inbox_id": "507f1f77bcf86cd799439012",
    "status": "open",
    "priority": "high",
    "assignees": [
      {
        "conversation_id": "507f1f77bcf86cd799439013",
        "user": {
          "name": "Agent Smith",
          "email": "smith@example.com"
        }
      }
    ],
    "tags": ["billing", "urgent"],
    "notes": "VIP customer - handle with priority",
    "created_at": "2025-10-08T10:00:00.000Z",
    "last_activity": "2025-10-08T11:00:00.000Z"
  }
}

---

4. Get User Rooms (Customer View) (getUserRooms)

Retrieves customer's support rooms (widget view).

Endpoint: GET /api/conversation-v2/support/user/room

Authentication: Support token + session

Query Parameters:

{
  page?: number;
  search?: string;
  limit?: number;
  verified?: boolean;  // Filter by verification status
}

Response:

{
  "rooms": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "subject": "Account access issue",
      "status": "open",
      "last_message": {
        "content": "We're looking into this...",
        "created_at": "2025-10-08T10:45:00.000Z"
      },
      "unread_count": 1,
      "created_at": "2025-10-08T10:00:00.000Z"
    }
  ]
}

Business Logic:

• Shows only customer's own rooms
• Filters by session verification if required
• Simplified view (no agent/internal details)

---

5. Create Room (Customer) (createRoom)

Customer creates a new support room from widget.

Endpoint: POST /api/conversation-v2/support/user/room

Authentication: Support token + session

Headers:

X-Support-Session: <session_id>

Request Body:

{
  "inbox_id": "507f1f77bcf86cd799439012",
  "description": "I can't access my account"
}

Response:

{
  "success": true,
  "result": {
    "id": "507f1f77bcf86cd799439050",
    "status": "open",
    "inbox_id": "507f1f77bcf86cd799439012",
    "created_at": "2025-10-08T10:30:00.000Z"
  }
}

Business Logic:

• Creates room linked to support conversation
• Routes to specified inbox for agent assignment
• Emits Socket.IO event to notify agents
• Initial message created from description

Room Creation Flow:

graph TD
    A[Customer Submits Form] --> B[Validate Session]
    B --> C[Create Support Room]
    C --> D[Route to Inbox]
    D --> E{Routing Algorithm}
    E -->|Round Robin| F[Next Agent]
    E -->|Load Based| G[Least Busy Agent]
    E -->|Manual| H[Unassigned]
    F --> I[Notify Agent]
    G --> I
    H --> J[Queue for Assignment]

---

6. Create Internal Room (createInternalRoom)

Agent creates a support room for a contact (proactive support).

Endpoint: POST /api/conversation-v2/support/room/internal

Authentication: Required (JWT - agent)

Request Body:

{
  "inbox_id": "507f1f77bcf86cd799439012",
  "contact_id": "507f1f77bcf86cd799439032"
}

Response:

{
  "success": true,
  "result": {
    "id": "507f1f77bcf86cd799439060",
    "assignee_id": "507f1f77bcf86cd799439013",
    "contact_id": "507f1f77bcf86cd799439032",
    "created_at": "2025-10-08T10:30:00.000Z"
  }
}

Business Logic:

• Agent initiates conversation with contact
• Creator automatically assigned
• Used for proactive outreach

---

7. Update Room (updateRoom)

Updates room status or priority.

Endpoint: PATCH /api/conversation-v2/support/room

Request Body:

{
  "room_id": "507f1f77bcf86cd799439011",
  "status": "closed",
  "priority": "low"
}

Response:

{
  "success": true,
  "message": "Room updated successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "status": "closed",
    "priority": "low",
    "updated_at": "2025-10-08T10:30:00.000Z"
  }
}

Status Values:

• open - Active conversation
• pending - Waiting for customer
• closed - Resolved/archived

Priority Levels:

• low - Non-urgent
• medium - Standard priority
• high - Important
• urgent - Critical issue

---

8. Update Assignee (updateAssignee)

Reassigns room to different agents.

Endpoint: PATCH /api/conversation-v2/support/room/assignee

Request Body:

{
  "room_id": "507f1f77bcf86cd799439011",
  "conversation_ids": ["507f1f77bcf86cd799439013", "507f1f77bcf86cd799439014"],
  "inbox_id": "507f1f77bcf86cd799439012"
}

Response:

{
  "success": true,
  "message": "Assignee updated successfully",
  "data": {
    "assignees": [
      {
        "conversation_id": "507f1f77bcf86cd799439013",
        "assigned_at": "2025-10-08T10:30:00.000Z"
      }
    ]
  }
}

Business Logic:

• Replaces current assignees
• Notifies new assignees via Socket.IO
• Can assign multiple agents

---

9. Toggle Favorite (toggleFavorite)

Marks/unmarks room as favorite for agent.

Endpoint: POST /api/conversation-v2/support/room/:roomId/favorite

Response:

{
  "success": true,
  "room": {
    "_id": "507f1f77bcf86cd799439011",
    "is_favorite": true
  }
}

---

10. Snooze Room (snooze)

Temporarily mutes room notifications.

Endpoint: POST /api/conversation-v2/support/room/:roomId/snooze

Request Body:

{
  "time": 1633110000000
}

Response:

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "snoozed_until": 1633110000000
  }
}

---

11. Widget Statistics (widget)

Retrieves statistics for support widget dashboard.

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

Authentication: Required (JWT - agent)

Response:

{
  "success": true,
  "data": {
    "total_rooms": 450,
    "open_rooms": 12,
    "pending_rooms": 8,
    "closed_rooms": 430,
    "avg_response_time": 180,
    "agent_stats": {
      "active_agents": 5,
      "available_seats": 3,
      "current_load": 12
    }
  }
}

Business Logic:

• Real-time statistics for dashboard
• Agent availability metrics
• Performance indicators

---

Data Models

Support Room Schema

{
  _id: ObjectId;
  account_id: ObjectId;
  conversation_id: ObjectId;     // Support conversation
  contact_id: ObjectId;
  inbox_id: ObjectId;

  // Assignment
  assignees: ObjectId[];         // Conversation IDs of agents

  // Status
  status: 'open' | 'pending' | 'closed';
  priority: 'low' | 'medium' | 'high' | 'urgent';

  // Metadata
  tags: string[];
  notes: string;

  // User Preferences
  favorites: ObjectId[];
  snoozed_until: number;

  // Timestamps
  created_at: Date;
  updated_at: Date;
  last_activity: Date;
  closed_at?: Date;
}

---

Socket.IO Events

// Room created
socket.to(conversationId).emit('joinRoom', {
  room_id: roomId,
  type: 'support',
});

// Room updated
socket.to(accountId).emit('updateRoom', {
  room_id: roomId,
  type: 'status',
  data: updateData,
});

---

Performance Considerations

Indexing

db.support_rooms.createIndex({
  account_id: 1,
  assignees: 1,
  status: 1,
});
db.support_rooms.createIndex({
  contact_id: 1,
  status: 1,
});
db.support_rooms.createIndex({
  inbox_id: 1,
  last_activity: -1,
});

---

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