SMS Messaging Integration Contract

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

​

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

​

Twilio SMS API Integration

const TWILIO_CONFIG = {
  accountSid: process.env.TWILIO_ACCOUNT_SID,
  authToken: process.env.TWILIO_AUTH_TOKEN,
  // Webhooks
  inboundWebhookUrl: '/functions/v1/sms-webhook',
  statusCallbackUrl: '/functions/v1/sms-webhook/status',
};

• sms-send/index.ts - Send SMS via Twilio
• 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; // Twilio SID
  segment_count?: number;
  error?: string;
}

interface TwilioInboundWebhook {
  MessageSid: string;
  From: string; // E.164
  To: string; // E.164
  Body: string;
  NumSegments: string;
  AccountSid: string;
}

interface TwilioStatusWebhook {
  MessageSid: string;
  MessageStatus: 'queued' | 'sent' | 'delivered' | 'failed' | 'undelivered';
  ErrorCode?: string;
  ErrorMessage?: string;
}

​

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+)

​

Twilio 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

• Twilio webhooks validated using X-Twilio-Signature header and HMAC-SHA1 signature verification
• Signature validation ensures webhook authenticity and prevents spoofing
• RingCentral webhooks validated via Validation-Token header for subscription validation
• Invalid signatures result in 403 Forbidden responses

​

Provider Abstraction & Configuration

• Unified provider abstraction supports Twilio and 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
• Twilio SMS API: https://www.twilio.com/docs/sms
• TCPA Guidelines: https://www.fcc.gov/consumers/guides/stop-unwanted-robocalls-and-texts
• Integration Patterns: docs/architecture/integrations/index.md