Skip to main content

🚀 Conversational Agents APIs

Three services, one goal: bring your conversational agents to life.

The Conversational Agents APIs are the management layer of the Kaltura avatar platform. They let you configure everything — from the raw visual and voice building blocks, to assembled avatar personalities, to the intelligent agents your users will actually talk to.

Think of them as the backstage crew that sets the stage before the real-time show begins.

The Cast​

ServiceRoleThink of it as...
📦 Catalog ServiceLibrary of visual appearances and voices"The wardrobe & voice studio"
🎭 Avatar ServicePairs a face with a voice"The character casting"
📚 Knowledge ServiceIndexed content the AI can search"The reference library"
🧠 Intellect ServiceConfigures the AI brain"The script & personality"
🤖 Agent ServiceCombines avatar + intelligence"The actor on stage"

How It All Fits Together​

These services form a layered architecture. Each layer builds on the one below it:

┌─────────────────────────┐   ┌─────────────────────────┐
│   📦 Catalog Service    │   │   📚 Knowledge Service  │
│   Visual & Voice items  │   │   Indexed content       │
└────────────┬────────────┘   └────────────┬────────────┘
             │ voice.id / visual.id        │ knowledge_ids
             ▼                             ▼
┌─────────────────────────┐   ┌─────────────────────────┐
│   🎭 Avatar Service     │   │   🧠 Intellect Service  │
│   Face + Voice pairings │   │   Prompts, glossary,    │
└────────────┬────────────┘   │   capabilities          │
             │ avatarIds      └────────────┬────────────┘
             │                             │ configId
             └──────────────┬──────────────┘
                            ▼
               ┌─────────────────────────┐
               │   🤖 Agent Service      │
               │   Avatar + Intelligence │
               └────────────┬────────────┘
                            │ getEmbedScript
                            ▼
                    ┌───────────────┐
                    │   👤 End User │
                    └───────────────┘

Start from the top:

  1. Catalog — upload or browse voice samples and avatar visuals
  2. Avatar — combine a voice and a visual into a reusable character
  3. Knowledge — index your Kaltura media library or web content
  4. Intellect — define the AI personality, prompts, glossary, and attach knowledge
  5. Agent — link an avatar with an intellect and tune conversation behaviour
  6. Deliver — call getEmbedScript with your agentId and paste the returned HTML into any webpage
The building blocks at a glance
  • A catalog item is a raw asset: a face or a voice.
  • An avatar is a composition: one visual + one voice combined into a named character.
  • A knowledge record is an indexed content collection the AI can search.
  • An intellect is the AI configuration: persona, prompts, glossary, knowledge, capabilities.
  • An agent is the deployment unit: avatar + intellect + conversation settings.

API Routing Conventions​

The services use two different routing patterns depending on which underlying platform they are built on.

Action-based routing (Agent, Avatar, Catalog)​

POST /service/{prefix}/action/{actionName}
ServicePrefixExample
AgentagentPOST /service/agent/action/create
AvataravatarPOST /service/avatar/action/list
Catalogcatalog-itemPOST /service/catalog-item/action/get

All requests are POST with a JSON body (except Catalog create/update which use multipart/form-data).

REST-style routing (Intellect, Knowledge)​

POST /v1/{service}/{action}
ServiceExample
IntellectPOST /v1/intellect/add
KnowledgePOST /v1/knowledge/get

All requests are POST with a JSON body.

Common Response Shapes​

Every action returns JSON. Successful responses return the resource directly:

{
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "displayName": "My Assistant",
  ...
}

List actions return a paginated wrapper:

{
  "objects": [ ... ],
  "totalCount": 42
}

Pagination​

All list actions accept a pager object:

{
  "pager": {
    "offset": 0,
    "limit": 30
  }
}
  • Default: offset: 0, limit: 30
  • Maximum limit: 30 items per page
  • Use offset to page through results: page 2 = offset: 30, page 3 = offset: 60
🔍 Under the hood: Why action-based routing?

Kaltura's APIs use a service/action pattern (rather than REST resource/method) to maintain consistency across hundreds of API services in the Kaltura ecosystem. Every service exposes named "actions" via POST, which makes it easier to add new operations without changing URL structures.

This means:

  • All calls are POST — no GET, PUT, PATCH, DELETE
  • The action name (create, list, get, etc.) is part of the URL path, not derived from the HTTP method
  • Request parameters live in the JSON body, not query strings

Next Steps​

Ready to build? Here's where to go: