SMS Messaging Integration Contract

​

Overview

​

Integration Patterns

​

Pattern Summary

​

Internal Integrations

​

CE-01: Contacts Integration

-- SMS messages linked to contacts via foreign key
ce_sms_messages.contact_id → ce_contacts.id

-- Consent tracked per contact phone
ce_sms_consent.contact_id → ce_contacts.id

• SMS matched to contact by phone number (E.164 format)
• Contact detail includes SMS conversation tab
• Consent status displayed on contact
• SMS compose from contact detail page

// Phone-to-contact lookup
const contact = await supabase
  .from('ce_contacts')
  .select('id, first_name, last_name, phone, mobile_phone')
  .eq('organization_id', orgId)
  .or(`phone.eq.${normalizedPhone},mobile_phone.eq.${normalizedPhone}`)
  .single();

​

CE-03: Platform Telephony Integration

import { useTelephonyHistory } from '@/platform/telephony';

• Unified communication history (calls + SMS)
• Shared phone number formatting utilities
• RingCentral SMS API (if using RingCentral for telephony)

​

CE-04: Activities Integration

-- Trigger: Auto-create activity when SMS sent/received
CREATE TRIGGER ce_sms_create_activity
  BEFORE INSERT ON ce_sms_messages
  FOR EACH ROW
  EXECUTE FUNCTION ce_create_activity_from_sms();

interface SmsActivity {
  organization_id: string;
  contact_id: string | null;
  partner_id: string | null;
  lead_id: string | null;
  activity_type: 'sms';
  subject: string; // "SMS to [contact]" or "SMS from [contact]"
  description: string; // Message preview (first 100 chars)
  status: 'completed';
  activity_date: string; // ISO timestamp
  created_by: string | null;
}

​

PF-10: Notifications Integration

import { sendNotification } from '@/platform/notifications';

interface SmsNotification {
  type: 'sms_received' | 'sms_failed' | 'sms_opted_out';
  recipient_user_id: string;
  data: {
    sms_message_id: string;
    contact_name: string;
    phone_number_masked: string; // Last 4 digits only
    preview: string; // First 50 chars
    event_timestamp: string;
    error_code?: string; // For failures
  };
}

​

External Integrations

​

RingCentral SMS API Integration

const RINGCENTRAL_CONFIG = {
  clientId: process.env.RINGCENTRAL_CLIENT_ID,
  clientSecret: process.env.RINGCENTRAL_CLIENT_SECRET,
  jwtToken: process.env.RINGCENTRAL_JWT_TOKEN,
  // Webhooks
  inboundWebhookUrl: '/functions/v1/sms-webhook',
  statusCallbackUrl: '/functions/v1/sms-webhook',
};

• sms-send/index.ts - Send SMS via RingCentral
• sms-webhook/index.ts - Receive inbound SMS and status updates

interface SendSmsRequest {
  organization_id: string;
  to_number: string; // E.164 format
  body: string;
  contact_id?: string;
  template_id?: string;
}

interface SendSmsResponse {
  success: boolean;
  message_id?: string;
  external_message_id?: string; // RingCentral message ID
  segment_count?: number;
  error?: string;
}

// RingCentral delivers a notification envelope whose `body` carries the
// message-store record. sms-webhook parses the JSON body (no form-encoded payload).
interface RingCentralWebhookEnvelope {
  uuid: string;
  event: string; // e.g. /restapi/v1.0/account/~/extension/~/message-store
  subscriptionId: string;
  body: {
    id: number;
    from: { phoneNumber: string }; // E.164
    to: Array<{ phoneNumber: string }>; // E.164
    type: 'SMS' | 'MMS';
    direction: 'Inbound' | 'Outbound';
    messageStatus: 'Queued' | 'Sent' | 'Delivered' | 'DeliveryFailed' | 'SendingFailed';
    subject?: string; // message text
  };
}

​

Event Contracts

​

SMS Sent Event

interface SmsSentEvent {
  event_type: 'ce.sms.sent';
  organization_id: string;
  sms_message_id: string;
  contact_id: string | null;
  to_number_masked: string; // Last 4 digits
  segment_count: number;
  user_id: string; // Sender
  timestamp: string;
}

​

SMS Received Event

