VEverdun
voice-sessions

Start Talk Session

Claim a speaker for live voice and hand back the socket credentials.

Talking to a speaker with NO camera mapping is allowed (owner decision 2026-08-25): an operator addresses a place, not a camera. Tenant scoping is what contains it - SpeakersService.get_speaker runs ensure_parent_in_scope, so a site-scoped operator cannot reach another customer's speaker.

post/speakers/{speaker_id}/talk-sessions

Request

  • Base URL
    https://api.verdun.ai (the document declares no server; this is the origin it was published from)
  • URL
    https://api.verdun.ai/speakers/{speaker_id}/talk-sessions
  • Auth
    HTTP bearer

Path parameters

speaker_idstring required

Request body

event_idstring uuid nullable

The alarm this talk is about. Must be in the caller's scope. The speaker must share the alarm camera's current site and parent; a camera-speaker mapping is not required for human Live Talk.

camera_idstring uuid nullable

Optional; must equal the alarm's camera. Requires event_id.

Response

Successful Response

session_idstring uuid required

The session that now holds this speaker.

speaker_idstring uuid required

The speaker being talked through.

speaker_labelstring required

The speaker's display name.

ws_urlstring required

Path to open the audio WebSocket on. Present the ticket as ?ticket=.

ticketstring required

Single-use, short-lived credential for the audio socket. The browser WebSocket API cannot send an Authorization header, so this stands in for the bearer token. Shown once.

expires_atstring date-time required

After this the ticket is dead and the session is reaped.

max_secondsinteger required

Hard cap on the session. The server stops it regardless of the client.

idle_secondsinteger required

Silence for this long ends the session - an open mic never dangles.

Example response

{
  "speaker_label": "SE Horn - dumpster",
  "ws_url": "/speakers/talk/2b0f.../stream",
  "max_seconds": 120,
  "idle_seconds": 10
}

Changes

No recorded changes to this operation across all 2 revisions of this API.