Notifications

We use Twilio for SMS/voice and SendGrid for email to keep patients, partners, and internal staff informed. Templates live in Supabase, and all sends route through the notifications-dispatcher edge function.

Channel Overview

Channel	Provider	Use Cases
SMS	Twilio Messaging Service	Enrollment outreach, appointment reminders, urgent alerts.
Voice	Twilio Programmable Voice	Escalation calls for crisis alerts or unacknowledged handoffs.
Email	SendGrid	Monthly summaries, billing notifications, onboarding packets.

Template Management

• Templates stored in messaging.templates and versioned with checksum hashes.
• Localization support uses ICU message syntax; the default locale is English (en-US).
• Personalization variables must be sanitized-no raw PHI in SMS. Use aggregated terms (e.g., “your behavioral health team”).

Rate Limits & Throughput

• SMS: 250 messages/minute per long code pool. We stagger outreach to stay within Twilio A2P 10DLC guardrails.
• Email: 10k messages/day default SendGrid cap; marketing campaigns require additional approval.
• Voice: Calls originate from a shared pool and cap at 20 concurrent sessions by default.

Delivery Monitoring

• Delivery receipts feed into /webhooks/notifications and update messaging.delivery_events.
• Failures escalate according to the notification type. Critical alerts requeue with voice as a fallback.
• Analytics dashboards show open/click rates (for email) and response times (for SMS).

Compliance

Consent Tracking

We store patient consent preferences and honor opt-out keywords (STOP, UNSUBSCRIBE). Opted-out patients remain reachable via phone by licensed clinicians only.

• Emails include unsubscribe links; unsubscribes flow into the patient’s communication preferences.
• Voice calls disclose recording status when applicable.

See the Referral Ingestion API for webhook/auth patterns and the Clinic Tablet setup guide for escalation expectations during warm handoffs.