Conversation Controller

Controller: conversation.controller.js
Module: Conversation-v2
Purpose: Manages user conversation state, preferences, and status within the messaging system

Overview

The Conversation controller handles the core conversation entity operations including user status management, conversation details updates, DND (Do Not Disturb) settings, and support-specific configurations. Each conversation represents a user's presence and state in the messaging system.

Methods

1. Get Conversation (`getConv`)

Retrieves the authenticated user's conversation details.

Endpoint: GET /api/conversation-v2/conversation

Authentication: Required (JWT)

Request:

// Headers
Authorization: Bearer <token>

Response:

{
  "_id": "507f1f77bcf86cd799439011",
  "account_id": "507f1f77bcf86cd799439012",
  "user_id": "507f1f77bcf86cd799439013",
  "dnd_till": null,
  "favorite": [],
  "support_dnd_till": null,
  "support_favorite": [],
  "status": [
    {
      "type": "online",
      "timestamp": 1633024800000
    }
  ],
  "last_activity": 1633024800000,
  "support_status": "available",
  "default_email_inbound_conversation": "507f1f77bcf86cd799439014",
  "default_sms_inbound_conversation": "507f1f77bcf86cd799439015",
  "support_live_seat": true
}

MongoDB Operations:

Collection	Operation	Query	Purpose
`conversations`	`findOne`	`{ account_id, user_id }`	Get user's conversation

Business Logic:

Returns the conversation entity for the authenticated user
Used to initialize user's messaging state on login
Contains preferences for both team and support conversations

2. Get Associated Conversations (`getAssociated`)

Retrieves team conversations associated with the current user's conversation scope.

Endpoint: GET /api/conversation-v2/conversation/associated

Authentication: Required (JWT + conversation context)

Query Parameters:

{
  scopes?: string[];      // Filter by conversation scopes
  search?: string;        // Search query
  type?: string;          // Conversation type filter
  default_inbound?: string; // Filter default inbound conversations
}

Request:

GET /api/conversation-v2/conversation/associated?scopes=team&search=john&type=user
Authorization: Bearer <token>

Response:

{
  "success": true,
  "conversations": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "user_id": "507f1f77bcf86cd799439013",
      "account_id": "507f1f77bcf86cd799439012",
      "user": {
        "name": "John Doe",
        "email": "john@example.com",
        "avatar": "https://cdn.example.com/avatars/john.jpg"
      },
      "status": [
        {
          "type": "online",
          "timestamp": 1633024800000
        }
      ],
      "last_activity": 1633024800000
    }
  ]
}

MongoDB Operations:

Collection	Operation	Query	Purpose
`conversations`	`find`	Multiple filters	Get team conversations

Business Logic:

Filters conversations based on scope (e.g., team members, support agents)
Supports search functionality for finding specific team members
Used for populating team member lists in the UI

Use Cases:

Displaying team members in chat interface
Finding users to start conversations with
Filtering support agents by availability

3. Get Bots (`getBots`)

Retrieves list of available bot configurations for the messaging system.

Endpoint: GET /api/conversation-v2/conversation/bots

Authentication: Required (JWT)

Request:

GET /api/conversation-v2/conversation/bots
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": [
    {
      "id": "bot_1",
      "name": "Support Bot",
      "type": "automated_response",
      "avatar": "https://cdn.example.com/bots/support.png",
      "description": "Handles automated support responses"
    },
    {
      "id": "bot_2",
      "name": "Sales Bot",
      "type": "lead_qualification",
      "avatar": "https://cdn.example.com/bots/sales.png",
      "description": "Qualifies leads and schedules demos"
    }
  ]
}

Business Logic:

Returns hardcoded or configured bot list from service layer
Bots can be used for automated responses in conversations
No database query required (static configuration)

Use Cases:

Displaying available bots to assign to conversations
Auto-responder configuration
Chatbot integration setup

4. Update Conversation Details (`updateDetails`)

Updates various conversation settings including DND status and favorites.

Endpoint: PATCH /api/conversation-v2/conversation/details

Authentication: Required (JWT)

Request Body:

{
  "details": {
    "dnd_till": 1633110000000,
    "favorite": ["507f1f77bcf86cd799439016", "507f1f77bcf86cd799439017"],
    "support_dnd_till": null,
    "support_favorite": ["507f1f77bcf86cd799439018"]
  }
}

Response:

{
  "success": true,
  "message": "Details updated"
}

MongoDB Operations:

Collection	Operation	Query/Update	Purpose
`conversations`	`findOne`	`{ account_id, user_id }`	Get current conversation
`conversations`	`updateOne`	`$set` details + `last_activity`	Update conversation settings

Business Logic:

Automatically sets last_activity timestamp on update
Merges provided details with existing values (partial updates)
Only updates fields that are explicitly provided in request
Validates conversation exists before updating

