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

# Collect custom ticket fields with your AI agent

> Define the details your AI agent collects when it creates a ticket, and view or edit them on every ticket in the Helpdesk.

Custom fields are the details your AI agent collects from customers when it creates a ticket, such as an order number, a delivery date, or a photo of the damage. You define a field once under **Settings → Custom fields**, add it to a create-ticket action, and the AI agent asks for it during the conversation. The answer lands on the ticket, typed and labeled, where your team can read and edit it.

Fields are shared across an AI agent's Actions. Two create-ticket Actions that both collect *Order number* write to the same field, so tickets look the same no matter which conversation created them. Your team can then filter the inbox, build saved views and run [triggers](https://chatbase.co/docs/user-guides/chatbot/help-desk/triggers.md#custom-field-conditions) on those values, and every field gets its own column in a [ticket export](https://chatbase.co/docs/user-guides/chatbot/help-desk/exporting-tickets.md).

> [!NOTE]
>
> Custom fields are collected only by a create-ticket Action. Tickets from the [Chatbase Live Chat](https://chatbase.co/docs/user-guides/chatbot/actions/chatbase-live-chat.md) Action, tickets a teammate creates in the Helpdesk, and tickets created through the API don't collect fields.

***

## Anatomy of a field

![Custom fields settings listing fields with their labels, instructions and types](https://mintcdn.com/chatbase/o5YBuDZ7CvCUXc-u/user-guides/images/help-desk/custom-fields/fields-tab.png?fit=max\&auto=format\&n=o5YBuDZ7CvCUXc-u\&q=85\&s=bbfc2e4909bca652faf140d105b81340)

| Property | What it does |
| - | - |
| **Internal label** | The name your team sees in the Helpdesk. Unique per AI agent. |
| **Customer-facing label** | The name the AI agent uses with customers when asking for the value. A noun phrase works best: *Refunded order number*, not *What is your order number?* |
| **Type** | Controls what the value can be and how it renders on the ticket. Fixed while the field is in use, see [Archiving fields](#archiving-fields). |
| **Collection instruction** | Optional guidance for the AI agent on how to get the value and what counts as a valid answer, for example *"It starts with SL and has 8 digits."* The AI agent writes its own question from it. |

### Field types

| Type | Holds |
| - | - |
| **Text** | Free text |
| **Number** | A number |
| **Boolean** | A yes or no answer, shown as Yes or No on the ticket |
| **Date** | A calendar date |
| **Email** | An email address. On the email channel, a lone email field is filled from the sender's address without asking. |
| **Image** | A photo the customer uploads |
| **Dropdown** | One of the options you define. The AI agent only offers options that exist, so a Dropdown with no options is not collected. |

*Subject* and *Description* are built in. Every ticket has them, and you can't create a field with either name.

***

## Create a field

![New field sheet with the type row, both labels, a collection instruction and dropdown options](https://mintcdn.com/chatbase/o5YBuDZ7CvCUXc-u/user-guides/images/help-desk/custom-fields/field-editor.png?fit=max\&auto=format\&n=o5YBuDZ7CvCUXc-u\&q=85\&s=7637f15adb99579fc11b280859a919a1)

**1. Open Custom fields**

Go to **Settings → Custom fields** for your AI agent.

**2. Add the field**

Click **New field**, fill in the internal and customer-facing labels, and pick the type. Pick carefully, because existing ticket values depend on the type and it stays fixed while the field is in use.

**3. Add a collection instruction (optional)**

Tell the AI agent how to get the value, for example *"Ask for the order number from the confirmation email, not the tracking code."*

**4. Add options (Dropdown only)**

Type an option and press Enter to add it. Options have their own internal and customer-facing labels, and you can archive an option to stop offering it without losing the tickets that already carry it.

***

## Collect fields when creating tickets

![Create ticket action listing the collected fields, each with its collection instruction and a Required or Optional badge](https://mintcdn.com/chatbase/IGx3TTJzvgJBhcQX/user-guides/images/help-desk/custom-fields/action-collected-details.png?fit=max\&auto=format\&n=IGx3TTJzvgJBhcQX\&q=85\&s=41efb0efcb7f311837586db277708c87)

**1. Open the create-ticket Action**

In your AI agent's **Actions**, open a **Create ticket** Action. The **Collect additional details** section lists the fields this Action collects.

**2. Add fields**

Search your fields and add the ones this Action should collect. You can create a new field from here too. Two fields with the same customer-facing label can't be collected by one Action, since the customer couldn't tell them apart.

**3. Set how each field is collected**

Click a field's **Required** or **Optional** badge, or its gear, to open its settings for this Action. The ticket is only created once every required field has a value. Optional fields can stay empty. Fields are added as required.

**4. Customize the instruction (optional)**

In the same settings, you can give the field its own collection instruction for this Action only, or add one when the field has none. The field and your other Actions keep the original. Changes apply when you save the Action.

![Field settings for one action, with Required or Optional and a custom collection instruction](https://mintcdn.com/chatbase/IGx3TTJzvgJBhcQX/user-guides/images/help-desk/custom-fields/field-settings.png?fit=max\&auto=format\&n=IGx3TTJzvgJBhcQX\&q=85\&s=d9851fb09b05fffe43b8e1c19d82d021)

A custom instruction is a separate copy. Later edits to the field's own instruction don't reach it, so switch back to the field's instruction when you want them to. Clearing a custom instruction collects the field on this Action with no instruction at all.

The Action's [collection method](https://chatbase.co/docs/user-guides/chatbot/actions/escalate-to-human.md#chatbase-helpdesk) decides who fills the fields. In conversation, the AI agent asks for each field by its customer-facing label and your collection instruction, and re-asks for anything required that is still missing. In the chat form, the visitor fills them in next to the subject and description, with answers already given in the conversation filled in for them.

***

## Field values on the ticket

![Ticket details panel showing collected field values with inline editing](https://mintcdn.com/chatbase/o5YBuDZ7CvCUXc-u/user-guides/images/help-desk/custom-fields/ticket-details.png?fit=max\&auto=format\&n=o5YBuDZ7CvCUXc-u\&q=85\&s=aca04f67765c6dde426d783af9e75777)

Every ticket shows the fields its Action collects, filled or not, in the details panel. A field the customer didn't answer reads **Not set**. Add a field to the Action later and it appears, not set, on that Action's existing tickets too.

Your team can work with the values directly:

* **Edit or clear a value** inline from the details panel. Values are rendered by type: dates as dates, Dropdown values as their label, images as attachments.
* **Follow the history** in the ticket timeline. Each edit is recorded as *changed Order number from A to B*, with who made it.
* **Filter the inbox** by a field's value, from the Filter button or in a saved view. Operators follow the field's type, see [Filters](https://chatbase.co/docs/user-guides/chatbot/help-desk/filters.md#custom-fields).

Editing a field never reopens a closed ticket. Saving an edit counts as a ticket update, so it runs your **Ticket is Updated** triggers.

### Tickets without a field form

A ticket only has fields to edit when a create-ticket Action collected them. Tickets created any other way, such as Chatbase Live Chat tickets, show only values already stored on them, read-only, and you can't add fields to them by hand.

When you [merge tickets](https://chatbase.co/docs/user-guides/chatbot/help-desk/merging-tickets.md), custom field values stay on the merged ticket. They aren't copied to the ticket you keep.

***

## Where custom fields work

| Feature | Custom fields |
| - | - |
| [Inbox filters and saved views](https://chatbase.co/docs/user-guides/chatbot/help-desk/filters.md#custom-fields) | Yes, as filter conditions. They can't be added as columns. |
| [Triggers](https://chatbase.co/docs/user-guides/chatbot/help-desk/triggers.md#custom-field-conditions) | Yes, as conditions. No trigger action sets a field, and there are no `{{ticket.*}}` placeholders for fields. |
| [Ticket export](https://chatbase.co/docs/user-guides/chatbot/help-desk/exporting-tickets.md) | Yes, one column per field. |
| [Macros](https://chatbase.co/docs/user-guides/chatbot/help-desk/macros.md) | No. Macro variables don't include custom fields. |
| [AI draft replies](https://chatbase.co/docs/user-guides/chatbot/help-desk/ai-draft-replies.md) | No. Drafts don't read custom fields. |
| [Slack ticket threads](https://chatbase.co/docs/user-guides/chatbot/help-desk/slack-ticket-threads.md) | No. Fields aren't shown on the card or synced to the thread. |
| [Helpdesk API](https://chatbase.co/docs/api-reference/v2/helpdesk.md) | Ticket responses don't include field values. The ticket timeline does include a change event for each field edit, keyed by field ID. |

***

## Archiving fields

To retire a field, archive it. Historical ticket data keeps its meaning, because a field that holds values is never deleted or retyped.

* Archiving a field stops the AI agent from collecting it. Values already on tickets stay visible.
* If the field is still on any create-ticket Action, you'll be asked to confirm. It stays listed there, marked **Archived** and not collected, until you remove it from the Action.
* Labels stay reserved while a field is archived. To bring a field back, **restore** it instead of creating a new one. A restored field reconnects to all of its historical values.

The same applies to Dropdown options: archive an option to stop offering it, and restore it later if you need it again.

### Delete or change the type of an archived field

Once a field is archived and no ticket holds a value for it, you can open it from **Settings → Custom fields** to change its type or delete it. A value cleared from a ticket no longer counts.

* Changing a Dropdown to another type deletes its options.
* Deleting a field also removes it from every Action that still lists it.
* Deleting can't be undone.

***

## Limits

| Limit | Value |
| - | - |
| Fields per AI agent | 200 |
| Fields collected per Action | 20 |
| Image fields collected per Action | 5 |
| Options per Dropdown field | 100 |
| Internal / customer-facing label | 50 characters |
| Collection instruction | 200 characters |
| A collected value | 2,000 characters |

***

## Frequently asked questions

> [accordion] Can teammates fill in custom fields by hand on any ticket?
>
> Only on tickets whose create-ticket Action collects those fields. There, teammates can edit or clear each value inline in the ticket details panel. Tickets created any other way show stored values read-only, and fields can't be added to them.

> [accordion] Can I use custom fields in triggers?
>
> Yes, as conditions. They appear in their own **Custom fields** group in the condition picker. Triggers can't set a field value, and fields can't be inserted as placeholders in trigger emails or Slack messages.

> [accordion] Can I show a custom field as a column in the ticket list?
>
> No. The ticket list columns are fixed. You can filter on a field in a saved view, or export tickets to get one column per field.

> [accordion] Is there a multi-select field type?
>
> No. The field types are Text, Number, Boolean, Date, Email, Image and Dropdown, and a Dropdown holds one option.

> [accordion] Are custom fields returned by the Helpdesk API?
>
> Not on the ticket itself: ticket responses don't include field values. The ticket timeline includes a change event, keyed by field ID, each time a field is edited.


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