CSV imports

Bulk import and update variants using CSV files

CSV imports allow you to create or update multiple variants at once. This is useful for managing multi-site deployments or making bulk changes to variant attributes.

Export your current variants

Before importing, export your existing variants to understand the file format:

1. Navigate to Build > Variant management in Agent Studio
2. Click Export CSV
3. Save the file to your local machine

The exported CSV contains all your variants with their attributes and configurations.

Always use the exported file as your starting template. The exported format may use a different delimiter than a standard comma-separated file. If you edit the CSV in a spreadsheet application, re-export it in the same format to avoid import errors.

CSV file format

The CSV file must include these columns:

Column	Required	Description
id	No	Leave empty for new variants. Include existing IDs to update variants.
name	Yes	Unique name for the variant
is_default	Yes	true or false. Only one variant can be default. See note below.
attribute_*	No	Custom attributes (e.g., attribute_phone_number, attribute_address)

Default variant behavior

The is_default field is included in the CSV format but does not control which variant is used as the default. The platform assigns the default variant based on creation order. To control which variant is active for each conversation, use conv.set_variant() in your start function.

Example CSV

id,name,is_default,attribute_phone_number,attribute_opening_hours
,London Bridge,false,[phone],9am-5pm Mon-Fri
,Manchester,false,[phone],9am-6pm Mon-Sat
,Birmingham,true,[phone],24/7

Import process

1. Prepare your CSV

   • Keep column headers exactly as exported
   • Leave id empty for new variants
   • Include id values for variants you want to update
   • Include is_default values as required by the format (see note above)
2. Upload the file

   Navigate to Build > Variant management, click Import CSV, and select your file.

3. Review changes

   The platform shows a diff of what will change. New variants are highlighted and updated fields are shown side-by-side.

4. Confirm import

   Review the diff carefully and click Confirm import. Changes take effect immediately in the current environment.

If you are working in a sandbox environment, changes only apply to sandbox. Promote your sandbox to live when you are ready. See the variants overview for more on testing workflows.

Best practices

• Test in sandbox first - Import to your sandbox environment before production
• Keep a backup - Export before importing to preserve your current state
• Validate data - Check phone numbers, URLs, and other data before importing
• Use consistent naming - Follow a naming convention that scales (e.g., City-Location)
• One default only - Include exactly one variant with is_default=true in your CSV (see note above)

Common use cases

Adding new locations

Export your CSV, add new rows with empty id fields, and import to create new variants.

Updating phone numbers

Export, update the attribute_phone_number column, keep the id values, and import.

Changing default variant

The is_default field does not control the default variant via CSV import. Use conv.set_variant() in your start function for reliable variant routing.

Troubleshooting

Import fails with 'duplicate name' error

Variant names must be unique. Check for duplicate entries in your CSV.

Changes don't appear after import

Refresh the page. If changes still don’t appear, check the import confirmation screen for errors.

Can't set a variant as default

The is_default CSV field does not control the default variant. Use conv.set_variant() in your start function to programmatically set the active variant.

Attribute columns not recognized

Attribute columns must start with attribute_. Check your column headers.

Import succeeds but is_default doesn't apply as expected

The is_default field does not control the default variant. The platform assigns the default based on creation order. Use conv.set_variant() in your start function to control which variant is active for each conversation.

Import fails with 'Error saving your changes'

This can occur when the CSV contains invalid data. Check for:

• Empty variant name fields (every row must have a name value)
• Duplicate variant names
• Malformed attribute values

If the error persists, try importing fewer rows at a time to isolate the problematic entry.

Validation error: 'too_small'

This usually means a row has an empty required field, such as name. Ensure every row in your CSV has a value in all required columns. Remove any blank rows at the end of the file.

Limits

• Maximum 1000 variants per project
• Maximum 50 custom attributes per variant
• CSV file size limit: 10MB

For larger imports or complex migrations, contact your PolyAI representative for assistance.