Skip to main content
Schema definition requires Python familiarity. A developer defines the configuration schema (fields, types, defaults). Once the schema is set up, non-technical users can update values in the Data tab without writing code.
Use the Configuration Builder when non-technical managers need to update agent settings — opening hours, feature toggles, fallback phone numbers — without publishing a new version. Without this, every operational change requires a developer to edit code and promote through the deployment pipeline. The Configuration Builder is found under Build > Configuration Builder.

​
How it works

Configuration Builder separates structure (schema) from values (data).
TabPurpose
SchemaDefine what fields exist (like opening hours, toggles)
DataFill in the environment-specific values
The schema ensures consistent structure and validation. The data defines what the agent uses at runtime.
Configuration builder UI with schema/data tabs
The configuration builder is not tied to the main publish lifecycle.The builder sits outside the agent’s draft/publish system, so data value changes take effect immediately within each environment. Changes to Live values affect all active calls instantly — verify values in Sandbox or Pre-release first.This means:
  • An empty config file that receives a schema will instantly expose real-time fields to fill.
  • Data changes take effect immediately within the environment where they are made.
  • Schemas must be created separately in each environment (they do not propagate automatically).

​
Two tasks: schema definition and value entry

This page covers both schema definition (requires Python familiarity) and value entry (UI only). If you only need to fill in runtime values, skip to step 2. For the full technical setup including Python code, continue reading from the top.
The Configuration Builder serves two different tasks:
  • Schema definition — Define the structure and wire up conv.real_time_config in functions. This requires Python familiarity and is done in the Configuration Builder tab.
  • Value entry — Fill in runtime values via the Real Time Configuration UI. No code required.
These tasks may be performed by different people with different access levels. For customers who self-manage their configuration (for example, updating settings across many locations), the distinction matters — value entry is done through the UI without touching the schema definition.

​
Step-by-step

​
1. Create a schema

Live config UI showing example values
In Configuration Builder → Schema, define the fields your manager should configure. For example:
  • A text field for opening_hours
  • A toggle for after_hours_enabled
  • A validated phone number for fallback_number
These fields are written in JSON Schema format. The schema drives the form layout in the next step.
Use clear “title” values—these labels will be visible in the real-time UI.
{
  "title": "Agent Settings",
  "description": "Set call handling parameters for this agent",
  "type": "object",
  "properties": {
    "opening_hours": {
      "type": "string",
      "title": "Opening Hours",
      "description": "Hours during which the agent should be available"
    },
    "after_hours_enabled": {
      "type": "boolean",
      "title": "After Hours Message",
      "description": "Enable this toggle to play a message outside business hours"
    },
    "fallback_number": {
      "type": "string",
      "title": "Fallback Contact Number",
      "description": "Phone number to call if no agent is available",
      "pattern": "^\\+44\\d{10}$"
    }
  }
}
Boolean toggles are also useful as feature flags—enabling or disabling capabilities in live environments without a deployment. For example, you could add a transfer_enabled toggle to control whether the agent offers call transfers.
The schema must be created separately in each environment. If you build a schema in Sandbox, it does not automatically exist in Live. You need to set up the schema in every environment where you want the configuration UI to appear.

​
2. (Optional) Add environment-specific values

Live config UI showing example values
Once a schema is saved, the Real Time Configuration UI will appear automatically, even if no values are set. You can, however, populate values manually, at any time, in the Data tab, where each environment (Sandbox, Pre-release, Live) maintains its own data. 
{
  "opening_hours": "Mon–Fri, 9am to 6pm",
  "after_hours_enabled": true,
  "fallback_number": "+442071234567"
}
Fields can be left blank unless marked required.

​
3. Publish

You do not need to publish your agent for config changes to take effect. However, publishing may still be useful if you want to include these changes in a documented release. Once your schema is added, the Real Time Configuration tab becomes available for managers to enter values for:
  • Draft and Sandbox
  • Pre-release
  • Live
Live config UI showing example values

​
4. Add the read config in your functions

Use the conv.real_time_config helper to read real-time values. 
config = conv.real_time_config
hours = config.get("opening_hours")
after_hours = config.get("after_hours_enabled")
fallback = config.get("fallback_number")

if after_hours:
    conv.say("We're currently closed. Please call back during business hours.")
    conv.transfer_call(fallback)
All values are returned as a dictionary. Use .get("key") to safely access fields.

​
Working with nested and complex schemas

The Configuration Builder supports arrays and nested objects in addition to flat fields. This is useful for projects that manage per-site settings, employee directories, or structured data. For example, a schema might define an array of site-specific hours: 
{
  "type": "object",
  "properties": {
    "site_hours": {
      "type": "array",
      "title": "Site hours",
      "items": {
        "type": "object",
        "properties": {
          "site_name": { "type": "string", "title": "Site name" },
          "hours": { "type": "string", "title": "Opening hours" }
        }
      }
    }
  }
}
To access nested values in your functions, index into the structure: 
sites = conv.real_time_config.get("site_hours", [])
first_site_hours = sites[0]["hours"] if sites else None

​
Programmatic management via API

For deployments managing configuration across many locations, you can also manage real-time config programmatically through the API. The following endpoints are available:
MethodEndpointDescription
GET/real-time-configsList all real-time configs
GET/real-time-configs/:clientEnvGet config for a specific environment
PATCH/real-time-configs/:clientEnv/variablesUpdate config variables
PUT/real-time-configs/:clientEnv/schemaUpdate the config schema
This is especially useful when customers need to update settings themselves at scale, rather than editing values manually in the UI.

​
Best practices

Design schemas for clarity. Labels help non-technical users navigate the configuration UI. Validate critical fields (like phone numbers) with regex. Test behavior across all environments before deploying to Live. Keep track of which flows and functions use which configuration fields. Set up the schema in every environment where you need the config UI — schemas are not shared across environments. Standard JSON Schema features including arrays, nested objects, and validation patterns are supported.

​
What happens if the schema changes?

If the schema is edited in a way that invalidates existing data, the system will prevent publishing until all environments are valid again.

​
Can each environment have different values?

Yes. For example, you can test one phone number in pre-release while using a different one in live.
Last modified on March 31, 2026