conversation-api¶

Status: Current | Last reviewed: 2026-07-07

conversation-api is the HTTP/SSE surface for chat, voice-adjacent, and multimodal conversation integrations. It exposes conversation setup, user responses, session context, share-code resolution, A2UI render events, and conversation inspection. The full contract is the OpenAPI spec embedded below — this page covers when and how to use it.

Quick reference¶

Detail	Value
Base URL	`https://conversation-api.vanguard.dev.trueserve.deloitte.com`
Authentication	Bearer token; see Authentication
Content-Type	`application/json` for REST, `text/event-stream` for SSE
Required scopes	See each endpoint's security block in OpenAPI; most external callers use token scopes derived from `agents:manage`

When to use it¶

You want to...	Use
Start a conversation from a custom UI	`POST /conversations`
Send a user response	`POST /conversations/{conversation_id}/responses`
Stream TrueServe events for a conversation	`GET /sse/conversations/{conversation_id}`
Stream TrueServe or AG-UI events through the API namespace	`GET /api/v1/conversations/{conversation_id}/events?format=trueserve\|agui`
Inject context or state mid-conversation	`POST /sessions/{session_id}/context`
Manage raw local session variables	`GET/POST /sessions/{session_id}/variables`, `POST /sessions/{session_id}/variables/{name}/append`
Create or resolve multimodal share codes	`POST /share-codes`, `POST /share-codes/{code}/resolve`
Read a transcript programmatically	`GET /conversations/{conversation_id}/transcript`
Search conversation history	`POST /conversations/search`
Tear a session down	`DELETE /conversations/{conversation_id}`

Platform-managed telephony talks to ai-orchestrator over gRPC. External web, chat, and multimodal integrations should use conversation-api.

A few endpoints worth calling out¶

The Swagger view below is the source of truth for shapes and parameters; these notes explain the why behind a few entries that aren't self-evident.

`HEAD /conversations/{id}` — cheap authorization probe¶

Returns 204 if the caller is authorized to read the conversation, 404 otherwise. No body. Use this when an embedder needs to confirm access before opening the SSE stream — it skips the cost of fetching messages and events that the matching GET would pay.

`POST /conversations/search` — rich history search¶

Searches the indexed conversation-history row (conversation_search_documents) with cursor pagination. Use it for both global conversation search and per-agent history. Filters include date range, agent id, version, status, channel, caller, outcome, recording availability, archive state, and test traffic. The response shape is { items, nextCursor, hasMore, total? }; treat nextCursor as opaque.

Share codes are conversation capabilities, not a separate product API. They create short-lived access to an existing conversation's multimodal surface:

Endpoint	Purpose
`POST /share-codes`	Create a code tied to an existing `conversation_id`
`GET /share-codes?conversation_id=...`	List codes for a conversation
`POST /share-codes/{code}/resolve`	Exchange the code for conversation details; on first resolve, `session_params` are injected as session variables
`DELETE /share-codes/{code}`	Revoke a code

Use share codes when a voice/SMS flow needs to hand a caller into a browser surface for A2UI. Resolving a code is anonymous by design: possession of the code is the capability.

Session context vs session variables¶

Use POST /sessions/{session_id}/context for new integrations. It is the deployment-aware operation: local pipeline agents persist data keys as session variables for {{merge field}} prompts on the next turn, remote Agent Assist sessions forward references for immediate context injection, and providers without a live context API return unsupported.

POST /sessions/{session_id}/variables is the older local-pipeline specialization. It writes a flat JSON object directly into local session-variable storage. Keep using the variables endpoints only when you need raw variable reads, compatibility with existing local flows, or append/list behavior such as POST /sessions/{session_id}/variables/{name}/append with TTL. Long term, /context should be the canonical write path for mid-session state, while /variables remains the low-level compatibility and inspection surface.

Demo Notifications — phone-emulator demo surface only¶

The Demo Notifications section is a deliberately scoped surface for the phone-emulator demo experience: inbound SMS / email notifications arrive via POST /api/notifications/inbound (driven by an AWS Lambda), are persisted to demo_notifications, fanned out over a Redis pub/sub channel keyed by session, and delivered to demo UIs over SSE at GET /api/notifications/stream. It is not the production messaging path — production SMS goes through the share-code / multimodal-SMS endpoints. Callers integrating against a tenant's real conversational flow should ignore this section.

