Integration cookbook

Five common integration shapes. Pick whichever matches how your product talks to users.

1. Real-time inline gating

You have a chat bot. Before sending the bot's reply, you call Viora to check the user's last turn. If R-level >= R1-high, you swap in safety copy.

user turn → POST /v1/sessions/{id}/messages → check r_level → either bot reply or safety overlay

Latency is the constraint here: target < 500ms p95. Viora aims for sub-second; if you see p99 > 1.5s in production, tell us.

2. Post-hoc analytics

You log conversations to your own store. Once a day (or in real time but asynchronously) you replay them through Viora to populate signals.

conversation finished → POST sessions + messages in batch → R-levels stored alongside transcript

Latency-insensitive. Cheapest mode.

3. Triage queue

You operate human moderators. Viora surfaces escalations to a queue.

real-time append → if r_level >= R1-high, surface in moderator queue → moderator reviews + acknowledges

We have a built-in queue at /admin/queue. If you want to mirror that to your own ops platform, poll GET /admin/queue?acknowledged=false (admin auth) or wire up webhooks (planned).

4. Long-term user monitoring

For long-running consumer relationships, the per-end-user LBRS matters more than any single session.

end of session → GET /v1/end-users/{external_id} → check lbrs_r_level + consecutive_r1_plus_sessions → escalate patterns

A user with LBRS R1-high or consecutive_r1_plus_sessions >= 4 is showing a sustained pattern, not a bad day.

5. A/B testing your safety policy

Viora's R-levels are stable across calls (same convo → same scores), so you can run live A/Bs of safety copy variants against the same risk surface.

each session: random arm A vs B → different copy at each R-level → compare retention, escalation, downstream outcomes

We can pull per-arm rollups for you if your external_ids encode the arm.

Idempotency + retries

Sessions: safe to retry (idempotent on (client, external_id)). Messages: not idempotent. If you retry, you may double-write a turn. Track your own request IDs if it matters.