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

# SMS Notifications Guide

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

## 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](https://twilio.com) 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

```typescript theme={null}
import { PhoneVerification } from '@/platform/auth/components/PhoneVerification';

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

### SMS Preferences Component

```typescript theme={null}
import { SMSPreferences } from '@/platform/notifications/components/SMSPreferences';

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

### Sending SMS Notifications

```typescript theme={null}
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

### Consent Requirements

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

## Related Documentation

* [Notifications System](./notifications-guide.md)
* [Email Notifications](./email-notifications-guide.md)
* [Phone Verification](./notifications-guide.md#phone-verification)