Structured Fields

Structured Fields give your team a shared, typed vocabulary. Define a field once and fill it on sessions and on contacts: a session records what it was about, a contact keeps facts that carry across sessions, such as plan or tier. Use a simple field such as a date, or organize choices into a tree.

​

Create a field

​

Build nested choices

Enum fields show an Add top-level choice button. Hover over any choice and click + to add a child below it. Each choice has a name, description, and immutable API value. Only leaf choices are workflow outputs. For example, leaves with API values refund and invoice resolve as refund||invoice; parent choices only organize the tree.

​

Use an enum for a session attribute

Expand an enum and choose Link a session attribute. Pick an existing session attribute, such as __classification, or enter a new exact key, then choose Link attribute. Enable Show when empty if agents should see it before a value has been recorded. Use Link another session attribute to reuse the choices for an additional attribute. Each attribute can use only one enum. The session sidebar uses this enum’s choices as a searchable dropdown. Maintain choices here; there is no second list to configure. Selecting a choice saves its API value to the linked attribute, while other attributes retain their normal appearance. The link uses the enum as a choice list; it does not change its per-session structured field values or Show when rules. You need Structured Fields editing permission to manage links and session editing permission to select a value. Unlinking an attribute leaves its session values intact. See session attribute dropdowns for duplicate-key handling, permissions, and troubleshooting.

​

Show a field only when another field matches

A field can depend on another one. Open the field, choose Show when, pick a parent field (an Enum or Boolean field) and the choices that should reveal it. When an agent picks Bug, the Module field appears; picking Feature request shows Priority instead. Each dependent field stays a full field of its own, with its own name, filter, and workflow variable. A field whose condition is not met is not applicable for that session or contact: it holds no value, is never required to close, and is cleared automatically if the parent changes. Dependent fields can chain up to five levels deep.

​

Organize fields into groups

Groups split your fields into sets, for example QA for review fields and Session details for what the session was about. Click New group and give it a name and, optionally, a description that appears when you hover the icon next to the group’s name. Then add fields from the group’s + button or pick a Group when you create or edit a field. Fields without a group are listed under Ungrouped. Groups only organize fields. A field works the same way in any group: in workflows, filters, exports, and the close form, where required fields are listed under their group’s name.

• Show when stays inside a group. A field can only depend on a field in the same group, so the Show when picker lists only that group’s fields.
• Linked fields keep their group. A field that another field depends on, or that depends on another field, cannot move to a different group. Remove the Show when condition, move the fields, then add it back.
• Only empty groups can be removed. Move or remove a group’s fields before removing the group.

​

Use fields in workflows

Reference a field with {{structuredFields.<api_name>}} or choose one of the Structured Fields actions:

​

Record a value on a session

Set Session Structured Field Value takes a session number, a field, and a value: a leaf choice’s API value for an Enum field, an id for a User, Team, or Tag field, YYYY-MM-DD for a Date. Leave Value empty to clear the field. The value follows the same rules as the inbox. A value on a field whose Show when condition is not met fails the run and names the parent it is waiting on, so set the parent first. Changing a parent clears the dependent fields that no longer apply; the action lists them under Removed Field Keys.

​

Fill fields from the session’s messages

Fill Structured Fields with AI reads the session and its messages, then records a value for each field they support. Pick the fields to fill, or leave Structured Fields empty to fill every Enum, Text, Number, Boolean, and Date field. User, Team, and Tag fields are never filled by AI, so the picker does not offer them.

• Parents come with their children. If you pick a field that shows only when another field matches, that parent is added to the run when it is empty and listed under Auto-included; it is recorded only if the messages support it. A parent you did not pick is never changed once it holds a value.
• Existing values are kept. Fields that already hold a value are left alone unless Overwrite Existing Values is on. When an overwritten parent changes, dependent fields that no longer apply are cleared and listed under Cleared.
• Nothing is guessed. A field the messages do not support stays empty. Every field that was not recorded is listed under Skipped with its reason, such as no_evidence, already_set, not_applicable, changed_concurrently (someone recorded the field while the AI was reading), or too_large (the field has more choices than the AI can review at once).
• Instructions add guidance for this run, for example how your team tells a refund from a cancellation.

​

Record values on a contact

Set Contact Structured Field Value takes a contact ID, a field, and a value, with the same value rules as the session action. Fill Contact Structured Fields with AI works like the session version, but records what the session’s messages support on the session’s contact instead of the session. The run fails when the session has no contact.

​

Require fields before closing a session

Open Settings → Workspace → Closing sessions, turn on Require Structured Fields to close, and pick the fields agents must record. When an agent moves a session to a closed status from the inbox, a form asks for the selected fields first. The session stays open until every one of them is filled. Values are saved per session and pre-filled if the agent comes back later. To give a team different requirements, click Add team under Team exceptions, pick the team, and choose its own fields. For example, Billing agents also record an invoice number, while Support agents record the product. Turn off Also require workspace fields for a team that should skip the workspace list; with no fields of its own, that team closes sessions without the form. Teams not listed use the workspace list. A session follows the team it belongs to when it is closed, and a session without a team uses the workspace list. Only human agents are affected. Sessions closed by the AI agent, by workflows, or by connected systems are not held back. A required field whose Show when condition is not met does not block a close; it is asked for only once its parent field holds a matching value.

​

Values on a session

The values agents record are stored per session and mirrored into the session’s attributes, so they appear in inbox filters, exports, and connected ticketing systems. They are also available through the public API and the MCP tools under the session’s structured field values. For attributes linked to an active enum through Link a session attribute, Session data takes precedence if the key exists in both attribute stores. The duplicate in Agent-added data is removed when an agent saves a dropdown selection. Ordinary session writes leave it unchanged. This does not change the Structured Field’s own per-session record or how unlinked attributes are handled.

​

Values on a contact

The same fields can be filled on a contact. A contact holds its own values, separate from any of its sessions: setting a field on a contact never changes a session, and the other way around. The same value rules and Show when conditions apply. Record them with the Set Contact Structured Field Value and Fill Contact Structured Fields with AI workflow actions, the public API, or the MCP tools. Reading and writing through the API needs the contacts read and write scopes. Contact values are kept with the contact only. They are not shown in the dashboard yet, do not appear in contact filters, segments, exports, reports, or connected CRMs, and are not copied into the contact’s attributes.

​

Limits

---

​

Related Documentation