Skip to main content

Variant attributes provide per-variant configuration so prompts and behavior can change by location, environment, or tenant without separate code or deployments.

At runtime, the platform selects a variant, and the agent reads the attributes associated with that variant.

​
Location

Variant attributes are defined in: 
config/variant_attributes.yaml

​
What the file contains

The file has two top-level keys:
  • variants
  • attributes

​
Variants

The variants section defines the available variants. Each variant includes:
FieldRequiredDescription
nameYesUnique identifier for the variant
is_defaultNoMarks the fallback variant used when no variant is resolved at runtime
Exactly one variant should have is_default: true.

​
Attributes

The attributes section defines the values that vary by variant. Each attribute includes:
FieldDescription
nameAttribute identifier, ideally in snake_case
valuesMap from variant name to string value
Every attribute must provide a value for every defined variant, even if that value is an empty string.

​
Example

variants:
  - name: new_york
    is_default: true
  - name: london
  - name: tokyo

attributes:
  - name: office_phone
    values:
      new_york: "+12125551234"
      london: "+442071234567"
      tokyo: "+81312345678"

  - name: office_hours
    values:
      new_york: "9am - 5pm EST"
      london: "9am - 5pm GMT"
      tokyo: "9am - 5pm JST"

  - name: greeting_name
    values:
      new_york: "New York Office"
      london: "London Office"
      tokyo: "Tokyo Office"

  - name: custom_disclaimer
    values:
      new_york: |-
        This call is recorded for quality assurance.
        You may request a copy of this recording.
      london: |-
        This call may be recorded in accordance with UK regulations.
      tokyo: ""

​
Why variants are useful

Variants let one agent behave differently in different contexts without duplicating the whole project.

Branding

Change names, labels, or brand-specific wording.

Contact details

Swap phone numbers, addresses, and office hours.

Environment-specific behavior

Store values such as region codes, timezones, or flags.

Multi-tenant setups

Reuse the same logic with tenant-specific values.

​
Using variant attributes in prompts and resource files

Use {{attr:attribute_name}} in supported text fields such as:
  • flow step prompts
  • topic actions
  • rules
  • greeting messages
  • disclaimer messages
  • personality custom
  • role custom

​
Example

Our office number is {{attr:office_phone}}. We're open {{attr:office_hours}}.

​
Using variant attributes in Python

In code, variant values are read from conv.variant: 
phone = conv.variant.office_phone
hours = conv.variant.office_hours
Use the same attribute names that are defined in variant_attributes.yaml.

​
Typical attribute types

Common uses include:
CategoryExamples
Brandinggreeting name, company name
Contactphone numbers, addresses, office hours
IDslocation ID, region code
Feature flags"True" / "False" strings, checked in Python
URLsportal links, payment links
Environmenttimezone, is_live

​
Important formatting notes

  • variant names with special characters should be quoted
  • multi-line values should use |-
  • every variant must have a value for every attribute
Missing values will fail validationIf a variant is missing from an attribute’s values map, validation will fail.

​
Best practices

  • keep variant names stable over time
  • set exactly one default variant
  • provide a value or "" for every variant in every attribute
  • prefer {{attr:...}} over hard-coded strings when values vary by location or environment
  • use multi-line YAML for disclaimers, instructions, or longer text values

Topics

See how variant attributes are used in topic actions.

Voice settings

Use variant attributes in greetings and disclaimers.

Variant management (platform)

How variants are routed at runtime — SIP header routing, default selection, and conv.variant access.
Last modified on July 9, 2026