Design custom Dimensions

The Dimensions you design for your business are where most of the value comes from. Standard Dimensions give you a baseline, but generic labels like topic and sentiment are rarely specific enough to act on. You don’t need them for a first answer. Once you’ve had one, custom prompts are where most of the value comes from.

In the platform, custom Dimensions are made with Custom Prompts (often just Prompts). Standard Dimensions are System Prompts. The Prompts tab lists every prompt, yours and the standard ones.

You design and save a prompt with the agent, using Prompt Designer: a setting in the agent. Turn it on in the agent’s settings, and the agent can draft, test and save prompts with you. With it off, the agent can talk a prompt through but can’t save it.

What a custom prompt is

A custom prompt is an analytical task you define. It tells the model exactly what to look for in each conversation, and each field in it becomes a new column (a Dimension) in your enriched data.

If the standard Reason asks “What is this conversation about?”, a custom prompt can ask something only your business cares about:

• Did the customer mention a specific product feature?
• Is there a billing dispute in this conversation?
• What stage of the customer journey does this interaction represent?
• How satisfied was the customer with the agent?

Each answer is a column you can filter, cross with every other Dimension, and chart.

A prompt is applied to the sources you choose when you save or backfill it, and you can apply the same prompt to several sources: one prompt can cover your chat, email and survey sources, so the results compare. When you connect a new source later, apply your prompts to it too.

On a live integration, a saved prompt runs every day on new conversations. File uploads, history and conversations you already have need a backfill. See When enrichment runs.

What you need to tell the model

At its simplest, a custom Dimension needs two things:

1. What information to extract: an effort score, a set of categories, a journey stage, a product line.
2. How to classify it: true or false, a list of options, a score, or open-ended text.

When to use one

• Few survey answers. If your CSAT response rate is low, add a predicted CSAT score so every conversation has one.
• Journey stages. Label each support conversation with the stage of the customer journey it belongs to.
• Emerging topics. A Dimension with dynamic labels surfaces new topics and themes as they appear.
• An existing taxonomy. Put your current categories into a category list, and every conversation gets tagged with your own labels.

How a prompt is built

A prompt groups related fields so they run together on each conversation. It has two parts:

• Context: a short description of the data, including who the incoming and outgoing sides are and what your organization does. This is the background the model needs to read the data correctly. See Write the context.
• Fields: the individual tasks. Each has a name, a description of what to extract, and an output type. Each field is one Dimension.

The exact JSON is on the config reference page.

Example: why customers contact support

An e-commerce company wants to know why customers contact support. One prompt with six fields gives it six new Dimensions on every conversation:

Field	What it extracts	Output type
engagement_reason	A concise label for why the customer reached out	Dynamic label
engagement_category	The main topic of the interaction	Fixed category
issue_detected	true if the customer reports a problem or expresses frustration	Boolean
issue_reason	A short description of the issue	Dynamic label
issue_verbatim	The customer’s own words describing the issue	Verbatim quote
csat	Predicted customer satisfaction on a 1 to 5 scale	Score

Output types

These are the five output types used across these docs.

Output type	JSON type	Use it for
Dynamic label	string	Discovery: labels written from what the text says
Fixed category	string with an enum list	Consistent groupings from a list you define
Boolean	boolean	Whether a condition is present
Score	integer	A rating on a defined scale
Verbatim quote	string	The customer’s exact words on a topic

Fields of different types can sit in the same prompt and work together.

Dynamic labels

The model writes a label from what it finds. There is no list, so the output reflects the actual content of the conversation. A contact_reason field might return order tracking inquiry, refund request, product availability question or shipping delay complaint.

Dynamic labels are best for discovery: the model isn’t limited to a list, so it can surface themes you didn’t expect. Ask the agent to group them into broader themes once you see what comes back.

Fixed categories

The model picks one value from a list you define. Use this when you already have a taxonomy or need stable groupings for reporting. For example, engagement_category with billing_and_payments, account_access, product_setup, returns_and_refunds and none_detected.

Every list ends with none_detected for conversations where nothing fits. Add an other value only if you’ll read what lands in it.

