Chat
13 min
Detailed Functionality & Workflow Specification
1. Introduction & Vision
The CommandIT Chat system is an integrated communication platform designed to streamline interactions between end-users (clients), technicians, internal teams, and AI agents. It serves as a central, dynamic hub for communication and workflow automation within the CommandIT ecosystem.
Core Vision & Goals:
- Provide efficient channels for support requests and communication.
- Enable contextual collaboration linked directly to Tickets, Devices, and Organizations.
- Leverage AI Agents for automated triage, task execution, workflow progression, and technician assistance (CoPilot).
- Offer clear visibility into technician presence and availability.
- Support standard live chat queuing and routing for human agents.
- Ensure accountability through logging and transcript association.
- Integrate seamlessly with time tracking for accurate billing and effort analysis.
- Align with platform goals: zero noise (actionable interactions), automation, accountability, AI augmentation, and technician simplicity (presenting AI-prepared info).
Primary Access Methods:
- Technicians/Internal Users: Primarily via the CommandIT Agent; secondarily via the CommandIT Web Application.
- End-Users/Clients: Primarily via the CommandIT Agent (if deployed); secondarily via the Client Portal.
2. Core Concepts & Underlying Schema
The chat system's functionality is built upon a robust schema:
- ChatChannels: Conversation container, stores context (related_ticket_id, related_device_id), type, status, AI summary.
- ChannelParticipants: Links Users (human/AI) to ChatChannels, tracks join time, last_read_message_id.
- ChatMessages: Stores individual messages, sender, timestamp, content type, attachment links, edit/delete status. Includes 'SystemEvent' type.
- Users: Represents participants (is_ai flag). Stores presence/activity state (UserSessions, last_system_activity_timestamp, current_status_enum), push tokens, links to Contacts.
- Contacts: Stores client details, notification preferences (allow_email/sms_notifications), sms_consent_given.
- Attachments: Central repository for file metadata.
- TicketUpdates: Stores saved chat transcripts and AI-generated notes.
- TicketUpdateAttachments (M2M): Links chat Attachments to transcript TicketUpdates.
- AiTools: Defines functions callable by AI agents (interfacing with backend APIs).
- AiAgentConfigs/SpAiAgentOverrides: Define AI agent behavior.
- Automations/Scripts: Reusable workflows/scripts callable by AI via AiTools.
- UserSessions: Logs historical login/logout events and per-session activity.
- PendingChatRequests: Holds incoming client chats waiting for human agent assignment.
- Teams/UserTeamAssignments: Defines groups for routing human chat requests.
- Notifications/SentNotifications/NotificationTemplates: Framework for asynchronous user alerts.
- Roles/RolePermissions: Defines permissions (including chat.monitor).
- TimeEntries: Stores time logs. Includes related_chat_channel_id to link time directly to chat activity.
- Supporting Data: AI and Application Logic access related data (Tickets, Devices, Documents, Quotes, etc.) as needed.
3. User Roles & Access Interfaces
- Client/End-User: Via Agent or Portal widget. Initiates/responds. Permissions via Portal Roles.
- Technician/Internal User: Via Agent or Web App. Handles queues, collaborates, uses CoPilot, initiates chats. Permissions via internal Roles.
- AI Agent: Backend participant (Users.is_ai=true). Executes tasks via AiTools/APIs.
- Manager: Via Agent or Web App. Tech capabilities + monitoring based on Roles/Permissions.
4. Presence & Activity Indicators (Technician View)
Technician availability is visualized to aid dispatch and collaboration:
- Green (Active): Agent checking in + Active session + Recent system interaction. Likely responsive.
- Amber (Idle): Agent checking in + Active session + No recent system activity (idle threshold exceeded). May be present but inactive; response might be delayed.
- Red (Agent Offline): Agent check-in timestamp (Devices.last_agent_checkin) is stale. Device likely off/asleep; user unreachable via agent.
- Grey (Agent Unknown): No primary work device linked OR agent has never checked in. Cannot determine status.
- (Real-time updates depend on application's WebSocket layer).
5. Starting a Chat
- Client Initiating: Via Agent/Portal. Routes to AI Triage or Human Queue (PendingChatRequests targeting a Team). Context passed.
- Technician Initiating: DM User, DM Contact (may trigger Email/SMS invite workflow if recipient offline/no user), Contextual Ticket/Device Chat.
- System/AI Initiating: Automated workflows create channels, add participants, send initial messages.
6. Live Chat Workflow (Human Focus & AI Handoff)
- Queuing/Routing: PendingChatRequests target Teams. Dispatchers/Agents see queue based on team membership. Availability checked (UserSessions, current_status_enum). Assignment via broadcast or round-robin. Client waits.
- Acceptance: Agent accepts -> PendingChatRequests updated -> ChatChannel created -> Participants added -> Automatic Time Tracking Starts (See Section 6.1).
- During the Chat: Standard messaging, file sharing, @mentions (triggering Notifications), read receipts. UI supports toggling between multiple concurrent chats.
- Agent Actions: Invite others, leave, transfer between Teams. System messages log events.
- Manager Monitoring/Snooping: Requires chat.monitor permission. Application logic allows viewing live ChatMessages without appearing in ChannelParticipants. Monitors are invisible and cannot interact. To participate, they must explicitly "Join Chat".
- Ending the Chat: Mark ChatChannel inactive. Automatic Time Tracking Stops. Optional trigger to save transcript.
6.1 Automatic Time Tracking Integration
To ensure technician effort spent in chat is captured accurately:
- Timer Start: Application logic automatically starts a timer and creates a TimeEntries record when a technician becomes actively engaged:
- Accepts a chat from PendingChatRequests.
- Joins or is added to a ChatChannel.
- Brings a specific chat UI element into focus (requires front-end tracking).
- TimeEntries Creation:
- user_id = Tech's ID.
- start_time_utc = Current time.
- end_time_utc = NULL (timer running).
- related_chat_channel_id = The active channel_id.
- ticket_id = Populated immediately if ChatChannels.related_ticket_id exists, otherwise NULL.
- work_type_id = Set to a configured default (e.g., "Chat Support").
- is_billable = Set based on WorkType default / Agreement rules.
- Timer Stop/Pause: Application logic automatically stops the current running timer (sets end_time_utc, calculates duration_seconds) when:
- The tech switches focus away from the current chat window/tab.
- The tech becomes idle (based on Users.last_system_activity_timestamp exceeding threshold).
- The chat channel is closed/ended.
- The tech's session ends (logout/timeout - update UserSessions). (Note: This may result in multiple time entries per extended chat conversation).
- Deferred Ticket Linking: If a Ticket is created or linked to the ChatChannel after time tracking has begun, application logic finds previous TimeEntries for that related_chat_channel_id where ticket_id is NULL and updates them with the correct ticket_id.
7. AI-Augmented Chat & Workflows (Expanded)
- AI-Led Ticket Triage: AI Agent performs analysis, enrichment (setting agreement, linking related items/CIs, finding duplicates via AiTools), applies TicketTemplates, generates TicketTasks, suggests plans, sets classifications. If clarification is needed, it initiates/uses the chat channel to interact with the requester. Handoff to human Team if unable to proceed.
- AI Working Ticket Tasks: Executes Automations via AiTools/AgentCommandQueue, updates status/user via chat, handles approvals.
- CoPilot Assistance (for Humans in Chat): Techs use commands (e.g., /summarize, /search kb, /draft reply, /generate script, /request time off) -> AI uses context + AiTools -> Responds within chat or performs backend actions.
- AI Actions on Other Entities: AI parses chat intent -> Uses AiTools -> Updates Quotes, Approvals, creates Documents, etc.
8. Transcript & Attachment Handling
- Application generates transcript from ChatMessages.
- Transcript saved as TicketUpdates (usually internal).
- Attachments from chat linked to the transcript TicketUpdates via TicketUpdateAttachments.
9. Notifications (User Experience)
- Offline: Application triggers Push/Email/SMS via Notifications/SentNotifications based on presence (UserSessions), preferences (Contacts), and consent.
- Device-Side Alerts (Agent/Web UI): Configurable audio alerts (ICQ option!), visual badges/highlights/toasts for new queue items (PendingChatRequests), messages, and @mentions.
10. UI Persistence
- Chat interface designed in the front-end to remain accessible during navigation within primary user interfaces (Agent, Web App, Portal).