Real-time config

Let non-technical managers update agent settings without publishing new versions using structured configuration forms.

Use the Configuration Builder to let non-technical managers update agent settings – opening hours, feature toggles, fallback phone numbers – without publishing a new version or writing code. Changes take effect immediately in each environment, so no developer needs to step in.

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.

The Configuration builder is found under Real-time config.

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 enforces 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 Branch and publish workflow, so data value changes take effect immediately within each environment. Changes to Live values affect all active calls instantly – verify values in Sandbox or Staging 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

In Configuration Builder → Schema, define the fields. 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, so you can enable or disable capabilities in Live without publishing a new version. 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

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, Staging, 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 agent for configuration changes to take effect.

Once your schema is added, the Real Time Configuration tab becomes available:

• Sandbox
• Staging
• 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.

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, the Agents API exposes the same real-time config surface the UI uses:

Method	Endpoint	Description
GET	/v1/agents/{agentId}/real-time-configs	List configs across environments
GET	/v1/agents/{agentId}/real-time-configs/{clientEnv}	Get config for a specific environment
PATCH	/v1/agents/{agentId}/real-time-configs/{clientEnv}/variables	Update config variables
PUT	/v1/agents/{agentId}/real-time-configs/{clientEnv}/schema	Update the config schema

This is especially useful when customers need to update settings themselves at scale, rather than editing values manually in the UI.

Example: sync real-time config from an external source of truth

Python

import os, requests

BASE = "https://api.us.poly.ai"
HEADERS = {"x-api-key": os.environ["POLYAI_API_KEY"]}

# Push the latest opening hours from your internal scheduling system
requests.patch(
    f"{BASE}/v1/agents/{AGENT_ID}/real-time-configs/live/variables",
    headers=HEADERS,
    json={
        "variables": {
            "opening_hours": scheduling.get_hours_for_today(),
            "after_hours_enabled": scheduling.is_out_of_hours(),
        }
    },
)

Changes take effect immediately in the target environment. You do not need to publish.

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 publishing 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 Staging while using a different one in Live.

Related pages

Environments

Understand Sandbox, Staging, and Live.

Functions

Access configuration data in your agent logic with conv.real_time_config.

Real-time config endpoints

Manage schema and variables per environment via the Agents API.