Updatable Fields:

Field	Type	Description
`dnd_till`	Number (timestamp)	Do Not Disturb until this timestamp
`favorite`	ObjectId[]	List of favorite conversation IDs
`support_dnd_till`	Number (timestamp)	Support DND setting
`support_favorite`	ObjectId[]	Support favorite conversations

Error Responses:

// Conversation not found
{
  "error": "Conversation does not exist",
  "statusCode": 404
}

Use Cases:

Setting Do Not Disturb mode
Managing favorite conversations for quick access
Updating notification preferences

5. Update Status (`updateStatus`)

Updates the user's conversation status (online, away, busy, offline).

Endpoint: PATCH /api/conversation-v2/conversation/status

Authentication: Required (JWT)

Request Body:

{
  "status": {
    "type": "away",
    "timestamp": 1633024800000
  }
}

Response:

{
  "success": true,
  "message": "Details updated"
}

MongoDB Operations:

Collection	Operation	Query/Update	Purpose
`conversations`	`findOne`	`{ account_id, user_id }`	Get current conversation
`conversations`	`updateOne`	`$push` status, update `last_activity`	Append new status

Business Logic:

Status changes are appended to a history array
Prevents duplicate status updates (cannot set same status twice in a row)
Each status includes a timestamp for tracking
Automatically updates last_activity field

Status Flow:

graph LR
    A[Current Status: online] --> B{New Status}
    B -->|Same as current| C[Error: Duplicate Status]
    B -->|Different| D[Append to Array]
    D --> E[Update last_activity]
    E --> F[Success Response]

Status Types:

online - User is active
away - User is idle
busy - User is in focus mode
offline - User is disconnected

Error Responses:

// Duplicate status
{
  "error": "Current status cannot be same as last status",
  "statusCode": 400
}

// Conversation not found
{
  "error": "Conversation does not exist",
  "statusCode": 404
}

Use Cases:

Automatic status updates based on user activity
Manual status changes by user
Presence indicators in UI
Availability tracking for support agents

6. Update Support Status (`supportStatus`)

Updates support-specific settings including availability, routing, and live seat allocation.

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

Authentication: Required (JWT + conversation context)

Request Body:

{
  "conversationId": "507f1f77bcf86cd799439011",
  "status": "available",
  "default_email_inbound_conversation": "507f1f77bcf86cd799439014",
  "default_sms_inbound_conversation": "507f1f77bcf86cd799439015",
  "live_seat": true
}

Response:

{
  "success": true,
  "conversation": {
    "_id": "507f1f77bcf86cd799439011",
    "support_status": "available",
    "default_email_inbound_conversation": "507f1f77bcf86cd799439014",
    "default_sms_inbound_conversation": "507f1f77bcf86cd799439015",
    "support_live_seat": true,
    "last_activity": 1633024800000
  }
}

MongoDB Operations:

Collection	Operation	Query/Update	Purpose
`conversations`	`updateOne`	Update support fields	Update target conversation

Business Logic:

Only updates fields that are explicitly provided (undefined values are filtered out)
Can update support status for other team members (admin functionality)
Validates conversation ID against authenticated user's context
Used for managing support agent availability

Updatable Fields:

Field	Type	Description
`status` (support_status)	String	Agent availability status
`default_email_inbound_conversation`	ObjectId	Default conversation for email leads
`default_sms_inbound_conversation`	ObjectId	Default conversation for SMS leads
`live_seat` (support_live_seat)	Boolean	Whether agent occupies a live support seat

Support Status Values:

available - Ready to receive new support requests
busy - Currently handling maximum capacity
offline - Not available for support

Use Cases:

Support agent toggling availability
Routing configuration for inbound leads
Live seat management for concurrent chat limits
Admin managing team member support settings

Workflow:

graph TD
    A[Admin/User Request] --> B{Validate Conversation}
    B -->|Valid| C[Filter Undefined Fields]
    C --> D[Update Support Settings]
    D --> E[Return Updated Conversation]
    B -->|Invalid| F[Error: Unauthorized]

Data Models

Conversation Schema

{
  _id: ObjectId;
  account_id: ObjectId;          // Account this conversation belongs to
  user_id: ObjectId;             // User associated with conversation

  // Team Chat Settings
  dnd_till: number | null;       // Do Not Disturb timestamp
  favorite: ObjectId[];          // Favorite conversation IDs

  // Support Settings
  support_dnd_till: number | null;
  support_favorite: ObjectId[];
  support_status: string;        // 'available' | 'busy' | 'offline'
  support_live_seat: boolean;    // Occupies live support slot

  // Routing Configuration
  default_email_inbound_conversation: ObjectId;
  default_sms_inbound_conversation: ObjectId;

  // Status Tracking
  status: Array<{
    type: string;                // 'online' | 'away' | 'busy' | 'offline'
    timestamp: number;
  }>;
  last_activity: number;

  // Timestamps
  created_at: Date;
  updated_at: Date;
}

