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 VoiceClient 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.

​

Getting the bot config

​

getBotConfig()

Returns a Promise that resolves with the bot’s current configuration.

config = voiceClient.getBotConfig()

​

Updating the bot config

​

updateConfig()

Update the bot’s config. Passing a partial config is fine. Only the individual options that are passed to the updateConfig() call will be updated. You can omit any services you don’t want to make changes to. You can omit any options within a service that you don’t want to change.

Returns a Promise that resolves with the full updated configuration.

new_config = voiceClient.updateConfig([
  { service: "vad", options:[{stop_secs: 0.5}] }
])

​

Retrieving available config options

​

describeConfig()

Get the available config options for the bot the client is connected to.

Returns a Promise that resolve’s with the bot’s configuration description.

configuration_metadescription = await voiceClient.describeConfig()

​

Server-side configuration

Platforms implementing RTVI on the server side will generally provide a method for passing a config into a “start” method. 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 start 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_start_rest_api_payload = {
  api_keys: api_keys_map_for_env
  bot_profile: "a_bot_version_and_capabilities_string",
  max_duration: duration_in_seconds
  services: [{ llm: "together", tts: "cartesia" }]
  config: config_passed_from_client
};