SMS Journey

Internal

This page describes implementation details for the GiveCare development team.

The SMS journey is the complete message flow from an inbound caregiver SMS to Mira's outbound response². Every message traverses the same pipeline, with gates determining which path through the system it takes.

Message flow

flowchart TD
    A["Inbound SMS"] --> B["assessRisk"]
    B --> C{"Crisis gate"}
    C -->|"risk.level = high/critical"| D["Crisis response"]
    C -->|"risk.level = low/medium"| E{"Consent gate"}
    E -->|"No consent"| F["Consent request"]
    E -->|"Consented"| G{"Bootstrap gate"}
    G -->|"Incomplete"| H["Bootstrap flow"]
    G -->|"Complete"| I["Pi orchestrator"]
    I --> J["Objective selection"]
    J --> K["Model turn"]
    K --> L["Outbound SMS"]
    D --> L
    F --> L
    H --> L

Gate 1: assessRisk

Every inbound message is assessed for safety signals before any other processing. The risk assessment runs a classifier that outputs one of four levels:

Level	Action
low	Continue to consent gate
medium	Continue to consent gate with safety context attached
high	Route to crisis response immediately
critical	Route to crisis response immediately + flag for human review

Gate 2: Crisis gate

If risk.level is high or critical, the message bypasses all other gates. The caregiver receives a crisis response regardless of their consent status, bootstrap stage, or loop state. See Crisis Routing for response format and safety tiers.

Legal basis: TCPA emergency exemption (FCC Order DA 20-402). Crisis Text Line (741741) precedent¹.

Gate 3: Consent gate

Checks whether the caregiver has provided explicit opt-in consent for ongoing SMS communication. If no consent exists, the system sends a consent request and halts further processing until consent is received.

Consent is stored per phone number and is revocable at any time via STOP keyword.

Gate 4: Bootstrap gate

Checks whether the caregiver has completed the bootstrap flow — the initial data collection that Mira needs to operate effectively (name, care recipient relationship, basic situation). If bootstrap is incomplete, the message routes to the bootstrap flow, which collects minimum viable context before handing off to the full Pi orchestrator.

Bootstrap is designed to be completable in 3-5 SMS exchanges.

Pi orchestrator

Once a message passes all three gates, it enters the Pi orchestrator — the core decision engine that determines what Mira does next.

Objective selection

The orchestrator selects an objective for the current turn based on:

1. Current loop — what conversational loop is the caregiver in?
2. Caregiver state — what does the system know about their current situation?
3. Inbound content — what did the caregiver just say?
4. Pending actions — are there open action items, follow-ups, or assessments?

Model turn

The selected objective, conversation history, caregiver context, and system instructions are assembled into a prompt and sent to the language model. The model generates Mira's response, which is validated against:

• SMS length constraints (target 1-2 sentences, under 280 characters)
• Voice guide compliance (no anti-patterns, trauma-informed language)
• Safety check (post-generation safety filter)

Loop system

Conversations are organized into loops — named conversational contexts that determine Mira's behavior and objectives:

Loop	Purpose	Entry condition
bootstrap	Collect minimum viable context	New user, first message
onboarding	Introduce Mira, set expectations	Bootstrap complete
assessment	Administer instruments (SDOH-6, EMA-3, CWBS-14, SDOH-30)	Scheduled or triggered
benefits	Guide benefits discovery and application	Zone flagged
safety	Crisis detection and response	Risk gate triggered
proactive	Check-ins, follow-ups, status updates	Scheduler-driven

Loop transitions are managed by the arbiter — a routing layer that decides when to enter, exit, or switch loops based on caregiver state and system events.

Scheduler

The scheduler runs periodic ticks that evaluate which caregivers need proactive outreach:

flowchart LR
    A["Scheduler tick"] --> B["Arbiter routing"]
    B --> C["Eligible users"]
    C --> D["Loop selection"]
    D --> E["Turn execution"]
    E --> F["Outbound SMS"]

Proactive messages include:

• Daily EMA-3 check-ins
• Monthly CWBS-14 assessments
• Follow-ups on pending benefit applications
• Spike detection responses (score changes >= 20 points)
• Post-crisis continuity check-ins

Data flow

All messages, assessments, and state are stored in the Convex backend. The message flow is stateless per request — all state is read from and written to Convex on each turn.

---

1. GiveCare ADR-0001. "Crisis Gate Ordering." 2026-03-14. Source → ↩

2. GiveCare internal. "Backend Specification." Source → ↩