Voicebot realtime sessions
Create a realtime voicebot session, connect a browser media client with the returned room payload, read persisted transcript messages, and close the session when the call ends.
These endpoints require authentication. Session creation charges the first billable minute immediately. Closing the session bills any remaining elapsed duration beyond that initial charge.
Create Session
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
voicebotId | string | Yes | Voicebot identifier. |
participantName | string | No | Participant name shown in the realtime session. |
Response (201)
| Field | Type | Description |
|---|---|---|
sessionId | string | Logical session identifier. |
participantToken | string | Token used by the browser media client to join the room. |
livekitUrl | string | Realtime media server WebSocket URL. |
roomName | string | Room name used for connection, transcript reads, and end. |
voicebotName | string | Voicebot display name, when available. |
voicebotAvatarUrl | string | Voicebot avatar URL, when available. |
imageMappings | array | Optional image key mappings for UI rendering. |
expiresAt | string | Participant token expiry timestamp. |
curl -X POST https://api.valsea.ai/v1/voicebot-livekit/session \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"voicebotId": "665f5aa613e4fe2f12ab34cd",
"participantName": "web-user-001"
}'
Browser Connection Flow
After creating a session, keep participantToken, livekitUrl, and roomName in memory. Use the media client to connect to livekitUrl with participantToken, enable the local microphone, subscribe to remote audio tracks, and listen for transcript or image events on the data channel. When the call ends, disconnect the room and call the end-session endpoint with roomName.
Image Mappings
Use this as a fallback when the create-session response does not include enough imageMappings data.
cURL
curl -X GET https://api.valsea.ai/v1/voicebot-livekit/voicebots/665f5aa613e4fe2f12ab34cd/image-mappings/library \
-H "Authorization: Bearer YOUR_API_KEY"
Session Messages
Read transcript messages persisted by the realtime agent.
| Query | Type | Default | Description |
|---|---|---|---|
limit | number | 50 | Number of messages to return. |
offset | number | 0 | Pagination offset. |
End Session
Always end the session when the call finishes so final duration billing and cleanup can complete.
cURL
curl -X DELETE https://api.valsea.ai/v1/voicebot-livekit/session/ext-vb-665f5aa613e4fe2f12ab34cd-a1b2c3d4e5f6 \
-H "Authorization: Bearer YOUR_API_KEY"
Errors
| Status | Description |
|---|---|
400 | Invalid body, path parameter, or query parameter |
401 | Missing or invalid API key |
402 | Insufficient credits for session creation |
403 | Session belongs to another organization |
500 | Internal server error |