Overview

Define structured config forms and real-time agent settings.

The Configuration Builder allows builders to define JSON schemas that generate structured config forms. These forms let managers safely update settings—like opening hours or toggle flags—across environments.

How it works

Configuration Builder separates structure (schema) from values (data).

Tab	Purpose
Schema	Define what fields exist (like opening hours, toggles)
Data	Fill in the environment-specific values

The schema ensures consistent structure and validation. The data defines what the agent uses at runtime.

The configuration builder is not tied to the main publish lifecycle.

The builder sits outside the agent’s draft/publish system, so changes to schema and values take effect immediately.

This means:

• An empty config file that receives a schema will instantly expose real-time fields to fill.
• Any changes to schema or data will reflect immediately across all environments.

Step-by-step

1. Create a schema

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” and “description” values—these labels will be visible in the real-time UI.

{
  "title": "Assistant Settings",
  "description": "Set call handling parameters for this assistant",
  "type": "object",
  "properties": {
    "opening_hours": {
      "type": "string",
      "title": "Opening Hours",
      "description": "Hours during which the assistant 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}$"
    }
  }
}

2. (Optional) Add environment-specific 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 (Draft, Pre-release, Live) maintains its own data.

{
  "opening_hours": "Mon–Fri, 9am to 6pm",
  "after_hours_enabled": true,
  "fallback_number": "[phone]"
}

Fields can be left blank unless marked required.

3. Publish

You do not need to publish your assistant 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

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.

Best practices

Design schemas for clarity. Labels and descriptions help non-technical users.

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.

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.

Need help? Contact [e-mail].