Initialize Client - Agentic Avatars SDK

Initialize Client

Initialize the avatar client to get WebRTC configuration.

Endpoint

POST /v1/avatar-session/:sessionId/init-client

Authentication

Header: Authorization: Bearer {token}

The token is received from create-session.

Path Parameters

Parameter	Type	Required	Description
sessionId	string	Yes	Session ID from create-session

Request Body

Empty body ({}).

Response

Success (200)

{
  "success": true,
  "whepUrl": "string",
  "turn": {
    "url": "string",
    "credential": "string",
    "username": "string"
  }
}

Field	Type	Description
success	boolean	Always true on success
whepUrl	string	WebRTC WHEP endpoint URL for media streaming
turn	object	TURN server configuration for WebRTC
turn.url	string	TURN server URL
turn.credential	string	Credential for TURN server authentication
turn.username	string	Username for TURN server authentication

Error Responses

401 Unauthorized

{
  "success": false,
  "error": "Invalid or expired token"
}

404 Not Found

{
  "success": false,
  "error": "Session not found"
}

410 Gone

{
  "success": false,
  "error": "Session ended"
}

Examples

cURL

curl -X POST https://api.avatar.us.kaltura.ai/v1/avatar-session/session-123/init-client \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

JavaScript (fetch)

const response = await fetch(`https://api.avatar.us.kaltura.ai/v1/avatar-session/${sessionId}/init-client`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const data = await response.json();
console.log('WHEP URL:', data.whepUrl);
console.log('TURN config:', data.turn);

Usage Notes

When to Call

Call this endpoint immediately after creating a session and before displaying the avatar.

What It Returns

• whepUrl: Use this to establish WebRTC connection for video streaming
• turn: TURN server credentials for NAT traversal

WebRTC Configuration

Use the returned configuration with the Client SDK:

import { AvatarRTCSDK } from '@unisphere/models-sdk-js';

const rtcSDK = new AvatarRTCSDK({
  whepUrl: data.whepUrl,
  iceServers: [
    {
      urls: [
        `turn:${data.turn.url}:80?transport=udp`,
        `turn:${data.turn.url}:443?transport=udp`,
        `turn:${data.turn.url}:80?transport=tcp`,
      ],
      username: data.turn.username,
      credential: data.turn.credential,
    },
  ],
});

await rtcSDK.connect();

Client SDK Automatic

If using the Client SDK's createSession() method, this endpoint is called automatically.

Next Steps

• Say Text - Make the avatar speak
• Keep Alive - Maintain the session