Skip to main content

Conversational Agent APIs Quick Start

Set up your first agent in under 15 minutes — browse the catalog, build an avatar, configure an intellect, and wire it all together into a conversational agent.

Before you start

You'll need a Kaltura Session (KS). See Prerequisites if you haven't set one up yet.

What you'll build​

By the end of this guide you'll have a fully configured agent ready for real-time sessions:

📦 Catalog  ──► 🎭 Avatar
(voice + visual) (face + voice)
                      │
📚 Knowledge ──► 🧠 Intellect
(optional)       (AI config)
                      │
                      ▼
                 🤖 Agent
                      │
                      ▼ getEmbedScript
                 👤 End User

Step 1: Browse the catalog​

See what voices and visuals are already available (Kaltura provides presets out of the box):

List available visuals
curl -X POST "https://YOUR_API_HOST/service/catalog-item/action/list" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "filter": { "typeEqual": "Visual" }, "pager": { "offset": 0, "limit": 30 } }'
List available English voices
curl -X POST "https://YOUR_API_HOST/service/catalog-item/action/list" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "filter": { "typeEqual": "Voice", "languageEqual": "en-US" }, "pager": { "offset": 0, "limit": 30 } }'

Note the itemId from each result — you'll need one visual ID and one voice ID.

Step 2: Create an avatar​

Combine a visual and a voice into a reusable character:

curl -X POST "https://YOUR_API_HOST/service/avatar/action/create" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "visual": { "id": "VISUAL_ITEM_ID" },
    "voice": { "id": "VOICE_ITEM_ID", "speed": 1.0 },
    "openingPhrase": "Hi! How can I help you today?"
  }'

Save the id from the response — that's your AVATAR_ID.

Step 3: Create an intellect​

An intellect defines the AI personality — name, goals, knowledge, and capabilities. Create one and note its id for the next step:

curl -X POST "https://YOUR_API_HOST/v1/intellect/add" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "internal",
    "name": "My Assistant",
    "status": 1,
    "prompts": [
      {
        "key": "name",
        "label": "name",
        "headerTemplate": "You will be identified as this name, this is your name:",
        "type": "custom",
        "value": "Kali"
      },
      {
        "key": "goal",
        "label": "Goal",
        "headerTemplate": "Your main goal is:",
        "type": "custom",
        "value": "Help users find and watch video content."
      }
    ],
    "capabilities": {
      "avatar": "on",
      "use_knowledge_base": "off"
    }
  }'

Save the id from the response — that's your INTELLECT_ID (used as configId in the agent).

Optional: attach a knowledge base

If you want the assistant to search your Kaltura media library or a website, create a 📚 Knowledge record first, then pass its id in knowledge_ids and set use_knowledge_base: "on" in capabilities.

Step 4: Create an agent​

Link the avatar and intellect together:

curl -X POST "https://YOUR_API_HOST/service/agent/action/create" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "My First Assistant",
    "intellect": {
      "intellectType": "genie",
      "genieId": "YOUR_GENIE_ID",
      "configId": INTELLECT_ID
    },
    "avatarIds": ["AVATAR_ID"],
    "maxConversationLength": 1800
  }'

Save the agentId — your agent is fully configured.

Step 5: Get the embed script​

Your agent is ready. Call getEmbedScript to get a ready-to-use HTML snippet:

curl -X POST "https://YOUR_API_HOST/service/agent/action/getEmbedScript" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "YOUR_AGENT_ID" }'

Paste the returned html into any webpage — it loads the Unisphere widget and launches the agent automatically.

Complete JavaScript example​

const API_HOST = 'https://YOUR_API_HOST';
const KS = process.env.KALTURA_KS;

// Helper for action-based services (Agent, Avatar, Catalog)
async function kAction(service, actionName, body = {}) {
  const res = await fetch(`${API_HOST}/service/${service}/action/${actionName}`, {
    method: 'POST',
    headers: { Authorization: `KS ${KS}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  return res.json();
}

// Helper for REST-style services (Intellect, Knowledge)
async function v1Action(service, actionName, body = {}) {
  const res = await fetch(`${API_HOST}/v1/${service}/${actionName}`, {
    method: 'POST',
    headers: { Authorization: `KS ${KS}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  return res.json();
}

// 1. Pick catalog items
const { objects: visuals } = await kAction('catalog-item', 'list', { filter: { typeEqual: 'Visual' } });
const { objects: voices } = await kAction('catalog-item', 'list', { filter: { typeEqual: 'Voice', languageEqual: 'en-US' } });
const visualId = visuals[0].itemId;
const voiceId = voices[0].itemId;

// 2. Create avatar
const avatar = await kAction('avatar', 'create', {
  visual: { id: visualId },
  voice: { id: voiceId, speed: 1.0 },
  openingPhrase: 'Hi! How can I help you today?',
});

// 3. Create intellect
const intellect = await v1Action('intellect', 'add', {
  type: 'internal',
  name: 'My Assistant',
  status: 1,
  prompts: [
    {
      key: 'name',
      label: 'name',
      headerTemplate: 'You will be identified as this name, this is your name:',
      type: 'custom',
      value: 'Kali',
    },
    {
      key: 'goal',
      label: 'Goal',
      headerTemplate: 'Your main goal is:',
      type: 'custom',
      value: 'Help users find and watch video content.',
    },
  ],
  capabilities: { avatar: 'on', use_knowledge_base: 'off' },
});

// 4. Create agent
const agent = await kAction('agent', 'create', {
  displayName: 'My First Assistant',
  intellect: {
    intellectType: 'genie',
    genieId: 'YOUR_GENIE_ID',
    configId: intellect.id,
  },
  avatarIds: [avatar.id],
  maxConversationLength: 1800,
});

// 5. Get embed script
const { html } = await kAction('agent', 'getEmbedScript', {
  agentId: agent.agentId,
});

console.log('✅ Agent ready:', agent.agentId);
console.log('Paste this HTML into your webpage:', html);

Next Steps​