API · Sessions

How sessions work

A session is one live avatar on one screen: one visitor, one conversation, from start to stop.

The life of a session

•Start. Your server calls POST /v1/sessions with an agent. The avatar is ready in a second or two when one is warm.
•Show. The visitor opens player_url, in an iframe on your page or as a link. In render mode your server also connects to ws_url.
•Talk. In a conversation the avatar talks with the visitor on its own. In render mode it speaks what you send it.
•Stop. You call POST /v1/sessions/{id}/stop. The page disconnects and the session's minutes are counted.

Two modes

Mode	Who talks	Price
`conversation`	Your Selvia AI agent: it listens to the visitor and answers from its knowledge.	$0.03 / min
`render`	Your own agent. You stream speech (or text we voice) to the avatar. See Render mode.	$0.025 / min

How a session ends

A session runs until one of these happens. Its status then shows the reason.

end_reason	What happened
`api_stop`	You stopped it with the API.
`session_limit`	A free account reached its 5 minutes for one session.
`idle_timeout`	Nobody watched it for about 90 seconds (the page was never opened, or was closed).
`embed_ended`	A visitor ended a conversation in the website widget.

A session is billed from start to stop, rounded up to the whole minute. It runs until you stop it, so always stop the sessions you start. The only automatic stops are the free plan's 5 minutes and a session that nobody watches.

One page per session

player_url works only for its own session. When the session ends the page disconnects, and opening it again shows nothing: a page left open can never watch the next visitor's session. Start a new session for each visitor.

List live sessions

GET/v1/sessions

Every live session of your account: the ones you started with the API, website-widget visitors and console calls.

curl https://talk.selviaai.com/v1/sessions \
  -H "Authorization: Bearer $SELVIA_API_KEY"

Check a session

GET/v1/sessions/{session_id}

status is active while it runs and ended afterwards. In render mode your socket also closes with code 4001 when the session ends.

Response

{
  "session_id": "1b913015-776e-4700-b17f-f1a9cdc8338f",
  "status": "ended",
  "mode": "render",
  "source": "api",
  "agent_id": 7,
  "started_at": "2026-10-17T10:55:15Z",
  "ended_at": "2026-10-17T10:58:19Z",
  "end_reason": "api_stop"
}

Stop a session

POST/v1/sessions/{session_id}/stop

Ends any of your sessions, whatever started it. Stopping one that already ended answers the same way, so it is safe to retry.

Capacity

Each agent has a number of conversations it may hold at once (its concurrency_limit, set on the agent). Past it, a new session answers 409 concurrency_limit. When every avatar is busy, it answers 503 no_capacity: try again shortly. See Errors.