Booleans

true or false: is a condition present? issue_detected returns true if the customer reports a problem or expresses frustration, false otherwise.

Booleans often act as gates for other fields: issue_reason and issue_verbatim only need an answer when issue_detected is true. See Conditional fields.

Scores

A whole number on a defined scale, such as predicted CSAT from 1 to 5 (1 = very dissatisfied, 5 = very satisfied) or a satisfaction rating from 1 to 10. Say in the description when to leave the score empty, for example “Leave empty if there is not enough signal”. The model leaves it empty only when the description tells it to, and empty scores keep averages clean. Predicted scores covers scoring in depth.

Verbatim quotes

The model copies the customer’s words that are most relevant to a topic. For example, issue_verbatim quotes what the customer said about their problem, in fewer than 30 words, taken only from the customer’s (incoming) messages.

Verbatims keep the customer’s own language, which makes them useful for reading behind a number and for quoting in a report.

Field blocks: a pattern that repeats

Prompts work best when related fields come in consistent blocks, one block per signal:

Field suffix	Type	What it holds	Example
_detected or _mention	Boolean	Whether the signal is present	issue_detected
_reason	Dynamic label	A short dynamic label for the signal	issue_reason
_verbatim	Verbatim quote	The customer’s own words about it	issue_verbatim
_category	Fixed category	A fixed classification of it	issue_category

Repeat the block for each signal you track: issues, friction points, product mentions, feature requests. Consistent names make the results predictable to query, and the agent can tell at a glance which fields belong together.

Conditional fields

Fields in a block usually depend on their boolean. issue_reason only has an answer when issue_detected is true. When the condition isn’t met, the dependent fields return none_detected, and a dependent score is left empty.

Say this in each dependent field’s description, for example: “If issue_detected is false, return ‘none_detected’.” Then when you filter to conversations where issue_detected is true, every one of them has a real issue_reason and issue_category.

Note

Older Dimension Labs guides told you to return null for an unmet condition. The convention now is none_detected for category and text fields, and an empty value for scores. Don’t use placeholder strings such as N/A or none.

Start from the decision

Write down the question the Dimensions have to answer, and who acts on it. “Which delivery problems make customers cancel, so operations can fix the worst one first” leads to very different Dimensions than “What do customers talk about?”.

Read the data first

We suggest reading at least 100 to 200 records from across the whole file, not just the first page. Note the kinds of records, the shorthand people use, and which signals actually appear. A Dimension for something that never appears in the text will be none_detected everywhere.

Design rules

• One question per Dimension. Don’t fuse two things in one list (“late and damaged”). Make two Dimensions.
• One boolean per product or feature. When you track mentions, give each product or feature its own boolean, so a conversation that mentions two of them is counted for both.
• Categories need an exit. End every list with none_detected, and add an “other” value only if you’ll read what lands in it.
• Pair a judgement with a quote. For anything subjective, such as a complaint reason or a churn risk, add a companion verbatim Dimension that copies the customer’s exact words. It makes every label checkable.
• Write the description as instructions. Say what counts, what doesn’t, and give two or three phrases from your data for each value.
• Name the values the model tends to invent. If you know it will be tempted by neutral or general, write “Do not use neutral; use none_detected.”
• Read only the customer when it matters. In bot and chat transcripts, speaker labels such as “Maya (AI):” can leak into persona or brand Dimensions. Say “ignore speaker labels; score only from the customer’s own words.”
• Mark priority when several apply. For “the single most important reason”, say which reason wins when there are two.
• Text only. Don’t design a Dimension for something already in a column (rating, channel, date). Join that column instead.
• Plan the crosses. Think about which fields you’ll read together. An engagement_category (what the customer is talking about) crossed with an issue_category (what needs to change to fix it) shows patterns neither field shows alone.

Write the context

Every prompt has a context: the instructions sent with every conversation. Put it in this order:

