Enriching Conversations with Metadata via SFTP

Last updated: July 14, 2026

Clients can attach additional metadata to your conversations in LevelAI by uploading CSV files to a dedicated SFTP location. This is useful when certain attributes — such as customer tier, order value, disposition codes, or campaign details — are not available at the time of ingestion but become available later in your systems or through other systems.

How It Works

You upload a CSV file to Level AI SFTP location folder. Each row in the file corresponds to a single conversation, and each column (other than the identifier column) is a metadata field you want to populate on that conversation. Level AI matches each row to the correct conversation using an identifier column, then attaches the remaining columns as metadata.

Prerequisites

  • SFTP server details and credentials: These will be shared with you by your Technical Account Manager (TAM). Please reach out to your TAM if you have not received them.

  • A designated upload folder: You can upload the files to a unique folder and configure the metadata enrichment from there on

File Requirements

Identifier Column (Required)

Every file must include exactly one identifier column that Level AI uses to match rows to conversations. This can be either:

  1. Level AI Conversation ID — the unique ID assigned by Level AI to each conversation,

or

  1. A custom field you already send us — such as Session ID, Call ID, or any other unique identifier that is part of your existing integration with Level AI.

If you plan to use a custom field as the identifier, please confirm the exact field name before your first upload so we can configure the matching correctly.

Metadata Columns

  • All remaining columns are treated as metadata fields to be added to the matched conversation.

  • Column headers become the metadata field names, so use clear, consistent names (e.g., customer_tier, order_value, disposition).

  • Keep column names consistent across uploads. Changing a column name will create a new metadata field rather than updating the existing one.

Example Files

Two sample files are provided below to illustrate the expected structure. You can use them as templates for your own uploads.

Example 1: Using a custom field as the identifier

File: metadata_example_custom_field.csv

Here, session_id is a custom field you already send to Level AI as part of your integration. The remaining three columns (customer_tier, order_value, disposition) will be added as metadata on the matched conversations.

Example 2: Using the Level AI Conversation ID as the identifier

File: metadata_example_levelai_id.csv

Here, levelai_conversation_id is the unique ID assigned by Level AI. The remaining columns (campaign_name, csat_score, refund_issued) will be added as metadata.

Note

  • Timing of uploads: Metadata files should be uploaded only after the corresponding conversations have been ingested into Level AI. If a row references a conversation that has not yet been ingested, it will be skipped and will not be retried automatically — you will need to re-upload that row once the conversation is available in Level AI.

  • Unique identifiers: Ensure the identifier value in each row is unique and matches exactly what exists in Level AI. Rows that cannot be matched to a conversation will be skipped.

  • Incremental uploads: Only include rows for conversations you want to update. There is no need to re-send previously uploaded data.

Frequently Asked Questions

What happens if a row doesn't match any conversation? Unmatched rows are skipped. The rest of the file is still processed normally.

Can I update metadata that was already sent? Yes. Uploading a new file with the same identifier will update the metadata fields included in that file.

Where will this metadata appear? Enriched metadata appears on the conversation in Level AI conversation details page in the Case details section