> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Secure Messaging

> PHI-compliant inbox for clinical and administrative conversations with patients and care teams at /pm/messaging.

The Secure Messaging inbox page lists all PHI-compliant conversations for the current organization and is accessible at the route `/pm/messaging`.

## Overview

The Secure Messaging inbox displays conversations from the `pf_conversations` table filtered to rows where `patient_id` is not null or `is_clinical` is true. The list is ordered by `last_message_at` descending and shows conversation name, category badge, PHI indicator, message preview, and last message date. Users can search conversations by name or preview text using a live filter, and filter by category (Clinical, Administrative, Urgent, Routine) using a dropdown.

Clicking a conversation row navigates to `/pm/messaging/:conversationId` (the `MessagingThreadPage`). A **New Message** button is shown to users with the `pm.messages.send` permission. Conversations flagged as `is_clinical` display a PHI badge alongside the category badge.

## Who it's for

Requires permission: `pm.messages.view`

The **New Message** button additionally requires `pm.messages.send`.

## Before you start

* You must hold `pm.messages.view` to access this page.
* Conversations are scoped to the current organization; no cross-tenant data is returned.

## Steps

<Steps>
  <Step title="Navigate to Secure Messaging">
    Go to `/pm/messaging`. The inbox loads all conversations for your organization where a patient is linked or the conversation is marked clinical.
  </Step>

  <Step title="Search conversations">
    Type in the search field to filter by conversation name or last message preview. The filter applies client-side to the loaded results.
  </Step>

  <Step title="Filter by category">
    Use the category dropdown to limit the list to Clinical, Administrative, Urgent, or Routine conversations. Selecting "All Categories" clears the filter.
  </Step>

  <Step title="Open a conversation">
    Click any conversation card to navigate to `/pm/messaging/:conversationId` and view the full thread.
  </Step>

  <Step title="Start a new message">
    Click **New Message** (requires `pm.messages.send`) to navigate to `/pm/messaging/new` and compose a new conversation.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Conversation categories">
    The `category` field on a conversation can be `clinical`, `administrative`, `urgent`, or `routine`. Each maps to a distinct badge style: clinical (default/blue), urgent (destructive/red), administrative (secondary), routine (outline).
  </Accordion>

  <Accordion title="Empty and error states">
    * **Empty inbox:** "No messages yet — Start a new conversation with a patient or care team member."
    * **Load error:** "Failed to load conversations. Please try again." shown in a card.
  </Accordion>
</AccordionGroup>

<Tooltip tip="Protected Health Information — individually identifiable health data covered under HIPAA.">PHI</Tooltip>-flagged conversations are indicated by both the category badge and a secondary PHI shield badge. All messaging data is scoped to the current organization via `organization_id`.

## Related

<Columns cols={2}>
  <Card title="Practice Management" icon="briefcase" href="/pm/overview">
    Overview of the Practice Management core.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/pm.tsx
  * src/cores/pm/pages/MessagingInboxPage.tsx
  * src/cores/pm/hooks/messaging/usePmConversations.ts
  * src/platform/permissions/constants.ts
</Accordion>