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

# Telehealth Integration — Integration Documentation

> Status: ✅ Complete Last Updated: 2026-02-22

**Spec:** PM-13\
**Status:** ✅ Complete\
**Last Updated:** 2026-02-22

***

## Overview

PM-13 adds telehealth session lifecycle management linked to PM-03 appointments. Sessions are created via an edge function, modality-driven modifiers integrate with PM-07 charge capture, and POS codes follow AHCCCS/CMS rules.

***

## Tables

| Table                         | Purpose                                                                    |
| ----------------------------- | -------------------------------------------------------------------------- |
| `pm_telehealth_sessions`      | Session records linked to appointments, with status lifecycle and modality |
| `pm_telehealth_configuration` | Per-org platform configuration (Zoom, Doxy.me, stub)                       |

**RLS:** Both tables use `pm_has_org_access()` for SELECT/INSERT/UPDATE, `pf_is_org_admin()` for DELETE. FORCE ROW LEVEL SECURITY enabled. All UPDATE policies include WITH CHECK.

***

## Edge Function

**`telehealth-create-session`**

* Auth: `validateAuth()` + `verifyOrgAccess()` via `pf_user_role_assignments`
* Reads `pm_telehealth_configuration` for platform resolution
* Inserts `pm_telehealth_sessions` with stub session URL (MVP)
* Returns session URL, status, modality, platform

***

## Domain Events

| Event                          | Publisher | Consumers    | Trigger                      |
| ------------------------------ | --------- | ------------ | ---------------------------- |
| `telehealth_session_started`   | PM-13     | FW-16, PF-10 | Session status → `active`    |
| `telehealth_session_completed` | PM-13     | PM-07, FW-16 | Session status → `completed` |

***

## PM-07 Integration (Billing Modifiers)

`modifier-logic.ts` updated with `telehealthModality` on `EncounterContext`:

| Modality        | Modifier | POS (home) | POS (other) |
| --------------- | -------- | ---------- | ----------- |
| `audio_video`   | 95       | 10         | 02          |
| `audio_only`    | FQ       | 10         | 02          |
| `store_forward` | GQ       | 10         | 02          |

Legacy `is_audio_only` boolean fallback preserved for backward compatibility.

***

## Permissions

| Key                                 | Category | Description                       |
| ----------------------------------- | -------- | --------------------------------- |
| `pm.telehealth_sessions.view`       | view     | View telehealth sessions          |
| `pm.telehealth_sessions.create`     | create   | Create telehealth sessions        |
| `pm.telehealth_configuration.admin` | admin    | Manage telehealth platform config |

***

## Module Settings

Added to `pm_module_settings`:

* `telehealth_require_consent_every_encounter` (BOOLEAN, default TRUE)
* `telehealth_recording_retention_days` (INTEGER, default 90)
* `telehealth_default_platform` (TEXT, default 'stub')

***

## Navigation

Telehealth added under `pm-scheduling` group at `/pm/telehealth` with `Video` icon, gated by `pm.telehealth_sessions.view`.

***

## Files

### New

* `supabase/migrations/20260222..._pm_13_telehealth.sql`
* `supabase/functions/telehealth-create-session/index.ts`
* `src/cores/pm/hooks/useTelehealthSessions.ts`
* `src/cores/pm/hooks/useTelehealthConfiguration.ts`
* `src/cores/pm/pages/TelehealthSessionListPage.tsx`
* `src/cores/pm/pages/TelehealthConfigurationPage.tsx`
* `tests/unit/pm/modifier-logic-telehealth.test.ts`
* `tests/rls/pm/pm-telehealth.test.ts`
* `docs/pm/telehealth-user-guide.md`
* `docs/pm/telehealth-admin-guide.md`

### Modified

* `src/cores/pm/utils/modifier-logic.ts` (telehealthModality + helpers)
* `src/platform/permissions/constants.ts` (3 permission keys)
* `src/platform/modules/module-registry/pm-module.ts` (nav item)
* `src/routes/pm.tsx` (route registration)

***

## Future Work

* **PM-15:** Clearinghouse submission of telehealth claims with modifier/POS
* **Video Platform:** Replace stub adapter with Zoom/Doxy.me BAA-compliant integration
* **PM-12:** Patient portal join link for self-service session access
* **CL-16:** FHIR Encounter resource with telehealth extension