Documentation

Demo backend → STS integration

How the demo FastAPI (demo-app/backend-fastapi) calls your STS API. Reuse the same JSON bodies and POST /STS/interactiveAgent contract from your own services.

API

Replace YOUR_STS_HOST with your deployed STS base URL (no trailing slash). The demo backend URL below comes from your Next env: https://sts-api.dev.aldea.ai.

Web session (browser voice, no phone)

Endpoint: POST /api/aldea/sts — creates a web session; website_url is crawled and merged into instructions like the interactive flow.

curl — web session

curl -sS -X POST "https://YOUR_STS_HOST/api/aldea/sts" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "instructions": "You are a helpful customer service agent.",
  "greeting": "Hello! Welcome to support. How can I help you today?",
  "website_url": "https://www.zappix.com",
  "documents": [
    { "title": "FAQ", "type": "text", "content": "Short answers to common questions (demo)." },
    { "title": "Public docs", "type": "url", "content": "https://www.zappix.com" }
  ]
}
JSON

Interactive agent via demo proxy

Endpoint: POST /api/interactive-agent on the demo backend (requires X-API-Key). Forwards unchanged to POST /STS/interactiveAgent.

curl — status (example)

curl -sS -X POST "https://sts-api.dev.aldea.ai/api/interactive-agent" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: demo-local-key" \
  -d @- <<'JSON'
{
  "action": "status",
  "session_id": "sess_your12hexchars"
}
JSON

Direct STS (no demo backend)

Call STS from your server the same way the demo does internally.

curl — interactive start (minimal)

curl -sS -X POST "https://YOUR_STS_HOST/STS/interactiveAgent" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "action": "start",
  "channel": "web",
  "instructions": "You are a helpful agent.",
  "website_url": "https://www.zappix.com",
  "sms_enabled": true,
  "caller_number": "+15551234567"
}
JSON

Call for the voice demo

Set NEXT_PUBLIC_DEMO_VOICE_NUMBER in .env.local (E.164). In Twilio, set that number's Voice webhook to POST https://sts-api.dev.aldea.ai/webhooks/twilio/incoming-call.

Architecture

Where traffic enters
Entry	Flow
Browser / mobile app	Your client calls the demo backend with `X-API-Key`. Demo backend uses `httpx.post(STS_API_BASE_URL + "/STS/interactiveAgent", json=payload)` — no extra wrapping.
Twilio Voice	`POST https://sts-api.dev.aldea.ai/webhooks/twilio/incoming-call` builds a full `action: start` payload (instructions, `link_catalog`, `website_url`, etc.), calls STS, then `bind_caller`, then returns TwiML `Redirect` to `{STS}/api/twilio/incoming-call` with `session_id` and `room_name`.
STS voice verify (optional)	When a secured intent is pending, STS can POST to your `INTERACTIVE_VOICE_VERIFY_HOOK_URL` (this demo exposes `/api/hooks/voice-verify`). Same API key convention as below.

Live URLs on this page use NEXT_PUBLIC_DEMO_BACKEND_URL → https://sts-api.dev.aldea.ai and NEXT_PUBLIC_APP_BASE_URL → https://sts-demo.dev.aldea.ai.

Environment variables (demo backend)

Configure demo-app/backend-fastapi/.env. STS must be reachable from this process (and from Twilio for the redirect URL).

demo-app/backend-fastapi environment
Variable	Default	Purpose
`STS_API_BASE_URL`	`http://localhost:8000`	Base URL of your STS API (no trailing slash). Must be public HTTPS when Twilio follows the redirect.
`DEMO_API_KEY`	`demo-local-key`	Required header `X-API-Key` on all demo routes below. If STS calls your voice-verify hook, set `INTERACTIVE_VOICE_VERIFY_HOOK_API_KEY` on STS to this value (or align both).
`DEMO_FRONTEND_BASE_URL`	`http://localhost:3000`	Used to build `link_catalog` URLs in the Twilio `start` payload (forms, patient pages, privacy, default).
`DEMO_WEBSITE_URL`	`https://www.zappix.com`	Passed as `website_url` on phone `start`. STS normalizes, crawls (Tavily), and injects chunks into instructions — same behavior as web `POST /api/aldea/sts`.
`DEMO_VOICE_VERIFY_ALLOWED_CATEGORIES`	`patient_information`	Comma list or `*` for `/api/hooks/voice-verify`.
`DEMO_VOICE_VERIFY_REQUIRE_PATIENT_ID`	`false`	When `true`, `demo_voice_verify.py` requires patient id + SSN last four for a match (used by the hook).

STS contract: POST /STS/interactiveAgent

Every call is POST {STS_API_BASE_URL}/STS/interactiveAgent with Content-Type: application/json. The body always includes action. The demo backend forwards the same JSON it receives on /api/interactive-agent.

Response highlights for action=start (typical)
Field	Meaning
`session_id`	Interactive session id (format `sess_` + 12 hex). Use on all follow-up actions and query params.
`room_name`	LiveKit room (e.g. `sts-{uuid}`). Twilio bridge uses this with `session_id`.
`websocket_url`	Present for web starts; phone demo flow may omit pre-dispatch details depending on STS config.

Actions (same JSON you send to STS)

