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

# Build a HIPAA-postured patient engagement program

> A program-level walkthrough for clinic chains: compose appointment reminders, two-way confirm and reschedule, and no-show win-back under the HIPAA posture your organization chooses.

# Build a HIPAA-postured patient engagement program

You run digital engagement for a clinic chain. Your patients expect the same reminder and rescheduling experience retail brands ship, but the data behind it is PHI, and the posture decision is yours. This guide composes the pieces Devotel Orbit ships for that program — appointment reminders, two-way confirm and reschedule, no-show win-back, recording consent, and audit evidence — into one reference, in the order you should build them.

Each part has its own deep guide. This page is the program-level order of work; if you only need the reminder mechanics, start with [Appointment reminders end to end](https://docs.orbit.devotel.io/guides/appointment-reminders-workflow.md).

> [!WARNING]
>
> This guide describes Devotel Orbit platform controls. It is **not legal
> advice.** The determination that PHI is in scope, the posture that
> applies, and the controls your regulator expects belong to your
> counsel and your compliance officer. Every control below is
> tenant-owned: you choose the posture, you operate the gates, and you
> own the retention decision.

## 1. Choose the posture first

The posture is a tenant-owned decision. Orbit provides the controls and the ledger; the legal determination that PHI is in scope is yours. Make four decisions before you build anything:

| Decision | What it controls | Where you set it |
| - | - | - |
| **BAA execution** | Whether PHI-adjacent audiences can launch at all. Until your Business Associate Agreement is executed and in term, the campaign launch precheck refuses designated audiences with `HIPAA_BAA_REQUIRED`. | [BAA flow](https://docs.orbit.devotel.io/compliance/baa.md), [HIPAA onboarding](https://docs.orbit.devotel.io/guides/hipaa-onboarding.md) |
| **At-rest encryption posture** | PHI at rest is encrypted with Google-managed AES-256. Review the current posture and its stated limits in the control reference. If your posture requires customer-managed keys, raise it with Devotel while scoping the BAA; do not assume a key-management toggle exists. | [HIPAA compliance controls](https://docs.orbit.devotel.io/compliance/hipaa.md) |
| **Archival and retention** | How long message logs, consent records, and audit rows are kept, and how they leave the platform for your evidence file. Retention is your decision. | [Audit log export](https://docs.orbit.devotel.io/guides/audit-log-export.md), [Compliance evidence binder](https://docs.orbit.devotel.io/compliance/evidence-binder.md) |
| **AI turn audit opt-in** | Whether AI agent turns in patient conversations are logged verbatim for periodic evidence export. You opt in, you opt out, and you own the retention decision. | [AI Turn Audit](https://docs.orbit.devotel.io/compliance/ai-turn-audit.md) |

Run the [HIPAA first-enablement runbook](https://docs.orbit.devotel.io/guides/hipaa-first-enablement.md) to bring the workspace to the posture you chose, then keep this page open as the build order.

## 2. Build a PHI-aware audience

Define the patient contact schema narrowly. Create custom fields for what the program actually uses — `first_name`, `phone`, `whatsapp`, `preferred_channel`, and an appointment or location key — and validate them in the [field schema explorer](https://docs.orbit.devotel.io/guides/audience-fields-schema-explorer.md). Derive computed traits from engagement events (`reminder_sent`, `confirmed`, `no_show`, `rebooked`), not from clinical data. Behavioral traits are not PHI; clinical values are.

What must **not** live in marketing attributes:

* Diagnosis codes, treatment plans, medication details, or lab results.
* Visit reasons that reveal a health condition.
* Provider notes or insurance details.

Keep those in your EHR or practice-management system. If a campaign genuinely needs a clinical cohort, the cohort membership is itself PHI: assemble it in your source system, import the audience, and designate it PHI-adjacent in the registry instead of copying clinical values into attributes. Designation follows provenance, and it travels with every campaign that uses the audience — see [Register PHI-adjacent audiences](https://docs.orbit.devotel.io/guides/hipaa-phi-audiences.md).

Designate the patient audience so the BAA gate attaches to it:

```bash theme={null}
PUT /api/v1/compliance/hipaa/phi-audiences
{
  "audience_ids": ["list_patients_reminders", "seg_patients_whatsapp"]
}
```

The write is a full replacement, so read the current registry first and send the complete set back. From this point on, any campaign that selects a designated audience is refused at launch until the BAA is executed and in term — which is exactly the guarantee you asked for when you chose the posture.

## 3. Consent and opt-out wiring for health messaging

Health messaging fails on consent bookkeeping, not on delivery. Wire it before the first reminder:

* **Verify per contact, per channel.** SMS consent does not grant WhatsApp consent. Pull destination verdicts for a sample of your patient list with the [consent inspector](https://docs.orbit.devotel.io/guides/audience-consent-inspector.md) and confirm the channel mix you planned matches the consent you hold.
* **Record the consent evidence.** Keep who consented, when, on which channel, and to which disclosure text. Your counsel defines the disclosure; Orbit records and enforces the verdict.
* **Honor opt-outs globally and immediately.** Keyword handling, propagation to suppressed destinations, and re-opt-in semantics are covered in [SMS opt-out & opt-in rules](https://docs.orbit.devotel.io/guides/opt-out-rules.md). If your counsel separates treatment messaging from marketing messaging, configure the classes accordingly rather than mixing them in one audience.
* **Cap and suppress.** Apply [message suppression](https://docs.orbit.devotel.io/guides/message-suppression.md) so a patient who opted out, rebooked, or was contacted elsewhere is never re-enrolled by a later run.
* **Schedule inside permitted windows.** Set tenant [quiet hours](https://docs.orbit.devotel.io/guides/quiet-hours-configuration.md) for messaging. For voice, the federal calling window is a platform guard: outbound calls outside it are blocked and the guard cannot be disabled, so plan reminder-call schedules inside it.

## 4. The appointment lifecycle flow

Build on [Appointment reminders end to end](https://docs.orbit.devotel.io/guides/appointment-reminders-workflow.md) — it carries the scheduler, the channel fallback, and the delivery verification. This section adds the program shape around it: two-way response handling and the no-show win-back.

```text theme={null}
appointment.scheduled → T-24h reminder (CONFIRM / RESCHEDULE keywords)
                        ├─ CONFIRM    → confirmed event → later reminders end
                        ├─ RESCHEDULE → booking link or agent handoff → later reminders end
                        └─ no reply   → T-2h reminder → attended?
                                                    ├─ yes → end
                                                    └─ no  → wait 24h → win-back
                                                              (max 2 per 30 days)
                                                              └─ rebooked event ends the run
```

**Reminder schedule.** A workable default cadence is T-24h with the two keywords, then a short T-2h reminder for patients who have not confirmed. Every SMS carries your opt-out language. Emit one event per appointment state change (`confirmed`, `no_show`, `rebooked`) from your scheduling system with a stable `appointment_id`, and key every condition on that id so a newer booking can never be cancelled or reminded by an older run.

**Two-way confirm and reschedule.** Map inbound keywords to actions: `CONFIRM` writes the `confirmed` event and ends the remaining reminders; `RESCHEDULE` replies with your booking link, or hands the conversation to an AI agent or the inbox for locations that prefer staffed rescheduling. WhatsApp locations use the equivalent approved template with the same two actions. Keep the keyword set to two words; every extra keyword is a misspelling you will support.

**No-show win-back with caps.** When `no_show` lands, wait a day, then send one win-back message with the rebook link. Two rules keep it defensible:

* Cap it with your tenant frequency caps — for example, two win-back messages per patient per 30 days — and let suppression absorb opt-outs and manual exclusions.
* End the run on `rebooked`, keyed to `appointment_id`, so a patient who rebooked by phone never receives the win-back the next morning.

A fallback channel is still a new send: it must pass the same consent, quiet-hours, and suppression checks as the primary.

## 5. Voice layer

Two controls cover calls in this program:

* **Recording consent.** If reminder callbacks, reschedule calls, or agent calls are recorded, play the consent prompt before recording starts and record the outcome per call. The walkthrough is [Execute the DPA and BAA, then manage per-call recording consent](https://docs.orbit.devotel.io/guides/compliance-dpa-baa-recording-consent.md).
* **Post-call surveys.** One-touch IVR capture after the call closes the loop on access and quality. Survey responses attach to a visit, so treat them with the same retention posture as the rest of the program when you export them. Setup is [Post-call CSAT and NPS surveys](https://docs.orbit.devotel.io/guides/post-call-surveys.md).

Schedule reminder calls inside the federal calling window; the platform blocks outbound voice outside it regardless of tenant settings.

## 6. Evidence for audits

Assemble the evidence on a cadence, not on demand. A weekly export is a workable default for an active healthcare workspace:

* BAA execution state and term.
* `hipaa.phi_audiences.set` audit rows — the sequence of registry writes is your designation history.
* Consent and opt-out changes for the designated audiences.
* Launch precheck refusals and send-gate refusals, with their reasons.
* AI turn audit records, if you opted in for AI-handled patient conversations.

Pull them through the [audit log export](https://docs.orbit.devotel.io/guides/audit-log-export.md), and roll BAA posture plus PHI access logging into a signed download with the [compliance evidence binder](https://docs.orbit.devotel.io/compliance/evidence-binder.md). A refusal row is not a defect by itself: it means either compliance work is pending or a designation and a campaign disagree, and the row tells you which.

## 7. Rollout checklist

The canonical sequence is the [production go-live checklist](https://docs.orbit.devotel.io/guides/go-live-checklist.md); this is the healthcare annotation of it:

| Go-live area | Healthcare addition |
| - | - |
| Sandbox sign-off | Run the reminder, keyword, and win-back paths against sandbox numbers, including the no-reply and reschedule branches. |
| Number and sender readiness | Senders registered for the message classes your counsel approved; WhatsApp templates approved for the reminder and win-back content. |
| Webhooks | Appointment state events signed, idempotent, and deduplicated on `appointment_id`. |
| Sending guardrails | Quiet hours set, frequency caps set for win-back, suppression lists loaded. |
| Security posture | Registry and BAA writes limited to `owner`/`admin`; designation kept with the compliance officer. |
| Compliance readiness | BAA executed and in term, patient audiences designated, recording consent enabled on recorded call paths. |
| Ops | Evidence export scheduled weekly; refusal rows reviewed as an incident queue. |

## Troubleshooting

| Symptom | Check |
| - | - |
| Launch refused with `HIPAA_BAA_REQUIRED` | Read `details.reason`: `not_signed`, `pending`, or `expired` each has a different de-block path. Resolve the BAA, or lift a designation that was made in error — never to route around the gate. |
| A confirmed patient still gets the T-2h reminder | Confirm the `confirmed` event carries the same `appointment_id` as the scheduled event, and that the reminder condition exits on it. |
| A rebooked patient receives the win-back | Check the `rebooked` event keying and the win-back condition; a contact-level check matches the wrong appointment. |
| A reschedule keyword goes unanswered | Verify the inbound keyword range is bound to the reminder sender and that the reply path (link, agent, or inbox) is configured for that channel. |
| Survey digits never arrive | Check the IVR capture settings and the terminal call state in the [post-call surveys](https://docs.orbit.devotel.io/guides/post-call-surveys.md) troubleshooting table. |

## See also

* [HIPAA onboarding: from BAA to audit-ready](https://docs.orbit.devotel.io/guides/hipaa-onboarding.md)
* [Register PHI-adjacent audiences](https://docs.orbit.devotel.io/guides/hipaa-phi-audiences.md)
* [Appointment reminders end to end](https://docs.orbit.devotel.io/guides/appointment-reminders-workflow.md)
* [Consent inspector](https://docs.orbit.devotel.io/guides/audience-consent-inspector.md)
* [Execute the DPA and BAA, then manage per-call recording consent](https://docs.orbit.devotel.io/guides/compliance-dpa-baa-recording-consent.md)
* [Production go-live checklist](https://docs.orbit.devotel.io/guides/go-live-checklist.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.