Messaging

MealStack includes a full-featured messaging system that lets practitioners and clients communicate directly inside the platform — no more switching to WhatsApp or losing conversation history.

Overview

The messaging system has two sides:

Messages are stored permanently as part of the client record. Unlike WhatsApp, you never lose context — the full conversation is always accessible from the dashboard.

Practitioner experience

Messages inbox

The Messages page (/dashboard/messages) shows all client conversations in a split-panel layout:

• Left panel — Conversation list with client avatars, last message preview, timestamps, and unread badges
• Right panel — Selected conversation with full message thread and reply composer

Filtering conversations

Use the filter chips at the top of the conversation list:

The unread count badge shows how many clients are waiting for a reply.

Searching messages

The search bar supports two modes:

1. Conversation search (2+ characters) — Filters the conversation list by client name
2. Full-text message search (3+ characters) — Searches across all message content with highlighted matches, timestamp, and client attribution

Full-text search results show:

• Client name and avatar
• Message snippet with the matching term highlighted
• Timestamp (relative: "2h ago", "Yesterday", "Mon", or date)
• Sender indicator ("You:" prefix for practitioner messages)

Click any search result to jump directly to that client's conversation.

Sending messages

From the conversation panel, practitioners can send:

Messages are delivered in real-time. The client receives a push notification (if enabled) and the message appears instantly in their portal chat.

Canned responses (quick replies)

Save frequently-used messages as canned responses for one-tap sending. Perfect for check-ins, motivational messages, and standard replies.

System defaults

MealStack provides built-in canned responses covering common scenarios:

• Motivation — "Great job! Keep up the amazing work 💪", "Proud of you", "Keep going"
• Reminders — "Don't forget to log your meals today", "Water reminder"
• Check-ins — "How are you feeling today?", "Any challenges this week?"

Creating custom responses

1. Open the Messages inbox
2. Click the Quick Replies button (top-right of conversation list)
3. Click Add New and fill in:
   • Shortcut — A keyword for slash-command matching (e.g., water, great, checkin)
   • Title — Display name shown in the picker
   • Content — The full message text (supports emoji)
   • Category — Group responses by type (motivation, reminder, check-in, custom)

Using canned responses

In the message composer, type / to open the slash-command picker. As you type after the slash, responses are filtered by shortcut and title. Click any response to insert it, then send.

Alternatively, click the Quick Replies icon next to the composer to browse all responses in a categorized list.

Reactions

Hover over any message to reveal the reaction picker — 6 preset emojis (❤️ 👍 😂 😮 😢 🙏) plus a reply button.

• Click an emoji to add your reaction
• Click the same emoji again to remove it
• Reactions appear as small pills below the message bubble
• Both practitioner and client reactions are visible to each other

The reaction style is single-reaction per user per emoji (iMessage-style) — you can react with multiple different emojis, but only one of each type.

Reply-to (quoted replies)

Click the reply button (↩) on any message to quote it in your next message. The quoted preview appears above the composer showing:

• Who sent the original message
• First 80 characters of the content

The recipient sees the quoted block inside your message bubble with a left border accent, making threaded context clear even in long conversations.

Edit and delete messages

Editing

Practitioners can edit their own messages within 15 minutes of sending. After editing:

• The message content updates in-place
• An "edited" label appears next to the timestamp
• The original content is not preserved for the client

Deleting

Practitioners can delete their own messages within 15 minutes of sending. After deletion:

• The message bubble is replaced with "This message was deleted" in italic
• The message is soft-deleted (preserved in the database for audit purposes)
• Reactions and replies referencing the deleted message remain but show the placeholder

Rate limiting

To prevent abuse, messaging is rate-limited:

Rate limit errors show a brief toast notification. The limit resets after 60 seconds.

Client experience

Opening the chat

Clients access messaging from:

• The Messages tab in the portal bottom navigation
• The unread messages banner on the portal home screen
• Push notification taps (deep-links to the chat)

Chat interface

The portal chat uses a premium WhatsApp/Telegram-style design:

• Header — Practitioner name, avatar, and real-time availability status (derived from business hours + timezone)
• Messages area — Grouped bubbles with date separators, food-themed background pattern
• Input bar — Emoji button, GIF button, auto-expanding text area, circular send button

