Skip to main content

​
Overview

A Session represents a single conversation with an AI avatar. Each session includes a Daily.co video room for streaming and tracks the lifecycle from creation to completion. Session Lifecycle:
  • Created → Session initialized with Daily.co room
  • Started → Avatar server activated and ready
  • Ended → Session completed, resources released

​
Fields

The Session object contains all information needed to connect to and manage an avatar conversation.
FieldTypeDescription
session_idstringUnique session identifier (starts with sess_)
avatarobjectAvatar information object
avatar.avatar_idstringID of the avatar associated with this session
avatar.namestringDisplay name of the avatar
avatar.urlstringPreview image URL for the avatar
session_typestringType of session (currently only webrtc_video)
statusstringSession status: created, started, or ended
started_atstring | nullISO 8601 timestamp when session started (null if not started)
ended_atstring | nullISO 8601 timestamp when session ended (null if not ended)
created_atstringISO 8601 timestamp when session was created
access_tokenstringAccess token for WebSocket authentication (only in create response)
daily_roomobject | nullDaily.co room information for video session
daily_room.urlstringDaily.co room URL
daily_room.namestringDaily.co room name
daily_room.tokenstringMeeting token for joining the room
expirationstring | nullISO 8601 timestamp when session expires (based on subscription plan limits)
durationnumber | nullSession duration in seconds (only set after session ends)
metadataobjectCustom metadata object
The WebSocket URI for streaming commands is returned by the Start Session endpoint as ws_uri. It is not included in the session objects returned by GET /v1/sessions or GET /v1/sessions/{session_id}.

​
Status Values

The status field is derived from the session’s timestamps:
StatusConditionDescription
createdstarted_at is nullSession created but not yet started
startedstarted_at is set, ended_at is nullSession is currently active
endedended_at is setSession has been completed

​
Daily.co Room Integration

Sessions include a daily_room object for video streaming via Daily.co infrastructure:
  • url: The Daily.co room URL for video connection
  • name: Unique room identifier
  • token: Authentication token for joining the room
  • exp: Room expiration timestamp (based on subscription plan)

​
Session Expiration

The expiration field indicates when the session will automatically end, based on your subscription plan’s session time limits:
  • Free Plan: Sessions expire after a certain duration
  • Paid Plans: May have longer or unlimited session durations

​
Example

​
Created Session

{
  "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
  "avatar": {
    "avatar_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W4T",
    "name": "Professional Avatar",
    "url": "https://example.com/avatars/preview.jpg"
  },
  "session_type": "webrtc_video",
  "status": "created",
  "access_token": "access_token_xxxxxxxxxxxxx",
  "started_at": null,
  "ended_at": null,
  "expiration": null,
  "duration": null,
  "created_at": "2024-01-15T10:30:00Z",
  "metadata": {
    "user_name": "John Doe",
    "session_purpose": "Customer Support"
  }
}

​
Started Session

{
  "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
  "avatar": {
    "avatar_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W4T",
    "name": "Professional Avatar",
    "url": "https://example.com/avatars/preview.jpg"
  },
  "session_type": "webrtc_video",
  "status": "started",
  "started_at": "2024-01-15T10:35:00Z",
  "ended_at": null,
  "expiration": "2024-01-15T14:35:00Z",
  "duration": null,
  "created_at": "2024-01-15T10:30:00Z",
  "metadata": {
    "user_name": "John Doe",
    "session_purpose": "Customer Support"
  }
}

​
Ended Session

{
  "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
  "avatar": {
    "avatar_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W4T",
    "name": "Professional Avatar",
    "url": "https://example.com/avatars/preview.jpg"
  },
  "session_type": "webrtc_video",
  "status": "ended",
  "daily_room": {
    "url": "https://agenthuman.daily.co/example-room-name",
    "name": "example-room-name",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "started_at": "2024-01-15T10:35:00Z",
  "ended_at": "2024-01-15T11:20:00Z",
  "expiration": "2024-01-15T14:35:00Z",
  "duration": 2700,
  "created_at": "2024-01-15T10:30:00Z",
  "metadata": {
    "user_name": "John Doe",
    "session_purpose": "Customer Support"
  }
}