> ## 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.

# Multi-Party Encounters

> List and filter multi-party encounters; view encounter metadata, participant roster, and manage recording consent.

This screen lists all multi-party encounters for the organization and is accessible at `/cl/multi-party-encounters`.

## Overview

The Multi-Party Encounters page displays a filterable table of encounters that involve more than one participant, including family therapy, mobile crisis, interpreter-assisted, and care team encounters. The list is fetched via `useMultiPartyEncountersList` and supports filtering by `status` using a dropdown. Columns show the encounter start datetime, type (resolved to a human-readable label via `MULTI_PARTY_ENCOUNTER_TYPE_OPTIONS`), modality (outline badge), and status (color-coded badge). Each row is keyboard-accessible and navigates to the encounter detail at `/cl/multi-party-encounters/:encounterId`. Users with `cl.multi_party.host` permission see a "New Encounter" button.

## Who it's for

Requires the `cl.multi_party.view` permission. Creating encounters additionally requires `cl.multi_party.host`.

## Before you start

* You must hold `cl.multi_party.view` to access this page.
* To schedule a new encounter you must hold `cl.multi_party.host`.

## Steps

<Steps>
  <Step title="Navigate to Multi-Party Encounters">
    Open the Clinical core and go to `/cl/multi-party-encounters`. The page loads all encounters for your organization, sorted by start time (most recent first).
  </Step>

  <Step title="Filter by status (optional)">
    Use the Status dropdown to filter encounters to a specific status. Select "All Statuses" to clear the filter.
  </Step>

  <Step title="Open an encounter">
    Click any row (or press Enter/Space) to navigate to the encounter detail page at `/cl/multi-party-encounters/:encounterId`.
  </Step>

  <Step title="Create a new encounter (if authorized)">
    If you hold `cl.multi_party.host`, click "New Encounter" to open the encounter form dialog. After submission, you are automatically navigated to the new encounter's detail page.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Status values">
    The `status` column uses badge variants: `completed` (default), `in_progress` (secondary), `cancelled` (destructive), all other values (outline). Clinical meaning of transitions between statuses is not determinable from code — SME confirmation required.
  </Accordion>

  <Accordion title="Empty and error states">
    When no encounters match (or exist), an empty state with a users icon and "No Multi-Party Encounters" message is shown, describing the supported encounter types. If the data fetch fails, a card with "Unable to load multi-party encounters. Please try again." is displayed.
  </Accordion>
</AccordionGroup>

## Viewing an encounter

The Encounter Detail screen shows a single multi-party encounter record with its participant list at `/cl/multi-party-encounters/:encounterId` (permission: `cl.multi_party.view`). Users with `cl.multi_party.host` additionally see the **Add** participant button and per-row remove controls.

The page loads a single multi-party encounter via `useMultiPartyEncounterDetail` and its participants via `useMultiPartyParticipants`, both scoped to `encounterId`. The Encounter Details card shows encounter type (human-readable label from `MULTI_PARTY_ENCOUNTER_TYPE_OPTIONS`), modality (`in_person`, `virtual`, `hybrid`), status, and optional encounter notes. The Participants card shows each participant's role (from `PARTICIPANT_ROLE_OPTIONS`), name (`external_participant_name` or a fallback of "Staff Member"/"Patient" based on `staff_user_id`), join time, and recording consent status. Users with `cl.multi_party.host` can add participants via `AddParticipantDialog` and remove participants whose consent has not yet been captured.

Note: the `cl_multi_party_encounters` database migration must be applied; until then, the page shows an error state.

<Steps>
  <Step title="Open the encounter">
    Navigate to `/cl/multi-party-encounters`, then click an encounter row. The detail page loads encounter metadata and the participant table.
  </Step>

  <Step title="Review encounter details">
    The Encounter Details card shows type, modality, status, and any freetext `encounter_notes`.
  </Step>

  <Step title="Add a participant (host only)">
    Click **Add** in the Participants card header (requires `cl.multi_party.host`) to open `AddParticipantDialog`. Assign a role from `PARTICIPANT_ROLE_OPTIONS`.
  </Step>

  <Step title="Review participant consent status">
    Each participant row shows a **Captured** or **Pending** badge for recording consent based on `recording_consent_captured_at`.
  </Step>

  <Step title="Remove a participant (host only)">
    For participants who have not yet had recording consent captured, a remove button is available for users with `cl.multi_party.host`. Clicking it calls `removeParticipant` scoped to the participant `id` and `encounter_id`.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Encounter types">
    Multi-party encounters are typed as `family_therapy`, `mobile_crisis_virtual`, `interpreter_assisted`, `care_team_meeting`, or `other`. The display label is resolved from `MULTI_PARTY_ENCOUNTER_TYPE_OPTIONS`.
  </Accordion>

  <Accordion title="Participant roles">
    Participants are assigned roles from `PARTICIPANT_ROLE_OPTIONS`: `primary_clinician`, `co_facilitator`, `peer_specialist`, `interpreter`, `patient`, `family_member`, `guardian`, or `other`.
  </Accordion>

  <Accordion title="Empty and error states">
    * Migration pending / load error: `EmptyState` with title "Error Loading Encounter" and message "The feature may not be available yet (migration pending)."
    * Participants error: separate `EmptyState` for participant load failure.
    * Encounter not found: `EmptyState` with title "Encounter Not Found".
    * No participants: "No participants recorded."
    * Loading: skeleton placeholders for both cards.
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Clinical" icon="stethoscope" href="/cl/overview">
    Overview of the Clinical 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/cl.tsx
  * src/cores/cl/pages/MultiPartyEncounterListPage.tsx
  * src/cores/cl/hooks/useMultiPartyEncounters.ts
  * src/cores/cl/pages/MultiPartyEncounterDetailPage.tsx
  * src/cores/cl/types/multi-party-encounter.ts
</Accordion>