Availability status

The header shows the practitioner's current availability based on configured business hours:

Suggested chips

When the chat is empty (first conversation), clients see tappable quick-start suggestions:

• 👋 Say hello — Auto-fills "Hi! 👋"
• 🔄 Request a change — Auto-fills "I'd like to request a change to my meal plan."
• ❓ Ask a question — Focuses the input (empty)

GIF picker

Tap the GIF button to open an inline picker (Instagram-style, slides up from bottom):

1. Trending GIFs load automatically
2. Quick search chips — pre-set categories (Agree, Applause, Dance, Good job, High five, Thumbs up, etc.)
3. Search — Type to find specific GIFs with debounced search
4. Tap to send — Selecting a GIF sends it immediately as a full-width bubble

GIFs are served through a server-side GIPHY proxy (/api/giphy) to keep the API key secure. Attribution ("Powered by GIPHY") is shown per GIPHY ToS.

Emoji reactions

Clients can react to any message:

• Desktop — Hover over a message to reveal the reaction picker
• Mobile — Long-press (500ms) a message to show the picker
• Quick react — Double-tap any message to instantly react with ❤️

The picker shows 6 emojis: ❤️ 👍 😂 😮 😢 🙏

Active reactions (ones the client has already used) are highlighted with a ring. Tapping an active reaction removes it.

Reply-to

From the reaction picker, tap the reply button (↩) to quote a message. A preview bar appears above the input showing:

• Left accent bar in primary color
• "Replying to [name]" label
• Truncated content preview
• X button to cancel

The reply appears in the sent bubble as a quoted block at the top.

Edit and delete (client side)

Clients can edit or delete their own messages within 5 minutes of sending (shorter window than practitioners to prevent abuse).

• Edited messages show an "edited" label
• Deleted messages show "This message was deleted" placeholder

Read receipts

Client messages show delivery status:

Push notifications

When the practitioner sends a message, the client receives:

• Push notification (if portal is installed as PWA and notifications enabled)
• In-app sound + haptic feedback (if the portal is open but on a different page)
• Toast notification (if the portal is open)

Notifications are visibility-aware — they don't fire when the client is already viewing the messages page.

Optimistic sending

Messages appear instantly in the chat (optimistic UI) before server confirmation:

• Sending state shows a spinner and slightly reduced opacity
• On success, the optimistic message is replaced by the server-confirmed version
• On failure, the message turns red with "Failed · Tap to retry" — tapping re-sends

Rich message types

Swap requests

When a client requests a food swap through the portal's meal plan view, a structured message is auto-sent:

🔄 Swap request: I'd like to replace "Apple Cinnamon Oatmeal" in my breakfast. Reason: Not available locally

This renders as a rich card in the chat with:

• Swap icon + "SWAP REQUEST" header
• Food name highlighted
• Meal type context
• Optional reason in italics

System messages

Automated system messages appear centered with muted styling:

• "Portal access enabled"
• "New meal plan shared"
• "Goal completed 🎉"

How-to guides

How to set up canned responses

How to search message history

How to configure message notifications (practitioner)

Message notification preferences are managed per-practice in Settings → Client Portal → Push Notification Preferences. Ensure "Message notifications" is toggled on.

How to configure message notifications (client)

Clients manage their notification preferences from the portal user menu → Notification Settings. They can toggle message alerts on/off and set quiet hours.

How to use GIFs (portal)

How to react to a message

Security & privacy

• All messages are encrypted in transit (TLS)
• GIF searches are proxied through the server — client devices never contact GIPHY directly
• Rate limiting prevents spam and abuse
• Message data is scoped to the organization — no cross-org access
• Soft-deleted messages are retained for audit but hidden from the UI
• HIPAA-friendly: data stays on the platform, not on third-party messaging services

Feature toggle

Messaging can be enabled or disabled per-client from the client's Portal tab → Feature Toggles → Messaging. When disabled, the client sees a locked screen prompting them to contact their dietitian.

The messaging feature toggle is on by default for new clients when portal access is enabled.