STS interactiveAgent actions
action	Required / common fields	Behavior
`start`	Optional: `instructions`, `greeting`, `documents`, `rag_doc_ids`, `rag_max_chunks_per_doc`, `website_url`, `link_catalog`, `verification_rules`, `caller_number`, `channel`, `sms_enabled`, `page_guidance_enabled`, `integration_id`, `client_reference_id`, `tenant_id`	Creates realtime session + interactive state; may dispatch agent (except demo phone shortcut).
`status`	`session_id`	Returns interactive session snapshot (verification, page_context, pending SMS, etc.).
`bind_caller`	`session_id`, `caller_number`	Stores caller for SMS and telephony binding.
`page_context`	`session_id`, `page_context` object	Updates remote form/page state for the agent (second device).
`verification`	`session_id`, `category`, `verified`; optional `details` (e.g. `sms_catalog_key`)	Marks a category verified; may trigger auto SMS per rules.
`completion`	`session_id`; optional `status`, `message`, `updated_fields`	Marks flow completion; agent receives LiveKit notify.

Demo backend HTTP API

All routes below expect X-API-Key: {DEMO_API_KEY} unless noted.

Routes implemented in demo-app/backend-fastapi/main.py
Method & path	What it does	STS calls
`POST /api/interactive-agent`	Transparent proxy for browsers / tools.	`POST /STS/interactiveAgent` (same JSON)
`POST /api/hooks/voice-verify`	Parses STT utterance via `demo_voice_verify.py`; returns `verified` + `details.sms_catalog_key`.	Called by STS (outbound from STS), not the other way around.
`POST /api/client/form-event`	Builds `page_context` from payload (page, step, form_name, sections, …).	`action: page_context`
`POST /api/client/form-even`	Typo alias of `form-event`.	Same as above
`POST /api/client/verify-and-submit`	Checks hardcoded demo credentials, then verification + completion. `form_name === "healthcare_signup"` uses category `form` and matches SSN+DOB against any demo profile (real caller numbers OK).	`verification` then `completion`
`POST /api/client/verify-patient-info-demo`	`session_id`, `ssn_last4`; optional `patient_id`. Matches `DEMO_PATIENT_INFO_RECORDS`.	`verification` for `patient_information` with `details.sms_catalog_key`
`POST /api/client/form-completed`	Lightweight completion notify (no credential check).	`completion`
`GET /health`	Liveness.	—
`POST /webhooks/twilio/incoming-call`	Twilio Voice webhook: `start`, `bind_caller`, TwiML redirect to STS bridge.	`start`, `bind_caller`
`POST /webhooks/twilio/call-status`	Echoes CallSid / status (placeholder for analytics).	—

Twilio inbound sequence

Steps from ring to agent audio
Step	System	Detail
1	Twilio	`POST` form fields (`From`, `To`, `CallSid`) to demo `/webhooks/twilio/incoming-call`.
2	Demo backend	Builds `start_payload`: `channel: phone`, `website_url`, `link_catalog` (URLs from `DEMO_FRONTEND_BASE_URL`), `verification_rules` (including `voice_prompt` / `voice_prompt_short` for patient_information).
3	STS	`POST /STS/interactiveAgent` with `action: start` returns `session_id`, `room_name`.
4	Demo backend	`POST /STS/interactiveAgent` with `action: bind_caller` (same `session_id`, Twilio `From`).
5	Demo → Twilio	TwiML `<Redirect>` to `{STS_API_BASE_URL}/api/twilio/incoming-call?session_id=…&room_name=…&to=…&from=…`.
6	STS	Bridge connects the call leg to LiveKit; agent worker handles audio and interactive pipeline.

Voice verification hook (STS → demo)

For secured intents (e.g. patient_information), STS may POST to your hook with { session_id, utterance, category }. Configure on the STS process:

INTERACTIVE_VOICE_VERIFY_HOOK_URL = {your-demo}/api/hooks/voice-verify
INTERACTIVE_VOICE_VERIFY_HOOK_API_KEY = same secret as DEMO_API_KEY (header X-API-Key)

If the hook URL is unset, recent STS builds can run the packaged demo_voice_verify matcher in-process instead (see STS release notes / INTERACTIVE_VOICE_VERIFY_DISABLE_INLINE).

Demo credentials & patient rows

Replace in production with your database. Shown here for testing verify-and-submit and voice/hook matching.

DEMO_HARDCODED_USERS (verify-and-submit, non–healthcare_signup)

Caller must match key exactly
E.164 caller	SSN last 4	DOB
`+15551234567`	`1234`	`1990-01-01`
`+15550001111`	`1111`	`1988-05-15`

Healthcare signup path

form_name === "healthcare_signup": any caller number; verification uses SSN last four + DOB against any row in DEMO_HARDCODED_USERS (e.g. 1234 + 1990-01-01).

DEMO_PATIENT_INFO_RECORDS (voice hook + verify-patient-info-demo)

demo_voice_verify.py — SSN last four (and optional patient id)
SSN last 4	Patient id (compact)	Catalog key returned
`4521`	`pat01demo` (optional if SSN-only mode)	`patient_information`
`8822`	`pat02demo` (optional)	`patient_information`
`1111`	—	`patient_information`