Skip to content
Radioso Docs home
Open app

Chat and history

This is the main agent chat workflow for authenticated API clients.

How it works

  1. Send a chat request with a workspace token.
  2. Optionally set agentId. When omitted, Radioso uses the workspace default agent.
  3. Choose whether the response should stream.
  4. Reuse conversationId when you want continuity across turns.
  5. Inspect saved conversations later through the history routes.

Agents own assistant identity, instructions, greeting settings, retrieval participation, per-skill settings, and surface settings for authenticated chat, anonymous chat, and website embed. Retrieval answer configuration lives on the agent through skillSettings["retrieval.answer"]; omitted fields inherit system/model defaults. If an agent has retrieval enabled, assistant chat may use retrieval and return citations. Direct-only agents use the direct assistant path and return retrieval diagnostics with retrievalInvoked: false.

Ask a grounded question

This calls the hosted EU API; use https://api-us.radioso.ai or your own self-hosted origin instead, matching wherever $RADIOSO_API_TOKEN was issued — see Workspaces and tokens.

bash
curl -sS -X POST https://api.radioso.ai/api/v1/assistant/chat \
  -H "Authorization: Bearer $RADIOSO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"What does the FAQ say about uploaded content?","stream":false}'

The chat request schema also supports:

  • conversationId for follow-up turns
  • agentId for selecting a non-default workspace agent
  • startConversation: true for bootstrap flows
  • userExpectedLocale when the caller knows the user’s locale
  • inputMetadata and metadataFilter for richer routing and filtering

Bootstrap responses are ephemeral. When startConversation: true returns a greeting, the response can omit conversationId. Save and reuse a conversationId only after the first normal user message returns one.

If the bootstrap response includes bootstrapGreetingId, send it with the first normal user message and no conversationId. Radioso saves the displayed greeting only when that first user message creates the conversation.

Streaming and non-streaming modes

stream defaults to false; set it per request.

In practice:

  • use stream: false for simple request-response flows
  • use stream: true when you want incremental output

A stream can emit status before the answer begins. Its stage is one of interpreting, searching, or composing. Map these values to localized UI copy in the client; they are not assistant messages. A successful answer then uses chunk and done. A superseded pre-answer turn ends with cancelled, which is terminal.

Chunks indicate incremental delivery, not necessarily live model tokens. Replies that require validation or a durable write can be committed first and replayed in bounded chunks. Clients should ignore unknown event names so additive stream events remain compatible.

Use the API Reference for the exact streaming and non-streaming response contracts.

Conversation history

Use GET /api/v1/history to list merged chat and document-search history.

Use GET /api/v1/history/chat to list saved conversations. Add ownership=human_owned to return only conversations currently owned by a human operator; the response total then counts waiting handoffs.

Use GET /api/v1/history/chat/{conversationId} to retrieve one conversation and its debug metadata. The older GET /api/v1/history/{conversationId} route is a compatibility alias.

That second route is the one to use when you need to inspect how a specific answer was produced.

A turn without a reply still shows up here. If the visitor sent another message before the assistant answered, or the answer attempt failed outright, the interrupted user message carries a turnFailure object: eventStatus of cancelled for the first case (with the pipeline stage it was interrupted at) or failure for the second (with errorMessage). turnFailure is dashboard-only — it never appears on the public or embed conversation reads.

Use GET /api/v1/history/chat/{conversationId}/tail to read messages created after a cursor. The cursor is the newest message the client has already seen. Conversation detail responses include tailCursor; use it for follow-up tail calls after loading the transcript. If cursor is omitted, Radioso returns the newest bounded page and a cursor for the newest returned message. Dashboard tail responses can include ownership when the conversation is currently human-owned.

Endpoint reference

text
GET  /api/v1/agents
POST /api/v1/agents
GET  /api/v1/agents/{agentId}
PUT  /api/v1/agents/{agentId}
POST /api/v1/agents/{agentId}/default
POST /api/v1/assistant/chat
GET  /api/v1/history
GET  /api/v1/history/chat
GET  /api/v1/history/chat/{conversationId}
GET  /api/v1/history/chat/{conversationId}/tail
GET  /api/v1/history/search
GET  /api/v1/history/search/{searchId}

Common failure modes

  • 400 usually means the request body is invalid.
  • 401 means the workspace token is missing or invalid.
  • 404 can mean the conversation id is not available in the current workspace context.
  • 204 is part of the route contract. Use the reference page for the exact no-body case.