Direct Messages App Overview
Send 1:1 and small-group direct messages (Pings) to anyone in your organization, right from the unified Inbox—with real-time delivery, mentions, attachments, and full admin control.
What is the Direct Messages App?
Direct Messages is the platform-wide private messaging layer of MangoApps Workforce. Conversations live inside the unified Inbox alongside notifications and broadcasts, so users have a single place for everything that needs their attention. Threads are tenant-isolated, real-time, and can be turned on or off organization-wide by administrators.
Core Value Proposition:
- 💬 One Surface — Direct messages live inside the same Inbox as notifications, broadcasts, and action requests
- ⚡ Real-Time — ActionCable delivery pushes new, edited, and deleted messages to every participant instantly
- 👥 1:1 or Small Group — Pairwise threads or group threads up to 10 participants
- 🛡️ Admin Controlled — A single toggle enables or disables Direct Messages org-wide
How It Works
Conversation Flow
┌────────────────────────────────────────────────────────────────────────────┐
│ DIRECT MESSAGE FLOW │
├────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ PICK 1+ │──▶ │ THREAD │──▶ │ MESSAGES │ │
│ │ RECIPIENTS │ │ CREATED │ │ POSTED │ │
│ │ (typeahead) │ │ (1:1 idemp. │ │ (body + │ │
│ │ │ │ or group) │ │ attachments)│ │
│ └──────────────┘ └──────────────┘ └──────┬───────┘ │
│ │ │
│ ┌───────────────────────┼─────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌─────────┐│
│ │ ACTIONCABLE │ │ MENTION │ │ INBOX ││
│ │ BROADCAST │ │ NOTIFICATION│ │ UNREAD ││
│ │ (every part. │ │ (platform_ │ │ BADGES ││
│ │ user stream)│ │ dm_mention) │ │ ││
│ └──────────────┘ └──────────────┘ └─────────┘│
│ │
└───────────────────────────────────────────────────────────────────────────┘
Where Conversations Live
┌─────────────────────┐
│ UNIFIED INBOX │
│ /inbox │
└──────────┬──────────┘
│
┌────────────────────────┼────────────────────────┐
▼ ▼ ▼
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ Notifications │ │ MESSAGES │ │ Broadcasts │
│ & Actions │ │ (Pings) │ │ & Digests │
└────────────────┘ └───────┬────────┘ └────────────────┘
│
▼
┌────────────────────────┐
│ Side Panel (offcanvas)│
│ • Thread header │
│ • Scrollable messages │
│ • Compose at bottom │
└────────────────────────┘
Key Features
💬 1:1 and Group Threads
| Feature | Description |
|---|---|
| One-on-one threads | find_or_create_one_on_one is idempotent — opening a DM with the same person reuses the existing thread |
| Group threads | Start a group with 2+ recipients; capped at 10 participants per thread |
| Multi-recipient picker | Typeahead search of users in the current business; pick one for 1:1, two or more for a group |
| Thread context | Threads can be tagged with origin (e.g. workspace_id) via the context JSONB field |
| Thread title | Group threads can carry an optional title; otherwise display name is derived from participants |
Use Case: From a workspace member popover, click “Send a Ping.” A drawer opens with the recipient pre-filled. Send the message — the existing 1:1 thread is reused if you already have one with that person.
⚡ Real-Time Delivery
| Capability | Description |
|---|---|
| ActionCable channel | Platform::DirectMessageChannel streams to user_#{id} for every participant |
| Live message events | message_created, message_updated, message_deleted events broadcast to all participants |
| No refresh needed | New messages appear in open threads without reloading the page |
📎 Rich Messaging
| Feature | Description |
|---|---|
| Attachments | Active Storage has_many_attached :attachments on every message |
| Mentions | @email@domain.com mentions parsed from body and tracked in mentioned_user_ids |
| Mention notifications | Mentioned users receive a platform_dm_mention notification with a 160-char preview |
| Edit your own | Authors can edit their own messages; edited_at timestamp records the change |
| Soft delete | Authors can delete their own messages; tombstone preserved for audit |
Use Case: Drop a screenshot into a Ping with @manager@acme.com, post it, and your manager gets a notification in their Inbox plus a real-time push to any open thread view.
📥 Unified Inbox Integration
Direct Messages render inside the unified Inbox — there is no separate “messages” page anymore.
| Behavior | Description |
|---|---|
| Messages folder | /inbox?folder=messages lists all your DM threads, sorted by last activity |
| Side panel chat | Clicking a thread row opens a sticky-bottom chat layout in an offcanvas side panel |
| Auto-open | Linking to /inbox?folder=messages&thread=:id opens that thread directly |
| Unread pills | Per-thread unread counts and a global unread badge |
| Read receipts | Opening a thread calls mark_thread_read, updating last_read_at for the participant |
| Date dividers | “Today” / “Yesterday” / formatted date markers between message groups |
| Search | Inbox search matches DM threads by participant name/email or message body |
🎯 Multiple Entry Points
Direct Messages can be started from anywhere in the product:
- New Message button — top of the Inbox messages folder
- Drawer flow —
/messaging/newopens a Turbo offcanvas drawer with the recipient typeahead - Workspace context — pass
context_workspace_idto tag a thread with its origin workspace - Single-recipient links — legacy
user_idparam supported for “Send a Ping” buttons on profile / mention popovers
🛡️ Admin Controls
| Setting | Description |
|---|---|
| Org-wide toggle | direct_messages_enabled boolean on the businesses table — defaults to enabled |
| Read-only mode | When disabled, existing thread history stays visible to participants but compose forms are turned off |
| Hard enforcement | MessagingController and InboxController#post_thread_message block new threads and replies when disabled |
| Settings page | /admin/general_settings/direct_messages — single switch with status banner |
Use Case: During a quiet period or compliance review, an admin disables Direct Messages. Users see a lock icon and “Direct Messages are disabled for your organization” instead of the compose box; existing conversations remain viewable.
🔒 Security & Tenancy
| Layer | Enforcement |
|---|---|
| Business scoping | All three models (DirectMessageThread, DirectMessage, DirectMessageParticipant) include BusinessTenantScoped |
| Recipient validation | create filters recipients to current_business.users only — cross-tenant DMs are impossible |
| Participant gate | MessageService#post rejects with “not a participant” if the actor isn’t in the thread |
| Author-only edit/delete | Edit and delete checks return “not your message” for any other user |
| Soft delete + audit | Deleted messages keep deleted_at and deleted_by_id for compliance |
🤖 AI-Ready Storage
Each message stores a content_embedding (vector(1536)) column with an IVFFlat cosine-similarity index, so messages are indexed for future semantic search and AI retrieval features.
User Roles & Permissions
| Role | Capabilities |
|---|---|
| Employee | Start 1:1 or group threads with anyone in the business; post / edit / delete own messages; mark threads read |
| Manager | Same as Employee — DMs are not gated by role |
| HR / Admin | Same as Employee for messaging, plus access to the org-wide enable/disable toggle |
| System Admin | Full configuration via /admin/general_settings/direct_messages |
How We Compare
See how MangoApps Workforce Direct Messages stacks up against standalone messaging tools:
| Feature | MangoApps Workforce | Slack | MS Teams Chat | Workplace Chat |
|---|---|---|---|---|
| 1:1 + small-group threads | ✅ | ✅ | ✅ | ✅ |
| Real-time delivery | ✅ | ✅ | ✅ | ✅ |
| Mentions + notifications | ✅ | ✅ | ✅ | ✅ |
| Attachments | ✅ | ✅ | ✅ | ✅ |
| Unified inbox (DMs + notifications + broadcasts) | ✅ | ❌ | ⚡ | ❌ |
| Org-wide on/off toggle | ✅ | ❌ | ⚡ | ❌ |
| Built-in to HR / Workforce platform | ✅ | ❌ | ❌ | ❌ |
| Per-message vector embeddings | ✅ | ❌ | ❌ | ❌ |
| Legend: ✅ Included | ❌ Not Available | ⚡ Limited / Admin-only |
Why MangoApps Workforce?
- 🔗 One Inbox — DMs sit alongside notifications, broadcasts, and action requests — not in a separate app
- 🛡️ Tenant-Isolated by Design — Recipients are filtered to your business; cross-tenant DMs aren’t possible
- 🎛️ Single Switch Control — One admin toggle turns messaging on or off org-wide
Getting Started
For Employees
- Open Inbox from the rail
- Switch to the Messages folder
- Click + New Message, type a name or email, pick 1+ recipient(s), and send
- Click any thread row to open the chat side panel
For Managers
- Same flow as employees — DMs aren’t role-gated
- Use group threads (2–10 people) for quick team huddles outside a workspace
For Administrators
- Go to Admin → General Settings → Direct Messages
- Toggle Allow Direct Messages on or off
- Confirm the status banner reflects the new state
Best Practices
- ✅ Use DMs for short, person-to-person threads — use Workspaces for longer-running team work
- ✅ Mention people by
@emailso they get an Inbox notification, not just a real-time push - ✅ Keep groups under the 10-participant cap — for larger groups, use a Workspace
- ✅ When linking to a conversation, use
/inbox?folder=messages&thread=:idso the side panel auto-opens - ✅ Admins: leave the toggle on by default unless compliance review or a quiet period requires otherwise
Frequently Asked Questions
Q: How many people can I add to a group message?
A: Up to 10 participants per group thread, including yourself. The cap is enforced by the model and the thread service.
Q: What happens to my existing conversations if an admin disables Direct Messages?
A: Existing thread history stays visible to participants, but the compose form is replaced with a “Direct Messages are disabled for your organization” notice. New threads can’t be started and replies are blocked until it’s turned back on.
Q: Can I message someone in another business?
A: No. The recipient picker is scoped to current_business.users, and the create action filters out any IDs that don’t belong to your business.
Q: Can I edit or delete a message after sending?
A: Yes — but only your own messages. Edits record an edited_at timestamp; deletes are soft (the row is kept with deleted_at / deleted_by_id for audit).
Q: How do I know if I have unread messages?
A: The Inbox shows per-thread unread pills and a global unread badge. Opening a thread automatically marks it read.
Related Resources
- Apps Overview — All apps and extensions in MangoApps Workforce
- Workspace App Overview — For longer-running team conversations
- Ask AI Overview — Conversational AI assistant inside MangoApps Workforce
Direct Messages keep one-to-one and small-group conversations in the same Inbox as everything else that needs your attention — fast, private, and under admin control.