interface SmsReceivedEvent {
  event_type: 'ce.sms.received';
  organization_id: string;
  sms_message_id: string;
  contact_id: string | null;
  from_number_masked: string; // Last 4 digits
  preview: string; // First 50 chars
  timestamp: string;
}

​

Consent Changed Event

interface ConsentChangedEvent {
  event_type: 'ce.sms.consent_changed';
  organization_id: string;
  consent_id: string;
  contact_id: string | null;
  phone_number_masked: string; // Last 4 digits
  old_status: string;
  new_status: string;
  method: string; // How consent was changed
  timestamp: string;
}

​

TCPA Compliance Contract

​

Consent Requirements

• Required before sending marketing messages
• Must capture: timestamp, method, source
• Must be stored in ce_sms_consent table

• Required for informational messages
• Can be implied from business relationship
• Document consent source

​

Opt-Out Contract

• STOP, UNSUBSCRIBE, CANCEL, END, QUIT (case-insensitive)

1. Detect keyword in inbound message
2. Update ce_sms_consent.consent_status to opted_out
3. Record opted_out_at timestamp and opted_out_keyword
4. Send confirmation: “You have been unsubscribed. Reply START to resubscribe.”
5. Log activity for compliance audit
6. Notify assigned users

• Hard block on sending to opted-out numbers
• Check performed in sms-send Edge Function before API call
• RLS does NOT prevent viewing opted-out contacts (for compliance review)

​

Security Considerations

​

Phone Number Privacy

• Phone numbers stored in E.164 format
• Display masked in UI (show last 4 digits only)
• No phone numbers in application logs
• Encrypted in transit (TLS 1.2+)

​

RingCentral Credential Security

• Credentials stored in Supabase Secrets
• Never exposed in client-side code
• Webhook signature validation required

​

PHI Detection

• Message content scanned for PHI patterns
• Warning shown to user before send (not hard block)
• Patterns: SSN, DOB formats, medical terms
• Configurable via sms_phi_detection_mode setting

​

Module Settings

​

Implementation Status

​

Security & Compliance Controls

​

PHI Detection

• PHI detection runs before message send (when phiDetectionEnabled is true in provider config)
• Detected PHI patterns are logged to ce_sms_messages.phi_detected and phi_detection_result fields
• Detection uses pattern matching from _shared/phi-detection.ts utility
• PHI detection results are included in audit logs for compliance review

​

TCPA Opt-Out Handling

• Opt-out keywords detected: STOP, UNSUBSCRIBE, CANCEL, END, QUIT, STOPALL, UNSUBSCRIBEALL
• Automatic consent revocation when opt-out keywords are received
• Confirmation message sent: “You have been unsubscribed and will no longer receive SMS messages from us.”
• Consent status updated in ce_sms_consent table with consent_status = 'revoked' and revoked_at timestamp
• Future sends blocked via checkSmsConsent() validation in sms-send function

​

Webhook Signature Validation

• RingCentral webhooks validated via the Validation-Token header during subscription validation
• Inbound/status notifications are parsed from the RingCentral JSON envelope
• Signature/token validation ensures webhook authenticity and prevents spoofing
• Invalid signatures result in 403 Forbidden responses

​

Provider Abstraction & Configuration

• Provider abstraction routes all SMS through RingCentral
• Provider configuration loaded from ce_module_settings with fallback to environment variables
• Business hours enforcement via isWithinBusinessHours() utility
• Phone number normalization to E.164 format via normalizeToE164()
• Segment calculation for multi-part messages via calculateSmsSegments()

​

Consent Verification

• checkSmsConsent() validates consent status before sending
• Consent checked per contact phone number in ce_sms_consent table
• Required consent status: 'granted' with valid granted_at timestamp
• Revoked consent blocks all future sends until new consent is granted

​

References

• Spec: specs/ce/specs/CE-08-sms-messaging-integration.md
• Plan: specs/ce/plans/CE-08-sms-messaging-PLAN.md
• Tasks: specs/ce/tasks/CE-08-sms-messaging-TASKS.md
• RingCentral SMS API: https://developers.ringcentral.com/api-reference/SMS
• TCPA Guidelines: https://www.fcc.gov/consumers/guides/stop-unwanted-robocalls-and-texts
• Integration Patterns: docs/architecture/integrations/index.md