1. What one record is and who wrote it, including who the incoming and outgoing sides are and what your organization does.
2. Any redaction markers the model will see, such as [REDACTED].
3. A glossary of abbreviations and jargon from your data.
4. Common record shapes (an automated message, a one-word answer).
5. Terms that mean two things, and how to tell them apart.
6. Ground rules: use only what the text states, return none_detected when there’s no signal.

Common use cases

Product and feature mentions

Detect when customers mention specific products, features or services. Define each one as its own boolean, so mentions that occur together are each captured.

Issue and friction detection

Find when customers hit a problem, what the problem is, and how to categorize it for whoever fixes it. Combine a boolean with a reason, a verbatim and a root-cause category: the field block above.

Customer journey stage

Label which stage of the customer lifecycle an interaction belongs to, such as onboarding, active use, renewal or churn risk, and watch how topics shift between stages.

Satisfaction and quality scoring

Predict customer satisfaction, agent helpfulness or support quality on a defined scale, then compare across segments, periods and categories. See Predicted scores.

Signals specific to your industry

Compliance mentions in financial services, safety concerns in healthcare, revenue opportunities in sales conversations, competitor mentions in product feedback.

Custom prompts and standard Dimensions

Standard and custom Dimensions run on the same data, and the agent can cross them. Start with the standard set for a baseline, then build custom prompts to go deeper where it matters most. The differences are in the table on What a Dimension is; the one that matters here is that custom prompts are analyzed at session level only.

Getting started

1. Name the objective. Which business questions do you need answered, and which decisions will the Dimensions support?
2. Choose the fields. Decide what to extract: topics, issues, products, scores, verbatims, or a mix.
3. Bring your taxonomy. If your organization already has categories, product lines or classification schemes, use them in your category lists.
4. Write the prompt. Turn on Prompt Designer in the agent’s settings, then describe the Dimensions to the agent, or paste a prompt written to the config reference. The agent drafts the JSON with you.
5. Test and refine. Check it on a varied sample and adjust descriptions, category lists and conditional logic. See Test before you run.
6. Save it. Ask the agent to save the prompt and choose the sources to apply it to. It then appears on the Prompts tab.
7. Backfill it. On the Backfill tab, run it over the conversations you already have. See Backfill.

Your Dimension Labs team can also design prompts with you to fit your sources and goals. Email [email protected].

Worked example: a competitor Dimension on two years of history

A team wants to know how often customers mention a competitor, which one, and why, across two years of support tickets.

1. Get the history in. Upload the two years of tickets under Data Sources > Unstructured data, or send them to /trackhistorical. New tickets come in from a live integration. See Upload a file.

2. Design the block. Turn on Prompt Designer in the agent’s settings and ask the agent to draft one block of four fields. A boolean plus a name field counts every mention and still tells you which competitor:

Field	What it extracts	Output type
competitor_mentioned	true if the customer names or clearly refers to a competitor	Boolean
competitor_name	Which competitor, from your own list: acme, globex, initech, other_competitor, none_detected	Fixed category
competitor_reason	Why the competitor came up, for example cheaper plan elsewhere	Dynamic label
competitor_verbatim	The customer’s exact words about the competitor, at most 30 words	Verbatim quote

The three dependent fields say “If competitor_mentioned is false, return ‘none_detected’.” The competitor names here are examples: use your own list. If a customer often names two competitors and you need both counted, use one boolean per competitor instead of competitor_name.

3. Test it. Ask the agent to label a varied sample: “Pick 40 tickets from across the two years, including some that mention a competitor, and show me how this prompt labels them.” Fix the descriptions and test again. See Test before you run.

4. Save it. Ask the agent to save the prompt and apply it to both sources: the upload with the history and the live integration. It appears on the Prompts tab, and from now on the live integration’s new tickets are enriched with it every day.

5. Backfill the two years. Open the Backfill tab, choose the prompt, choose the history source (and the live source, for the days before you saved the prompt), and set the date range to cover the two years. Start it and watch its status on the tab.

6. Check coverage. When it has finished, ask the agent: “How many tickets from [start date] to today have a value for competitor_mentioned, and how many have none?” If part of the range is missing, backfill that gap. Then read a few competitor_verbatim values to check the labels hold up.