Skip to main content
Manage location-specific content (Build > Variant management) for multi-site deployments. Each variant stores attributes like phone numbers, addresses, and hours. variant-1

​
Prerequisites

  1. Ensure you have admin access to Build > Variant management in your PolyAI agent.
  2. Set up Managed Topics aligned with your multi-site configuration goals.
  3. Understand how to use functions in your agent.
To bulk update or create variants, use the CSV import guide.

​
Key capabilities

​
Multi-site configurations

Use variant management to manage multiple locations within the same agent, ensuring responses are location-specific. Attributes such as phone numbers and opening hours can be stored per variant, enabling dynamic customer interactions.

​
Managed Topics integration

Attributes defined in variant management are accessible in your Managed Topics rules, templates, and actions. For example, you can use ${variant_foo} to populate responses dynamically with location-specific information.

​
Flexible routing

Set up routing in the start function to direct users to the appropriate variant. For voice, route based on phone numbers or SIP headers; for webchat, use URL parameters or session data. Variants can also be used to tailor SMS messages dynamically.

​
Advanced functions

Use the conv.variant object to retrieve variant attributes during conversations or to make decisions based on variant data. Use functions to set, retrieve, or act on variant-specific attributes.

​
Testing and troubleshooting

You can now select a specific variant when making in-app test calls. The variant selector appears in the Call configuration section when variants exist for your project. This allows you to test variant-specific behavior directly in Agent Studio without manual function workarounds.
The first variant created will be used as the default for the agent. If this variant is deleted, the next variant in the list will automatically become the new default. At present, there is no UI-based option to manually set a specific variant as the default.

​
Real-life use case

A hotel chain with multiple branches worldwide uses Variant Management to manage its agent. Each branch (e.g., “London” and “New York”) has a variant configured with attributes like phone numbers, addresses, and check-in hours. When a guest contacts the agent, the branch is identified based on the user’s context—phone number for voice, URL parameters for webchat—and the response is tailored accordingly.

​
Variants and attributes

  • Use the (+) plus sign to add a new attribute.
  • Use the Add variant button to add a new variant.
variant-2

​
Setting up a new variant

variant-3 To configure variants:
  1. Open the Variant Management tab in your agent.
  2. Add a new variant and provide a name, such as “London” or “Tokyo.”
  3. Save your configuration.
variant-4

​
Setting up a new attribute

variant-5 Define attributes for the variant, such as:
  • Phone numbers
  • Address
  • Operating hours
  • Menu
  • Accessibility
variant-6

​
Default variant handling

By default, the first variant in the list is used unless otherwise specified. If a variant needs to be changed programmatically, use the conv.set_variant() method in your start function. Example: 
if not conv.variant:
    conv.set_variant("default_variant_name")

​
Using variants in SMS templates

Main article: SMS To include variants dynamically in SMS messages, use the syntax ${variant_attribute}. For example:
  • ${variant_phone_number} dynamically includes the phone number associated with the active variant.

​
Testing variants

​
In-app calling

When making test calls from Agent Studio, you can select a specific variant from the Call configuration section. The variant selector only appears when variants exist for your project. Call settings are grouped in a collapsible panel for easier navigation.

​
In chat

For webchat testing, you can set variants manually in the start function: 
if not conv.callee_number:
    conv.set_variant("London")
Alternatively, create functions such as set_variant1, set_variant2 to switch variants during testing.

​
Advanced: Accessing variants in functions

This example demonstrates how to dynamically assign variants based on user context. Using the conv.variant object, you can retrieve and set the appropriate variant to ensure responses are tailored to the user’s location or context.

​
Voice example (phone number-based)

def start_function(conv: Conversation):
    phone_numbers = {
        variant.phone_number: variant_name
        for variant_name, variant in conv.variants.items()
    }
    if conv.callee_number:
        conv.set_variant(phone_numbers[conv.callee_number])

​
Webchat example (URL parameter-based)

For webchat interactions, you can use URL parameters or session data to determine the variant: 
def start_function(conv: Conversation):
    # Get variant from webchat metadata (e.g., URL parameter)
    location = conv.metadata.get("location")
    if location and location in conv.variants:
        conv.set_variant(location)