Skip to main content

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.

​
Overview

Encore Health OS supports SMS delivery for critical notifications via Twilio API. SMS is ideal for time-sensitive alerts that require immediate attention.

​
Configuration

​
Prerequisites

  • TWILIO_ACCOUNT_SID secret configured
  • TWILIO_AUTH_TOKEN secret configured
  • TWILIO_PHONE_NUMBER secret configured
  • Verified phone number in user profile

​
SMS Provider

The platform uses Twilio for SMS delivery:
  • Global coverage (190+ countries)
  • Two-way SMS support
  • Delivery receipts
  • Opt-out handling (STOP keyword)

​
Features

​
Phone Verification

Users must verify their phone number before receiving SMS:
  1. Enter phone number (E.164 format)
  2. Receive 6-digit verification code
  3. Enter code to verify
  4. Enable SMS opt-in

​
Message Formatting

  • Maximum 160 characters (single SMS segment)
  • Automatic truncation with ”…” if longer
  • Variable substitution supported
  • Plain text only (no HTML)

​
Delivery Tracking

SMS messages track:
  • Sent - Delivered to Twilio
  • Delivered - Confirmed received by carrier
  • Failed - Delivery error

​
Usage

​
Phone Verification Component

import { PhoneVerification } from '@/platform/auth/components/PhoneVerification';

function ProfilePage() {
  return (
    <div>
      <h2>Phone Settings</h2>
      <PhoneVerification />
    </div>
  );
}

​
SMS Preferences Component

import { SMSPreferences } from '@/platform/notifications/components/SMSPreferences';

function NotificationSettings() {
  return (
    <div>
      <h2>SMS Notifications</h2>
      <SMSPreferences />
    </div>
  );
}

​
Sending SMS Notifications

await supabase.from('pf_notifications').insert({
  user_id: userId,
  organization_id: orgId,
  title: 'Alert',
  body: 'Urgent: Resident fall reported at Site A',
  type: 'critical_alert',
  channel: 'sms',
  priority: 'high',
});

​
Phone Number Format

​
E.164 Format Required

SMS requires phone numbers in E.164 format:
  • + prefix
  • Country code (1-3 digits)
  • Subscriber number (up to 12 digits)
Examples:
  • US: +12025551234
  • UK: +442071234567
  • AU: +61412345678

​
Validation

Phone numbers are validated on:
  • User profile update
  • Verification request
  • SMS send attempt

​
User Opt-In

SMS requires explicit user consent:
  1. User verifies phone number
  2. User enables SMS opt-in toggle
  3. User selects notification types for SMS

​
Opt-Out Handling

Users can opt out by:
  • Replying “STOP” to any SMS
  • Disabling SMS in notification preferences
  • Removing phone number from profile

​
Best Practices

  1. Keep Messages Brief: 160 characters maximum
  2. Use for Critical Alerts Only: Reserve SMS for urgent matters
  3. Respect Time Zones: Avoid sending SMS at night
  4. Include Sender Name: Prefix with “Encore Health OS:”
  5. Provide Opt-Out: Include “Reply STOP to unsubscribe” occasionally

​
Rate Limits

Twilio rate limits:
  • Default: 1 message/second per phone number
  • Burst: 30 messages/minute
  • Daily: Custom limits per account
Platform rate limiting:
  • 30 SMS/minute per organization
  • Queue additional messages automatically

​
Character Limits

​
Single SMS (160 characters)

Plain text only, no special formatting.

​
Multiple Segments

Messages > 160 characters split into multiple SMS:
  • Each segment: 153 characters
  • Platform automatically truncates to 160

​
Special Characters

Some characters count double (GSM-7 encoding):
  • [ ] { } | \ ^ ~ €

​
Testing

​
Development Testing

Use Twilio test credentials:
  1. Create test project in Twilio
  2. Use test phone numbers
  3. Messages logged but not delivered
  4. No charges incurred

​
Production Testing

  1. Verify real phone number
  2. Send test SMS to your phone
  3. Confirm delivery receipt
  4. Test opt-out flow

​
Troubleshooting

​
SMS Not Sending

  1. Check Twilio credentials are configured
  2. Verify edge function deployed
  3. Confirm user has verified phone number
  4. Check user has SMS opt-in enabled
  5. Review edge function logs

​
Invalid Phone Number

  1. Verify E.164 format (starts with +)
  2. Check country code is correct
  3. Remove spaces, dashes, parentheses
  4. Use phone validation tool

​
Delivery Failures

Common reasons:
  • Phone number invalid or disconnected
  • Carrier blocked message (spam filter)
  • Country not supported
  • Account balance insufficient
Check delivery receipts in Twilio dashboard.

​
Verification Code Not Received

  1. Check phone number is correct
  2. Verify SMS carrier supports SMS
  3. Check spam folder (some carriers filter)
  4. Wait 2-3 minutes (carrier delays)
  5. Request new code

​
Cost Considerations

​
Twilio Pricing (approximate)

  • US/Canada: $0.0079 per SMS
  • UK: $0.04 per SMS
  • Australia: $0.07 per SMS
  • India: $0.004 per SMS

​
Cost Optimization

  1. Use SMS sparingly (critical alerts only)
  2. Batch notifications when possible
  3. Offer email alternative
  4. Monitor usage in Twilio dashboard

​
Security

​
PII Handling

  • Phone numbers encrypted at rest
  • Logs redact phone numbers (mask middle digits)
  • Verification codes expire after 10 minutes
  • No PHI in SMS messages

​
Opt-Out Compliance

Platform automatically:
  • Honors STOP keyword replies
  • Updates user preferences
  • Prevents future SMS to opted-out users
  • Logs opt-out timestamp