SMS Notifications Guide

​

Overview

​

Configuration

​

Prerequisites

• RINGCENTRAL_CLIENT_ID secret configured
• RINGCENTRAL_CLIENT_SECRET secret configured
• RINGCENTRAL_JWT_TOKEN secret configured
• SMS-enabled number set per-org (ringcentral_sms_phone_number)
• Verified phone number in user profile

​

SMS Provider

• Two-way SMS support
• Delivery receipts
• Opt-out handling (STOP keyword)

​

Features

​

Phone Verification

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

• Sent - Delivered to RingCentral
• 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

• + prefix
• Country code (1-3 digits)
• Subscriber number (up to 12 digits)

• US: +12025551234
• UK: +442071234567
• AU: +61412345678

​

Validation

• User profile update
• Verification request
• SMS send attempt

​

User Opt-In

​

Consent Requirements

1. User verifies phone number
2. User enables SMS opt-in toggle
3. User selects notification types for SMS

​

Opt-Out Handling

• 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 OS:”
5. Provide Opt-Out: Include “Reply STOP to unsubscribe” occasionally

​

Rate Limits

• Default: 1 message/second per phone number
• Burst: 30 messages/minute
• Daily: Custom limits per account

• 30 SMS/minute per organization
• Queue additional messages automatically

​

Character Limits

​

Single SMS (160 characters)

​

Multiple Segments

• Each segment: 153 characters
• Platform automatically truncates to 160

​

Special Characters

• [ ] { } | \ ^ ~ €

​

Testing

​

Development Testing

1. Create a sandbox app in the RingCentral Developer Console
2. Use allowed phone numbers
3. Messages logged but not delivered to arbitrary numbers
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 RingCentral 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

• Phone number invalid or disconnected
• Carrier blocked message (spam filter)
• Country not supported
• Account balance insufficient

​

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

​

RingCentral Pricing (approximate)

• Included in your RingCentral plan’s SMS allotment; overage billed per plan
• International rates vary by country
• 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 the RingCentral 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

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

​

Related Documentation

• Notifications System
• Email Notifications
• Phone Verification