chat-widget

What it does

Enables a real-time support chat system with a user-facing floating widget and an admin dashboard. The skill outlines data models for chats and messages, REST endpoints for users and admins, WebSocket channels for live updates, a frontend widget and admin UI, email notification scheduling, and TypeScript typings for client-side data structures.

How it works

• Data models: two tables are defined, support_chats and support_messages. SupportChat has associations to User and multiple SupportMessages; SupportMessage belongs_to SupportChat and has a sender_type enum (user/admin). Key fields include last_message_at, admin_viewed_at, archived_at on chats, and content, read_at, created_at on messages. Methods include touch_last_message, unread_for_admin?, archive!, unarchive!, archived? on the Chat model, and after_create actions on the Message model: update chat timestamp, auto-unarchive on user messages if archived, broadcast to chat channel, notify admins on user messages, and schedule email notification on admin messages.
• API Endpoints: User-facing GET /support_chat to get or create a chat and fetch messages, and PATCH /support_chat/mark_read to mark admin messages as read. Admin-facing GET /admin/chats for listing chats, GET /admin/chats/:id for details, POST /admin/chats/:id/archive to archive, and POST /admin/chats/:id/unarchive to restore. Controller logic for user show and admin index illustrates how chats and messages are serialized and filtered.
• WebSocket Channels: ChatChannel for per-chat real-time messages, with authorization allowing either the owning user or admins, handling send_message to create messages. AdminNotificationChannel broadcasts to admins on new user messages. Message broadcasting sends to the specific chat channel and to a global admin notification channel; admins get scheduled email notifications via a delayed job when a user message is sent.
• Frontend - User Widget: A floating ChatWidget with a ChatButton, ChatPanel, and MessageList. Use a useSupportChat hook managing chat state, a WebSocket consumer, and a ChannelSubscription. Behavior includes deduplication of incoming messages, a read-marking action on panel open, auto-scroll on new messages, a connected indicator, and keyboard controls (Enter to send, Shift+Enter for newline). Message alignment differs by sender, with timestamps displayed.
• Frontend - Admin Dashboard: Pages for chat list and detail with active/archived filtering, unread indicators, and real-time updates using the same WebSocket channel. Admin detail shows grouped messages by date and includes an archive/restore toggle. mark_viewed_by_admin() is described to run when the admin page loads.
• Email Notifications: SupportReplyNotificationJob sends an email to the user when an admin replies and the message remains unread, with a 5-minute delay to avoid spam. The job checks message.read_at and sender_type before sending.
• TypeScript Types: Explicit interfaces for SupportMessage, SupportChat, and Admin/Client views, plus WebSocket message types for chat and admin notifications.

When to use it

Use this skill when you need to provide real-time in-app live chat for customer support, including a user-facing widget and an admin dashboard for staff.

What it can touch

• Frontend: User Widget UI components and state management, including WebSocket subscription to ChatChannel.
• Backend: Models (SupportChat, SupportMessage), REST Controllers for user/admin endpoints, Action Cable channels (ChatChannel, AdminNotificationChannel), and a background job (SupportReplyNotificationJob).
• Email system: SupportReplyNotificationJob to send delayed emails.

Caveats

• Risk is declared as critical.
• Requires proper WebSocket/auth security on channels to ensure users can only access their chats.
• Database indexes recommended (e.g., on support_chats.user_id, last_message_at, archived_at, support_messages.chat_id, (chat_id, created_at)).
• Admin email notifications are delayed by 5 minutes and only sent if the message remains unread at that time.
• Deduplication relies on tracking seen message IDs across broadcasts to avoid duplicates.