Messaging & Notifications

Who this is for: support staff, care-team staff, PMs, new hires.

The idea: one event, many channels

The platform has a central internal “event” system: whenever something meaningful happens to a case (created, paid, appointment booked, documents ready, appointment reminder due, etc.), that single event can fan out to several communication channels at once — email, text message, in-app messaging, automated phone outreach, and a marketing/CRM sync — depending on how that event type is configured.

Channels

Email — templated emails (confirmations, reminders, document-ready notices, etc.), styled per brand.
Text messages (SMS) — sent through one of two supported text-messaging providers depending on the brand’s configuration; also used for outbound fax where a state process requires it.
In-app messaging — a threaded conversation tied to either a specific case or a patient overall. Patients, admins, and doctors can all post into a thread. Some messages are staff-only or admin-only notes and are never shown to the patient; only messages marked visible to everyone reach the patient’s message inbox.
Automated phone outreach — an AI-driven calling system used for certain outreach scenarios (for example, following up after a missed voicemail). Calls can also be routed through more than one telephony provider depending on brand and scenario.
Marketing/CRM sync — patient and marketing-tag data can be synced to an external CRM system for the sales/marketing team’s own outreach and campaigns, separate from the operational messaging above.
Secondary notification system — a second notification layer keeps certain patient events in sync with an outside notification platform, primarily for workflow-triggered marketing-style messages.

Appointment reminders

For any case with a booked appointment, the system automatically schedules four reminders — 48 hours, 24 hours, 2 hours, and 15 minutes before the appointment — each sent by both email and text message. See Scheduling & appointments.

In-app messaging details

Each case (or, for freeform conversations not tied to one case, each patient) has its own message thread.
Messages can be marked visible to everyone, staff-only, or admin-only — patients only ever see the “everyone” tier.
When staff send a patient-visible message, the patient is notified (for example by email) that a new message is waiting.
Every new thread message is also mirrored out to an internal support/helpdesk system in real time, so support tooling outside the care portal stays in sync.
Some automated system flows can post a message into a patient’s thread on the patient’s own behalf — for example, automatically notifying the patient (via a system-style message) when they’ve successfully uploaded documents.

Duplicate automated-phone-outreach routes

The automated phone outreach system’s API routes currently exist in two identical copies in the codebase, with the care portal automatically forwarding requests from one path to the other. Both copies are live and would need updating together if the logic changes — a cleanup opportunity, not something that affects how the feature behaves for staff or patients today.

Open question: template permissions

Every message-template management screen in the admin area restricts creating/editing templates to the highest admin permission level, except one (visit-note templates), which currently has no such restriction. This looks like an oversight rather than an intentional difference and is worth a permissions review.

Where this comes from

parkingmd-care-portal/docs/care-portal-kt-guide.md (Communications section)
parkingmd-care-portal/docs/retell-system.md
parkingmd-care-portal/src/lib/events/ (the central event dispatcher)
parkingmd-care-portal/src/lib/email/, src/lib/sms/, src/lib/telnyx/
parkingmd-care-portal/src/lib/threads/
parkingmd-care-portal/src/lib/novu/, src/lib/ghl-service/
parkingmd-care-portal/src/lib/retell/
parkingmd-care-portal/src/lib/appointment-reminders/
parkingmd-care-portal/src/lib/webhooks/ (support-system mirroring)
parkingmd-patient-portal/src/models/messages.ts, src/trpc/routers/messages.ts
parkingmd-care-portal/src/app/api/retell/ vs. src/app/api/integrations/retell/ (identical route copies), next.config.js (rewrite rule forwarding one to the other)
parkingmd-care-portal/src/app/api/templates/visit-notes/route.ts (missing the superAdmin check present in provider-completion/, provider-declined/, provider-patient-followup/, quick-templates/)