Configuration

RTVI bots expose services and service configuration options to clients.

Your client config can be set when initializing your bot or at runtime.

A typical bot config, in JSON, might look like this:

[
  {
    "service": "vad",
    "options": [{ "name": "params", "value": { "stop_secs": 3.0 } }]
  },
  {
    "service": "tts",
    "options": [
      { "name": "voice", "value": "79a125e8-cd45-4c13-8a67-188112f4dd22" }
    ]
  },
  {
    "service": "llm",
    "options": [
      {
        "name": "model",
        "value": "meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo"
      },
      {
        "name": "initial_messages",
        "value": [
          {
            "role": "system",
            "content": `You are a assistant called ExampleBot. You can ask me anything.
              Keep responses brief and legible.
              Your responses will converted to audio. Please do not include any special characters in your response other than '!' or '?'.
              Start by briefly introducing yourself.`
          }
        ]
      },
      { "name": "run_on_config", "value": true }
    ]
  }
]

​

Client-side configuration

You can pass a config into the RTVIClient params properties on the constructor. Passing a config from the client is optional. A bot will always start with a default config if no config is passed from the client. Some RTVI implementations may also choose to ignore configs passed from the client, for security or other reasons.

​

Working with the RTVI config array

RTVI config is defined as a list because order matters; configurations are applied sequentially on your bot pipeline. For example, to configure a TTS service with a new voice and an LLM service with new prompting, specify the TTS first to ensure the voice is applied before the prompting. This ordering principle also applies to service options, ensuring deterministic outcomes for all RTVI implementations.

RTVI clients instances expose various methods for working with config arrays which you can read about here.

​

Server-side configuration

Platforms implementing RTVI on the server side will generally provide a method for passing a config into a connect endpoint. It’s a good practice to use the same config format for both client-side and server-side configuration, though of course this choice is left up to the implementor of the server-side APIs.

​

Setting service API keys

It’s important to note that API keys should never be included in configuration messages from or to clients. Clients shouldn’t have access to API keys at all.

Platforms implementing RTVI should use a separate mechanism for passing API keys to a bot. A typical approach is to connect to a bot with a larger, “meta config” that includes API keys, a list of services the bot should instantiate, the client-visible bot configuration, and perhaps other fields like the maximum session duration.

For example:

const bot_connect_rest_api_payload = {
  api_keys: api_keys_map_for_env
  max_duration: duration_in_seconds
  services: [{ llm: "together", tts: "cartesia" }]
  config: config_passed_from_client
};