> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botbrains.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversation Attributes

> Add structured fields to every conversation that people set or AI fills, then filter, score, and monitor by them

export const feature_0 = "conversation attributes"

export const note_0 = undefined

<Warning>
  [ServiceLens](/concepts/servicelens), which includes {feature_0}, is currently in beta and available per project. Contact [support@botbrains.io](mailto:support@botbrains.io) to turn it on for your project. {note_0}
</Warning>

Conversation attributes add structured fields to every conversation, such as the product a customer asks about, whether they asked for a refund, or how frustrated they are. People set them by hand, integrations set them through the API, or AI fills them from the transcript. Unlike free-form [labels](/concepts/labels), each attribute has a type and defined values, so you can filter conversations by it, combine attributes into [scorecards](/concepts/scorecards), and flag conversations with [monitors](/concepts/monitors). You manage them on the [conversation attributes page](https://platform.botbrains.io/~/conversation-attributes).

## Attribute Types

Click **New attribute** and choose **Create your own** or a [template](#templates-and-built-in-attributes). Each attribute has a label, a type, a key, and an optional description. The key forms the identifier `conversation.attributes.<key>`. You can't change the key or the type after you create the attribute.

| Type | Holds | AI can fill it |
| - | - | - |
| **Yes / No** | True or false | Yes |
| **Single select** | One option from a list | Yes |
| **Multi select** | Any number of options from a list | Yes |
| **Integer** | A whole number, optionally on a scale of levels | Yes, with 2–10 levels |
| **Decimal** | A decimal number, optionally on a scale of levels | Yes, with 2–10 levels |
| **Text** | Free text, up to 2,000 characters | No |
| **Date** | A calendar date | No |
| **Scorecard** | A 0–100 score computed from other attributes | Computed, see [Scorecards](/concepts/scorecards) |

**Levels.** For the AI to fill a number, add 2 to 10 levels in increasing or decreasing order, each with an optional label and description. An integer gets the most likely level, a decimal the probability-weighted average.

**Keys.** A key uses lowercase letters, digits, and underscores, starts with a letter, and must be unique in the project. You can't use built-in names such as `topic` or `status`, or other reserved names such as `labels`, `size`, or `first`. Template keys such as `sentiment` belong to their templates, so install the template instead. A deleted attribute's key becomes free once botBrains has removed its values.

**Deleting.** You can't delete an attribute while a scorecard, a selection, or a monitor uses it. Deleting removes its values from all conversations.

## How AI Fills Attributes

The fill mode decides who sets the value and when.

| Fill mode | Behavior |
| - | - |
| **Manual** | People set the value on the conversation, integrations through the API |
| **On demand** | The AI fills it only when you run a backfill or re-evaluate a conversation |
| **After the conversation** | The AI fills it once the conversation has been quiet for about 10 minutes. Best for outcomes and quality signals |
| **Before every reply** | The AI fills it on each new customer message, before the AI agent replies, so [guidance](/concepts/guidance), [procedures](/concepts/procedures), and Liquid templates can react in the same turn |

**Prompt.** Tell the AI what to decide in up to 256 characters, such as "Did the customer ask for a refund?" The AI also reads the label, the description, and the option descriptions, so describe each option clearly.

**Selection.** Under **Fill only for conversations matching**, limit the attribute to a segment such as voice calls or Zendesk tickets. Leave it empty to fill every conversation. A selection can use other AI attributes that fill earlier (before every reply, then after the conversation, then on demand), but no scorecards.

**Test before saving.** Click **Run test** to let the AI fill the attribute for the five most recent matching conversations. You see each value with its confidence, and botBrains stores nothing.

**Before every reply.** The AI fills these attributes after [triggers](/concepts/triggers) run, so triggers still see the previous values. Each fill adds a little latency. If it fails or takes longer than 4 seconds, the AI agent replies without the new value, and the AI fills it later. Voice calls get these values after the call instead.

**Values set by hand.** The AI never overwrites a value that a person set or cleared. Only a [backfill](#backfill-existing-conversations) with **Overwrite values set by people** switched on replaces it.

The AI skips hidden conversations and conversations without a customer message.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/botbrains/images/conversation-attributes/attribute-editor.png" alt="Attribute editor showing the fill mode options, the prompt, the selection filter and test results with values and confidence for five recent conversations" data-generation-prompt="Use a project with ServiceLens turned on and a custom Single select attribute filled 'After the conversation', for example 'Product' with 3-4 options that each have a description, and enough recent conversations. Navigate to platform.botbrains.io/~/conversation-attributes and click that attribute to open the editor sheet on the right. Click 'Run test' and wait until the 'Test on recent conversations' table shows 5 conversations with values and confidence. Scroll the sheet so the 'Fill mode' cards, the 'Prompt' field, 'Fill only for conversations matching' and the test results are visible together. Use a 1920x1080 viewport, collapse the sidebar, and crop to the sheet." />

<Note>
  A project can have up to 200 attributes. Together, its AI-filled attributes can ask at most 150 questions per conversation, and at most 20 before every reply. A yes/no, single select, or number attribute asks one question, and a multi select asks one per option.
</Note>

## Templates and Built-in Attributes

**Templates** add ready-made AI attributes, such as sentiment or the [CX Score](/concepts/scorecards#cx-score), with prompts that botBrains maintains. Click **New attribute** and pick a template. On a managed attribute, you can change the label, the fill mode, the selection, and the **Use in templates** switch, but not the prompt or the options. Templates fill new conversations automatically. Run a backfill to fill existing ones.

**Built-in attributes** appear under **Default** and expose data every conversation already has. You can't edit their definitions or insert them with Liquid, but [scorecards](/concepts/scorecards#how-scorecards-work) can score Status, Topic, and CSAT Rating.

| Identifier | Label | Values |
| - | - | - |
| `conversation.topic` | Topic | Your project's [topics](/concepts/topics) |
| `conversation.status` | Status | Resolved, Unresolved, Escalated |
| `conversation.rating` | CSAT Rating | 1–5 |
| `conversation.channel` | Channel | Browser, App, Zendesk, WhatsApp, Slack, Salesforce, Voice, API |
| `conversation.involvement` | AI Involvement | Autonomous, Public, Private, Not involved |
| `conversation.length` | Customer Messages | Number of customer messages |

## Backfill Existing Conversations

AI attributes fill new conversations on their own. To fill conversations from before you created the attribute, or an on-demand attribute, open it and click **Backfill**:

1. Choose when the last message happened. The default is the last 30 days, with presets for 7, 30, or 90 days, or all time.
2. Optionally narrow the scope with conversation filters.
3. Click **Check scope** to see how many conversations match, then **Start backfill**.

The backfill skips hidden conversations and conversations outside the attribute's selection. It works newest first, covers up to 10,000 conversations per run, and each attribute runs one backfill at a time. It re-evaluates every conversation in scope, including ones that already have an AI value. Values that people set or cleared stay unless you switch on **Overwrite values set by people**. You can't backfill manual attributes.

To refill a single conversation, click **Re-evaluate** in the **Attributes** section of its details panel. It keeps values set by hand.

## Values on a Conversation

Open any [conversation](https://platform.botbrains.io/~/conversations) to see the **Attributes** and **Scorecards** sections in its details panel. Built-in attributes don't appear there. Edit a value in place or clear it. Hover the icon next to a value to see where it came from:

| Source | What the icon says |
| - | - |
| **AI** | **Filled by AI** with the confidence, for example 92%. The icon turns amber below 50% |
| **Person** | **Set by hand** or **Cleared by hand**. The AI leaves these values alone |
| **AI without an answer** | The AI couldn't determine a value on its last run |

<img src="https://mintlify.s3.us-west-1.amazonaws.com/botbrains/images/conversation-attributes/conversation-sidebar.png" alt="Conversation details panel with the Attributes section showing AI-filled values with confidence icons and a value set by hand, and the Scorecards section with a score pill" data-generation-prompt="Use a project with ServiceLens turned on and the Sentiment, Urgency, Frustration and CX Score templates installed plus one custom attribute. Navigate to platform.botbrains.io/~/conversations and open a conversation with at least 2 customer messages where the AI filled these attributes and one custom value was set by hand. Scroll the right details panel to the 'Attributes' and 'Scorecards' sections. Capture both sections with the AI and hand-set icons next to the values and the CX Score pill visible. No tooltips or cursor. Use a 1920x1080 viewport, collapse the sidebar, and crop to the details panel." />

## Where You Use Attributes

| Where | What you can do |
| - | - |
| [Conversation list](https://platform.botbrains.io/~/conversations) | Pick a custom or managed attribute, or a scorecard, from the **Filter** menu |
| [Audiences](/concepts/audiences) | Use attributes in the audience builder, guidance conditions, procedure branches, and [triggers](/concepts/triggers) |
| Messages, [guidance](/concepts/guidance#personalize-with-liquid), and tool parameters | Insert `{{ conversation.attributes.<key> }}` with Liquid for attributes with **Use in templates** switched on |
| [Scorecards](/concepts/scorecards) | Weight yes/no, single select, and number attributes into a 0–100 score |
| [Monitors](/concepts/monitors) | Flag conversations that match attribute filters or fail a scorecard |
| [Data export](/concepts/data-export#attributes) | Export values and scores with conversations as JSONL, CSV, Excel, or Markdown, all at once or one attribute at a time |

### Filter by Attributes

| Operator | Types | Matches |
| - | - | - |
| `eq`, `in`, `neq`, `nin`, `exists` | All types | Equal to, any of, not equal to, none of, set or unset |
| `gt`, `gte`, `lt`, `lte` | Integer, Decimal, Date, Scorecard | Greater or less than |
| `contains`, `ncontains` | Text, Multi select | Text: contains the text, ignoring case. Multi select: has all values |

A conversation must match every operator you set on an attribute, and any one value within an operator. `neq`, `nin`, and `ncontains` also match conversations without a value. The conversation list keeps the conditions as JSON in the `attributes` URL parameter, so you can share a filtered view:

```text theme={null}
https://platform.botbrains.io/~/conversations?attributes={"sentiment":{"in":["negative"]}}
```

In the query string, the conversations API accepts `attributes[<key>]=<value>`, which you can repeat and which means `in`, and `attributes[<key>][<operator>]=<value>`. In a JSON request body, such as an [export](/concepts/data-export#attributes), send the conditions under `attributes`. Every operator takes a list of values as text, except `exists`, which takes `true` or `false`:

```json theme={null}
{"attributes": {"sentiment": {"in": ["negative"]}, "cx_score": {"lt": ["50"]}, "frustration_triggers": {"exists": true}}}
```

## Permissions

To create, test, backfill, or delete attributes, you need a role that can edit them, such as Project Contributor. Project Members can set values and re-evaluate conversations. See [Permissions](/concepts/servicelens#permissions) for every role.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.