Configuration

When you create a session via WebRTC or WebSockets, you send a request body that configures the agent for that session. This page documents every field in that configuration.

Agent configuration

These top-level fields define which companion, resources, and metadata to use for the session.

Attaching resources

The functions, faqCollections, and knowledgeBaseId fields let you wire resources to a session at creation time. These resources must already exist in your project — create them via the Tools, FAQs, and Knowledge endpoints first.

{
  "companionId": "comp_abc123",
  "functions": ["fn_weather", "fn_booking"],
  "faqCollections": ["faqc_returns", "faqc_shipping"],
  "knowledgeBaseId": "col_product_docs"
}

You can attach multiple tools and FAQ collections to a single session. Only one knowledge collection is supported per session.

Language

The language field sets the language for the session. Use plain language names — English, Spanish, French, German, etc. — not ISO codes.

{
  "companionId": "comp_abc123",
  "language": "Spanish"
}

Memory and user identity

When you pass an externalClientId, the Companion API enables memory for that session. The companion remembers what was said and can pick up the conversation in future sessions with the same user.

{
  "externalClientId": "user_12345"
}

Memory is scoped to a companion + external client ID pair. This means:

• If the same user (user_12345) talks to a different companion, memory starts fresh — conversations are not shared across companions.
• If you change the externalClientId for the same user, the companion treats them as a new person with no history.
• If the same externalClientId connects to the same companion again, the companion recalls previous conversations and can reference them.

Use a stable, unique identifier from your system — such as a user ID or account ID — so memory persists reliably across sessions.

User context

The externalClientProfile field lets you pass structured information about the end user into the session. The companion can reference this data during the conversation to personalize its responses.

{
  "externalClientId": "user_12345",
  "externalClientProfile": {
    "name": "Jane",
    "plan": "premium",
    "company": "Acme Corp"
  }
}

The object is unstructured — include any fields that would help the companion tailor its behavior. For example, passing the user's name lets the companion greet them personally, and passing their subscription tier lets it adjust recommendations accordingly.

Tagging sessions

Tags are string-to-string key-value pairs attached to the session for your own tracking:

{
  "tags": {
    "source": "ios-app",
    "experiment": "v2-onboarding",
    "env": "production"
  }
}

Tag keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

Tags are stored on the session and returned when you retrieve session details. Use them for filtering, analytics, or debugging.

Provider configuration

The providerConfig object controls the voice, video, and model behavior for the session.

Settings

The providerConfig.settings object lets you fine-tune the model and audio pipeline:

Turn detection

The turnDetection object configures Voice Activity Detection (VAD) — how the system decides when the user has started and stopped speaking. This directly affects interruption behavior and response timing.

{
  "providerConfig": {
    "settings": {
      "turnDetection": {
        "threshold": 0.9,
        "prefix_padding_ms": 400,
        "silence_duration_ms": 500
      }
    }
  }
}

Pass an empty object {} to use the provider's default VAD settings.

Noise reduction

The noiseReduction object accepts a single type field:

{
  "providerConfig": {
    "settings": {
      "noiseReduction": {
        "type": "nearField"
      }
    }
  }
}