Using the Messaging Inbox

Summary

The Messages page is the central inbox for all customer conversations. It uses a split-panel layout with a conversation list on the left and the active thread on the right. Staff can filter, search, reply, assign conversations, link work orders, and manage multi-channel messaging from one screen.

The inbox updates in real time. New customer messages across SMS, WhatsApp, and the portal appear in the conversation list and the active thread without needing to refresh. Status pills (Sent / Delivered / Read) update live as confirmations arrive. If the real-time connection drops for an extended period, an amber banner reads “Real-time updates paused — refresh the page to reload the latest conversations”.

The same thread view is rendered inside the Messages tab on the work-order detail page, so a staff member working a job sees the full cross-channel conversation with that customer (WhatsApp + SMS + portal interleaved), and replies default to whichever channel the customer last used. The two surfaces are now backed by the same conversation; replying from one updates the other immediately.

Prerequisites

• You must have the messages.view capability assigned to your role.
• To reply directly, you need the messages.send capability. Users with messages.send_gated can compose replies that go to the Approval Queue first.
• To access the Approval Queue tab, you need the messages.approve capability.

Steps

Navigating to the inbox

1. Select Messages from the main navigation. The page opens at /messages.
2. The page header reads “Messages” with the subtitle “Customer conversations”.
3. Below the header, a sub-nav bar shows available tabs. You always see Inbox. If you have approval permissions, you also see Approval Queue. If AI is enabled for your organisation, you also see AI Analytics.

Filtering conversations

1. The conversation list panel sits on the left (360px wide on desktop, full width on mobile).
2. At the top of the list panel is a search box. Type a customer name, phone number, or keyword to search across conversations.
3. Below the search box are two rows of filter buttons:
   • A date range row with six options: All time, Today, This week, This month, Last 30 days, Custom….
   • A read filter row with four buttons: All, Unread, Unassigned, and Mine. Each shows a count badge.
4. Below the rows, a microcopy line reads Showing: [preset label] so you can see at a glance which date scope is active.
5. The inbox defaults to Last 30 days so the list and the count badges only reflect recent activity - the All count means “47 conversations in the last 30 days”, not 47 across all time. The first time you visit the inbox after this default landed, a one-time banner explains the change. Dismiss it once you have read it; it does not return.
6. Pick Custom… to open an inline date range picker. Choose start and end dates - the inbox refetches as soon as both are set. The most recent custom range is remembered if you toggle away and back.
7. Select a filter to narrow the list. The URL updates with the range and filter parameters so you can bookmark or share filtered views. The preset you pick is remembered in your browser, so returning to the inbox lands on the same scope.
8. If no conversations match the date range, the empty state shows a one-tap All time link to broaden the scope.
9. The date range applies to “any activity” - a conversation appears in This week if any message, status change, or note on it falls inside the range, not just the start of the thread.
10. Search bypasses the date range deliberately - type a query and the inbox searches across everything, regardless of the active preset, so you can always find an old thread.

Reading the conversation list

1. Each conversation row displays the customer name, a message preview, a timestamp, and an unread badge if applicable.
2. A channel indicator icon appears next to each conversation showing how the customer last communicated:
   • Portal - speech bubble icon (grey)
   • WhatsApp - WhatsApp icon (green)
   • SMS - phone icon (blue)
   • Voice - phone-call icon (purple)
3. The list loads 50 conversations at a time. If more exist, a Load more button appears at the bottom.
4. New messages arrive in real time. Conversations with new activity bubble to the top of the list and briefly highlight.

Opening a conversation thread

1. Select a conversation from the list. The thread view opens in the right panel.
2. On mobile, the thread replaces the list. A Back to conversations button (left chevron) in the header returns you to the list.
3. The thread header shows the customer name and a channel badge. For WhatsApp conversations, a window status indicator shows whether the 24-hour session is active or expired.
4. The URL updates to include ?conversation={id} so you can link directly to a thread.

Reading messages

1. Messages appear in chronological order. Inbound messages align left, outbound messages align right.
2. Each message shows the sender name, timestamp, channel, and delivery status (pending, delivered, read, or failed).
3. Voice calls appear inline as a call card showing duration, outcome (answered / missed / voicemail), and a link to the call’s transcript and recording. Tap the card to open the full call detail page.
4. To load older messages, select Load earlier messages at the top of the thread.
5. Opening a thread automatically marks all unread messages in that conversation as read.

Voice calls in the inbox

Inbound and outbound voice calls now appear in the unified inbox alongside SMS, WhatsApp, and portal messages. The behaviour:

• A call from a known customer joins their existing conversation thread - so a call about a booked MOT shows up next to the SMS and WhatsApp exchange about the same booking.
• A call from an anonymous number that does not match any customer creates its own conversation thread keyed on the caller’s phone number, so repeat calls from the same unknown caller stay together.
• Withheld-number calls each get their own thread because there is no identifier to roll them up.
• The conversation row preview shows the latest voice activity, e.g. “Voice call - 41s - ended” or “Voicemail - 0:38”.
• The composer at the bottom of a voice-only thread offers Reply by SMS rather than a free-form composer, since the customer cannot reply on the voice channel.

Reassigning a misattributed call

If a call landed in the wrong customer’s thread - a spouse calling from the primary’s phone, or an anonymous caller you can now identify - you can reassign it.

1. Open the call card in the thread.
2. Click the Reassign action.
3. Choose Move to a different customer (search and select the right customer) or Detach to anonymous.
4. Optionally enter a reason for the audit log.
5. Click Confirm. The call moves to the chosen thread immediately and the conversation list updates.

Marking a voice call resolved

When the system cannot auto-resolve a call (a missed call, a voicemail, an escalation, or an errored call), the call stays in the Unread filter until you mark it resolved.

1. Open the call card.
2. Click Mark resolved.
3. The call’s row leaves the Unread filter; the Unread badge count decrements.

Routing for inbound messages without a customer match

When a message arrives from a phone number that does not match any customer, or from a customer with no active work order, the conversation lands in the inbox as an Unassigned row with a context badge: General, Booking, or Unknown. Unassigned filter counts make it easy to spot these. If the customer has exactly one active work order, the system auto-links the conversation to it. If they have several, the conversation surfaces with a “Pick a work order to link” prompt for staff to disambiguate.

Replying to a conversation

1. The reply composer sits at the bottom of the thread panel.
2. If the WhatsApp 24-hour session window is open, type a free-form message and press Send.
3. If the session window has expired, only template messages are available. Use the template picker to select a pre-configured notification type.
4. If you have gated permissions, your reply goes to the Approval Queue with a status of “pending_approval” instead of sending immediately.
5. If a message fails to send, it shows a failed status. Select the retry option to re-queue the message.
6. You can select which channel to send through if the conversation has multiple available channels.

Using the conversation sidebar

1. On screens 1280px and wider, a details sidebar appears automatically on the right.
2. On screens 1024-1279px, toggle the sidebar with the panel icon in the thread header.
3. On mobile, tap the info icon (circle-i) to open the sidebar as a slide-out sheet.
4. The sidebar shows customer details, linked work order information, and assignment controls.

Linking a work order

1. In the sidebar, select the option to link a work order. A search dialog opens where you can find and select the work order.
2. Once linked, a system message appears in the thread confirming the link.
3. To unlink, select the unlink option in the sidebar. A confirmation dialog asks you to confirm with an Unlink button.

Assigning a conversation

1. In the sidebar, use the assignment dropdown to assign the conversation to a staff member or remove the current assignment.
2. Assignment changes are reflected immediately in the sidebar and affect the Mine and Unassigned filter counts.

Using quick messages

1. The reply composer supports quick messages - pre-saved text snippets configured in Settings. These appear as selectable options when composing a reply.

Expected Outcome

• You can view all customer conversations in one place, filtered by status.
• You can read and reply to messages across WhatsApp, SMS, portal, and voice channels.
• Conversations update in real time without needing to refresh.
• Work orders are linked to conversations for full context.
• Filter counts update automatically as messages are read or assigned.

Troubleshooting

Problem	Cause	Fix
Messages page redirects to the dashboard	Your role does not have the messages.view capability	Ask an admin to update your role permissions in Settings
Approval Queue tab is not visible	Your role does not have the messages.approve capability	This is expected if you are not an approver. Ask an admin if you need access
AI Analytics tab is not visible	Communication AI is not enabled for your organisation	An admin must enable AI in communication settings
Cannot type a free-form reply	The WhatsApp 24-hour session window has expired	Use a template message instead, or wait for the customer to message again
Reply shows as “pending_approval”	Your account has gated messaging permissions	An approver must review and approve your message from the Approval Queue
Message shows “failed” status	The message could not be delivered via the channel provider	Select the retry option on the failed message. If it fails again, check the customer’s contact details
Conversation list shows “No conversations”	No conversations match the active filter	Switch to the All filter or clear the search box
Thread does not load	Network error or the conversation was deleted	Check your internet connection and refresh the page

Permissions

Capability	What it controls
messages.view	Access to the Messages page
messages.send	Send replies directly
messages.send_gated	Compose replies that require approval
messages.approve	View and action the Approval Queue tab