TextMagic Integration

Status: Planned
Version: 0.1 (Draft)
Last Updated: 2026-01-06

---

1. Overview

TextMagic is RABS' business SMS platform used by the admin team for direct communication with participants, carers, and external contacts. This integration provides:

1. Full Chat Interface - Send/receive SMS within RABS admin portal
2. Contact Sync - Two-way sync with YP3000 identity system
3. Discovery Source - Feed SMS contacts into YP3000 for identity resolution
4. Group Messaging - Broadcast to YP3000 groups (all staff, all carers, etc.)

---

2. Architecture

Data Flow

TextMagic Cloud
      │
      ├── Webhooks (inbound SMS) ──→ RABS Backend ──→ YP3000 Sighting
      │                                    │
      │                                    └──→ Chat Thread Storage
      │
      └── API (outbound SMS) ←── RABS Backend ←── Admin UI

Integration Points

Component	Purpose
TextMagic API	Send SMS, fetch contacts, manage lists
Webhook Receiver	Receive inbound SMS in real-time
YP3000 Scanner	Discover contacts from message history
Chat UI	Comms panel tab for TextMagic conversations

---

3. Features

3.1 Chat Interface

Similar to Reggie SMS but for admin team usage:

• Thread-based conversations per phone number
• Contact resolution via YP3000 (show name, role, relationships)
• Message history with timestamps
• Delivery status indicators
• Quick reply templates

3.2 Contact Discovery

Every inbound/outbound message creates a YP3000 sighting:

• Phone number normalized to E.164
• If identity exists: increment sighting count, update last_seen
• If new: create purgatory identity for review
• Confidence: 50 (SMS-only source)

3.3 Group Broadcast

Send messages to YP3000-defined groups:

Group	Target
All Staff	primary_role = 'staff'
All Participants	primary_role = 'participant'
All Carers	primary_role = 'carer'
Staff + Carers	Combined filter
Custom	Manual selection from YP3000

Safeguards:

• Preview recipient count before send
• Respect do_not_contact flag
• Opt-out handling via SMS STOP
• Rate limiting for bulk sends

3.4 Two-Way Sync

TextMagic → RABS:

• Contact names synced to YP3000
• List memberships inform relationships
• Message history available in chat UI

RABS → TextMagic:

• YP3000 identity names pushed to TextMagic contacts
• Group definitions synced as TextMagic lists (optional)

---

4. Database Tables

Extend existing comms schema:

-- TextMagic message storage
CREATE TABLE comms.textmagic_messages (
  id UUID PRIMARY KEY,
  textmagic_id TEXT UNIQUE,           -- TextMagic message ID
  thread_id UUID REFERENCES comms.textmagic_threads(id),
  identity_id UUID REFERENCES core_source.yp3000_identities(id),
  direction TEXT NOT NULL,             -- 'inbound' or 'outbound'
  phone_number TEXT NOT NULL,
  message_text TEXT,
  sent_at TIMESTAMPTZ,
  delivered_at TIMESTAMPTZ,
  status TEXT,                         -- 'sent', 'delivered', 'failed'
  metadata JSONB DEFAULT '{}'::JSONB,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Conversation threads
CREATE TABLE comms.textmagic_threads (
  id UUID PRIMARY KEY,
  phone_number TEXT NOT NULL UNIQUE,
  identity_id UUID REFERENCES core_source.yp3000_identities(id),
  last_message_at TIMESTAMPTZ,
  unread_count INTEGER DEFAULT 0,
  is_archived BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

---

5. API Endpoints

GET  /api/v1/comms/textmagic/threads         - List conversation threads
GET  /api/v1/comms/textmagic/threads/:id     - Get thread messages
POST /api/v1/comms/textmagic/send            - Send SMS
POST /api/v1/comms/textmagic/broadcast       - Send to group
POST /api/v1/comms/textmagic/webhook         - Receive inbound (from TextMagic)
POST /api/v1/comms/textmagic/sync            - Sync contacts with YP3000

---

6. Configuration

Environment variables (already configured in backend/.env):

TEXT_MAGIC_API_KEY=***   # Already set

Note: API key is already configured. May need to add webhook secret when implementing inbound webhooks.

---

7. UI Location

Comms Panel → TextMagic Tab

• Thread list (left sidebar)
• Chat view (center)
• Contact details from YP3000 (right panel)

---

8. Implementation Phases

Phase 1: Basic Chat

• Thread list and message display
• Send/receive messages
• Webhook integration for inbound

Phase 2: YP3000 Integration

• Contact resolution in chat UI
• Scanner for contact discovery
• Identity linking for threads

Phase 3: Broadcast

• Group selection UI
• Preview and confirmation
• Batch send with rate limiting
• Delivery tracking

Phase 4: Sync

• Push YP3000 names to TextMagic
• List synchronization