Widget & Runtime Init — @kaltura/intelligent-agents

Reference

How a browser app turns an agent id into a widget id, then into the hosts and KS it needs to start a session. Read this to wire the browser side of a deployment.

POST https://api.avatar.us.kaltura.ai/v1/application/resolveWidgetId

{ "agentId": "33b7c8b7-f67b-4ca3-b853-0f7ced06a6a3" }

Returns { "widgetId": "1_v1mj1kxb" }. Idempotent.

Initialize the Runtime

POST https://api.avatar.us.kaltura.ai/v1/application/appInit   (widget KS, no body)

WIDGET_KS=$(curl -s -X POST "https://www.kaltura.com/api_v3/service/session/action/startWidgetSession" \
  -d "format=1" -d "widgetId=1_v1mj1kxb" \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['ks'])")

Response:

Field	What it is
`partnerId`	The partner the widget resolves to
`ks`	Enriched KS with `geniegpcid`. Use it for conversation
`conversationManagerUrl`	Socket.IO control-plane host
`srsBaseUrl`	WHEP video-stream host
`turnServerUrl`	TURN host
`avatars[]`	`[{id, previewImageUrl, loadingVideoUrl}]`. Asset URLs for the avatar preview and loading video. They are not the rendered composite that the live WHEP stream shows
`widgetConfig` / `embedConfig`	Optional, present only when the widget was configured with them

The admin secret never touches the browser. appInit derives the agent from the widget KS.

Every visitor gets the same widget KS. Reach and limits: Security & Compliance § Session type. Per-attendee credentials and per-user separation are not possible on this path.

Per-visitor browser path

Use this when users must be kept apart. The server mints the token and the browser only receives the result:

Server: createAgentToken({ agentId, userId }), with a distinct userId per visitor.
Server: mgmt.application.appInit(token).
Server: send the returned ks (and hosts) to the browser.

That KS answers as the agent, keeps entitlement ON and keeps the user's identity. What it can reach: Security & Compliance § Session type.

The response also carries server-side flag fields, such as legacyScreenShareEnabled. Their names may change. Do not read them in your app. Use the SDK settings instead, for example the agent's screenShare (agent fields).

Feed this response straight into new KalturaAvatarSession({ token: ks, conversationManagerUrl, srsBaseUrl, turnServerUrl, videoEl, socketFactory }) (./experience) to bring the runtime up in the browser.

appInit does not return the conversation host. The session still makes two direct POSTs of its own, the respondToTool() ACKs and the session-completed signal, and it sends them to the genieUrl of the session's region (default nvp1, US). If your partner is in another region, pass the session the same region you gave Management. For a deployment not in REGIONS, pass the same genieUrl instead. KalturaAgentSession takes region at the top level and genieUrl under avatar and chat.

Two options on all three session classes (KalturaAvatarSession, KalturaChatSession, KalturaAgentSession) shape how the conversation starts:

Option Effect

kickoff: 'text' or { text, echo? } The SDK sends text as the first turn, once per session object, as soon as the server accepts input (after the opening turn, or after acknowledgeDisclosure()). Never re-sent on resume(), a reconnect or switchMode(). echo: true also emits it as a user transcript. A blocked send emits warning {code:'kickoff_failed'}. Pair with a silent opening phrase (SILENT_OPENING) for the fastest interruptible first reply: Start the Conversation

micStartMode: 'immediate' | 'deferred' (avatar only) connect() never waits for or fails on the mic. A denied or missing mic emits a warning and the session connects mic-less; typed turns still work

Option	Effect
`kickoff: 'text'` or `{ text, echo? }`	The SDK sends `text` as the first turn, once per session object, as soon as the server accepts input (after the opening turn, or after `acknowledgeDisclosure()`). Never re-sent on `resume()`, a reconnect or `switchMode()`. `echo: true` also emits it as a user `transcript`. A blocked send emits `warning {code:'kickoff_failed'}`. Pair with a silent opening phrase (`SILENT_OPENING`) for the fastest interruptible first reply: Start the Conversation
`micStartMode: 'immediate' \| 'deferred'` (avatar only)	`connect()` never waits for or fails on the mic. A denied or missing mic emits a `warning` and the session connects mic-less; typed turns still work

responsePending fires when a turn starts awaiting the server's first perceivable output, and again when the server acknowledges a turn with its first think delta, so a kickoff reply shows "thinking" before the first word.

Optional ./experience plugins layer on top of that same session:

Deck walkthroughs (./experience/presenter)
A transparent-background compositor for the avatar video (./experience/chroma-key)
Noise suppression
GenUI widgets
KAVA (Kaltura Video Analytics) reporting

All of them are documented in README.md alongside their runnable examples/*.html demos, not here. This reference covers the server-side Management API surface only.