Status Entry

{
  type: 'online' | 'away' | 'busy' | 'offline';
  timestamp: number; // Unix timestamp in milliseconds
}

Error Handling

Common Errors

Status Code	Error	Cause
400	Current status cannot be same as last status	Duplicate status update
404	Conversation does not exist	Invalid conversation ID
401	Unauthorized	Missing or invalid JWT token

Error Response Format

{
  "error": "Error message",
  "statusCode": 400
}

Integration Points

Dependencies

convService: Business logic for conversation operations
- queryConversation(accountId, userId) - Get conversation by user
- queryTeamConversations(params) - Get associated team conversations
- getBots() - Get bot configurations
- updateDetails(accountId, userId, details) - Update conversation details
- supportStatus(params) - Update support-specific settings

Socket.IO Events

While not directly emitted in this controller, status changes trigger real-time updates:

Event: conversation:status
- Triggered when user status changes
- Broadcasts to all team members
Event: conversation:details
- Triggered when conversation details update
- Notifies affected users

Multi-tenant Isolation

All operations are scoped by account_id from JWT:

const accountId = req.auth.account_id;
const userId = req.auth.uid;

This ensures users can only access conversations within their account.

Performance Considerations

Optimization Strategies

Status History:
- Status array grows over time
- Consider archiving old status entries periodically
- Current implementation keeps full history
Favorite Lists:
- Favorite arrays can grow large
- No pagination currently implemented
- Consider limiting favorites or implementing pagination
Associated Conversations Query:
- Can return many results for large teams
- Implement pagination if needed
- Consider caching team member lists

Use Cases

Team Chat Application

User Login:

User logs in → getConv() → Initialize conversation state
→ Display user's status, DND settings, favorites

Status Management:

User changes status → updateStatus() → Broadcast to team
→ Update presence indicators in UI

Finding Team Members:

User searches team → getAssociated() with search param
→ Display filtered team member list

Support System

Agent Availability:

Agent goes online → supportStatus({ status: 'available' })
→ Enable routing to this agent

Routing Configuration:

Admin assigns default conversations → supportStatus()
→ New email/SMS leads route to specified agent

Live Seat Management:

Agent reaches capacity → supportStatus({ live_seat: false })
→ Prevent new assignments until capacity available

Security Considerations

Authentication:
- All endpoints require valid JWT token
- Token provides account_id, user_id, and conversation.id
Authorization:
- Users can only update their own conversation details
- supportStatus can update other conversations (admin functionality)
- Validation should ensure proper permissions
Data Isolation:
- All queries filtered by account_id
- Prevents cross-account data leakage

Testing Recommendations

Unit Tests

describe('Conversation Controller', () => {
  describe('getConv', () => {
    it('should return user conversation', async () => {});
    it('should handle non-existent conversation', async () => {});
  });

  describe('updateStatus', () => {
    it('should append new status', async () => {});
    it('should reject duplicate status', async () => {});
    it('should update last_activity', async () => {});
  });

  describe('updateDetails', () => {
    it('should update DND settings', async () => {});
    it('should update favorites', async () => {});
    it('should handle partial updates', async () => {});
  });
});

Integration Tests

Test status change propagation to Socket.IO
Verify multi-tenant isolation
Test concurrent status updates
Validate favorite list management

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

Overview​

Methods​

1. Get Conversation (getConv)​

2. Get Associated Conversations (getAssociated)​

3. Get Bots (getBots)​

4. Update Conversation Details (updateDetails)​

5. Update Status (updateStatus)​

6. Update Support Status (supportStatus)​

Data Models​

Conversation Schema​

Status Entry​

Error Handling​

Common Errors​

Error Response Format​

Integration Points​

Dependencies​

Socket.IO Events​

Multi-tenant Isolation​

Performance Considerations​

Optimization Strategies​

Use Cases​

Team Chat Application​

Support System​

Security Considerations​

Testing Recommendations​

Unit Tests​

Integration Tests​

Documentation Assistant

Overview

Methods

1. Get Conversation (`getConv`)

2. Get Associated Conversations (`getAssociated`)

3. Get Bots (`getBots`)

4. Update Conversation Details (`updateDetails`)

5. Update Status (`updateStatus`)

6. Update Support Status (`supportStatus`)

Data Models

Conversation Schema

Status Entry

Error Handling

Common Errors

Error Response Format

Integration Points

Dependencies

Socket.IO Events

Multi-tenant Isolation

Performance Considerations

Optimization Strategies

Use Cases

Team Chat Application

Support System

Security Considerations

Testing Recommendations

Unit Tests

Integration Tests