For recorded demos, POST /conversations/{conversation_id}/multimodal-sms accepts delivery_mode: "demo_notification" and optional notification_session_id. In that mode the endpoint still creates or reuses the multimodal share code, but it writes an inbound SMS row to demo_notifications and publishes the SSE notification instead of calling the workflow-backed SMS path to send carrier SMS. Responses use sms_status: "simulated" for successful demo delivery.

Multimodal share links use SURFACE_APP_BASE_URL when set, then NEXT_PUBLIC_SURFACE_APP_URL, then SURFACE_APP_URL. If a caller supplies surface_app_base_url, conversation-api accepts that value only when it matches one of those configured URLs or an entry in SURFACE_APP_ALLOWED_BASE_URLS.

Browser-origin requests are fail-closed by default: EMBED_CORS_VALIDATION_ENABLED enables middleware that checks the request Origin against ai-manager's active allowed-origins table, and EMBED_ALLOW_LOCALHOST is false unless a local/Kind overlay explicitly enables it. ALLOWED_ORIGINS_REGEX controls CORS response headers; it is not the only enforcement point.

SSE event stream¶

The TrueServe stream emits standard Server-Sent Events. Each frame has an SSE id:, an event: value, and JSON data::

id: <redis-stream-id-or-event-id>
event: final_transcript
data: {"type":"final_transcript","eventId":123,"conversationId":456,"timestamp":...,"data":{"text":"Hello","role":"agent","is_final":true}}

GET /sse/conversations/{conversation_id} returns the TrueServe event stream. GET /api/v1/conversations/{conversation_id}/events?format=trueserve routes to the same stream. format=agui returns AG-UI BaseEvent objects instead.

Common TrueServe event: values:

Event	Shape	Notes
`interim_transcript`, `final_transcript`, `refined_transcript`, `reasoning`	`data.text`, `data.delta_text`, `data.role`, `data.is_final`, `data.turn_id`, `data.message_key`, `data.variant`, optional `data.agent`, optional `data.citations`	Transcript and message timeline events. `refined_transcript` is the enhanced final variant.
`knowledge_suggestion`	`data.suggestion_type`, plus `response_text` or `responses[]`, `citations[]`, `title`, `snippet`, `url`/`link`, `confidence`	Smart replies and knowledge suggestions share this channel.
`suggestion`	`data.suggestion_type`, `data.form_fields[]`, `data.form_id`, `data.form_status`, optional metadata	Used for form-filling and structured suggestions.
`tool_call`	`data.tool_name`, `data.tool_call_id`, `data.arguments`, `data.status`, `data.result`	Tool execution visibility.
`UI_RENDER`	top-level `surface_id`, `catalog_id`, `message_type`, `payload`, `actor_id`, optional `treatment`, optional `layout`	A2UI render instruction consumed by surface clients.
`ENABLE_MULTIMODAL`	top-level `session_token`, `multimodal_url`, `permission_status`	Signals that a browser multimodal surface can attach.
`PIPELINE_EVENT`	`data.event_kind`, `data.event_kind_name`, `data.frame_type`, `data.turn_number`, `data.duration_secs`, `data.was_interrupted`, `data.details_json`, `data.source`	Runtime lifecycle events such as speech start/stop, turn boundaries, TTS/STT/LLM start/stop, idle prompts, and call end.
`STATUS`	top-level `status`, `message`, `timestamp`	Conversation lifecycle status: started, idle, processing, transferred, ended.
custom insight kind, e.g. `transcript_analysis`	`data.kind`, `data.score`, plus kind-specific fields	Custom insight events use their `kind` as the SSE event name.

Reconnect with Last-Event-ID to resume from where you left off. Clients should ignore unknown event types and handle SSE comments such as : keep-alive.

Note: surface-app consumes this exact stream. If you're embedding surface-app you're already getting the SSE handling for free — see Embedding surface-app.

Smart Reply suggestions are emitted as knowledge_suggestion SSE events with data.suggestion_type="smart_reply". New clients should read data.responses[] (text, confidence, citation_ids) and data.citations[]; data.response_text is still populated with the first response for older clients.

Live OpenAPI¶

The block below renders the running service's /openapi.json. If the live service is unavailable while the docs build, the generator keeps the last successful spec when one exists so this reference does not collapse to an empty OpenAPI page.