Guide · CompanionGuard · Published 14 November 2026 · Reviewed 14 November 2026 · By the Ingenious AI team
Integrating the Crisis Evidence Runtime: Start, Message, End — and What to Do with Each Answer
The short answer
Runtime integration is three calls wrapped around your chat path: POST a session start (with minor-session context and caps), call the message endpoint per message event and honour the returned action — allow, show_crisis_resources, disclosure_required, enforce_break or notify_parent — then close with session end. Config, status and export endpoints complete the surface. Design rule: when the runtime is unreachable, your bot must fail safe — disclosure and referral behaviour must never depend on a network call succeeding.
What is the runtime integration contract?
The integration contract is the sequence of authenticated calls a bot's backend makes to the Crisis Evidence Runtime across a conversation's life — start, message (repeatedly), end — plus the operator's obligations for each possible response: show disclosure when told, present resources verbatim when told, pause minor sessions when told, and log flags for the human process. The runtime decides; the bot's code honours.
Create the free safety kit Next guide All guides
CompanionGuard is built by Ingenious AI. A compliance toolkit — not legal advice and not a clinical service. If you are in crisis right now: US — call or text 988; UK & Ireland — Samaritans 116 123.
Session start: context is the contract's first clause
The start call opens the session and carries the context every later decision depends on: the bot's identity (via your API key), your session identifier (stored only as a one-way hash), whether this is a minor session, and the operator-configured caps that apply. Everything the runtime later 'knows' — disclosure owed, caps ticking, parent flags applicable — is a consequence of what start asserted. Garbage context is therefore the integration's cardinal sin: a minor session started without its flag gets no caps and no flags, silently.
Assert context from your own authoritative session data at start time, not from per-message guesses. If your platform learns mid-session that a user is a minor, your integration should treat that as a context change to handle explicitly (a fresh, correctly-flagged session is cleaner than a silent mutation) — and the evidence chain will show the before and after honestly, which is what you want it to show.
Message calls: five answers, five obligations
Each message call returns exactly one action, and each is an obligation with a correct implementation. allow: proceed normally. disclosure_required: show the AI disclosure now, confirm it, and do not continue ordinary conversation until it is shown — this is a blocking state, not a suggestion to append a footer. show_crisis_resources: present the locale resource block verbatim — numbers from the pack, not model prose — in this reply. enforce_break: pause the minor session with your break experience; the cap has been reached and the decision is already sealed. notify_parent: a flag for your safeguarding pipeline — ensure your systems record it somewhere a human process consumes, since the runtime's part is recording, not routing.
Idempotency and ordering matter: message calls should be sequential per session (the chain is an ordered record), and a retried call should not double-seal a decision — design your client with the same care you would give a payment integration, because the evidentiary value of the chain depends on its fidelity to what actually happened. The runtime guide covers the decision model behind the answers.
End, status, config and export: the supporting calls
Session end closes the record cleanly — sessions that never end leave the daily-cap accounting and your own analytics guessing, so call it on timeout and abandonment paths too, not only on polite logouts. The config surface carries your operator configuration (caps and related settings) — treat changes to it as policy changes: deliberate, dated, and noted in your ops log, because the evidence chain will faithfully show behaviour changing at that moment. Status is your health probe: wire it into the same monitoring that watches your own backend. Export is the retrieval path for the sealed record — schedule it (monthly verification, quarterly reporting rehearsals) rather than discovering it during an audit.
Authentication throughout is your API key from the backend — see the API keys guide for issuance, hash-only storage and rotation.
Fail-safe design: when the runtime cannot answer
Networks fail, deploys happen, and a safety layer that fails open must fail toward safety. The design principles: disclosure should be shown by your own client logic at session start regardless (the runtime tracks and evidences it; your UI should not need permission to disclose). Crisis replies should be safe by construction in your prompt layer too — the harness-tested behaviour is your fallback when the live classifier is unreachable, so a message during an outage still meets a bot whose replies refer properly. Minor caps should degrade to your client-side session limits if you have them. And every outage window should be visible in your monitoring as a gap the evidence chain will honestly show.
What fail-safe must never mean: silently skipping. If message calls fail, log the failure in your own systems with timestamps, alert on sustained failure like any production dependency, and treat the window's sessions as unevidenced — because they are. The chain's honesty about gaps is a feature; your job is to keep gaps rare, short and known.
Five actions for a correct integration
- Assert session context at start from authoritative data — the minor flag and caps especially — never from per-message inference.
- Implement all five actions as obligations, with disclosure_required blocking and show_crisis_resources rendering the pack verbatim.
- Call session end on every exit path, including timeouts and abandonment, so cap accounting and records close cleanly.
- Put config changes under change control (dated, noted) and status under monitoring, like any production dependency.
- Design the outage posture in advance: client-side disclosure always, harness-tested reply behaviour as fallback, failures logged and alerted — never silently skipped.
Worked example: an integration reviewed in staging
A fictional team integrates the runtime for their companion over two days. Day one's staging review catches three contract misses: their client treats disclosure_required as a footer suggestion (fixed to a blocking modal with confirmation), their retry logic can double-submit a message call after a timeout (fixed with per-session sequencing and duplicate guarding), and session end is only called on explicit logout (fixed with an idle-timeout closer).
Day two's rehearsal runs the full script — a minor session hitting its cap, a crisis phrase drawing show_crisis_resources with the verbatim pack, a parent flag landing in the safeguarding queue, and a five-minute simulated runtime outage during which the bot still discloses (client-side) and its prompt-layer replies still refer (harness-tested). The exported staging chain verifies clean. The story is invented; the calls, actions and obligations are the product's own contract.
Frequently asked questions
What calls does the runtime integration require?
Per session: start (with context and caps), a message call per message event, and end — authenticated with your API key from your backend. Config, status and export endpoints complete the surface.
What are the five actions a message call can return?
allow, show_crisis_resources, disclosure_required, enforce_break and notify_parent — each an obligation: proceed, present the locale resources verbatim, show disclosure as a blocking state, pause the minor session at its cap, or record the flag for your safeguarding pipeline.
What is stored about my sessions?
Decisions sealed in a hash chain: event kinds, signal classes, actions, timestamps, a one-way hash of each message and a session reference that is a one-way hash of your session ID. Raw text, IPs, user agents and user IDs are never stored.
What happens if the runtime is unreachable?
Your design must fail safe: disclose from your own client logic, rely on harness-tested reply behaviour for referral, apply any client-side limits you have, and log/alert the gap. Sessions in the window are unevidenced — keep windows rare, short and known.
How do caps and minor context enter the integration?
At session start: the minor-session flag and the operator-configured session/daily caps are part of the session's context, and the runtime enforces them for flagged sessions, returning enforce_break at the cap.
Keep going
Related guides: Crisis Evidence Runtime: Live Guardrail Decisions, Sealed as Evidence · API Keys in CompanionGuard: Owner Keys, Bot-Owner Keys and the Usage Endpoint · Session and Daily Caps: How the Runtime Enforces Breaks for Minors
Put it to work: Create the free kit · Eval harness · Scenario tests · Crisis runtime · Disclosure packs · Pricing · All CompanionGuard guides