Triage

Triage lets your Guru intelligently classify incoming questions by asking clarifying questions about configurable dimensions (like operating system, product tier, or environment) before answering. The result is more accurate, context-aware responses that address the user’s specific situation instead of generic answers.

What Triage Does

Classifies Questions

Determines whether a question needs clarification, can be answered directly, or is a simple greeting

Gathers Context

Asks about relevant dimensions via interactive UI elements in the widget: buttons, dropdowns, or text fields

Routes Intelligently

Greetings get quick responses, general knowledge goes straight to an answer, and specific support gets full triage

How It Works

User asks a question

A user submits a question through the widget or another integration. This can be anything from a simple greeting to a detailed technical support request.

Triage engine classifies the question

The classification engine analyzes the question and determines its type:

Greeting: casual messages like “hi”, “thanks”, or “goodbye”
General knowledge: broad conceptual questions that can be answered without additional context
Specific support: targeted questions that benefit from knowing the user’s environment, product tier, or other dimensions

Engine checks configured dimensions

For specific support questions, the engine evaluates each configured dimension against the question text and the full conversation history to detect any values the user has already provided. This avoids redundant questions.

Widget shows interactive inputs for missing dimensions

If required dimensions are still missing after checking the conversation, the widget displays interactive inputs (buttons, dropdowns, or text fields) so the user can provide the needed context. Each input type is chosen automatically based on the number of options you configured for that dimension.

Question is answered with full dimension context

Once enough context is gathered (or the clarification limit is reached), the question is answered with all resolved dimension values injected into the search query and the LLM prompt. This produces answers tailored to the user’s specific situation.

The triage engine recognizes dimension values mentioned earlier in the conversation, so users won’t be asked for information they’ve already provided. For example, if a user says “I’m on MacOS” in their first message, the engine will detect “MacOS” as the operating system value for all subsequent questions in the same session.

Classification Routes

The triage engine routes each question into one of three paths:

Route	When	Behavior
Simple Interaction	Greetings, thanks, goodbye	Quick friendly response, no triage
Answer	General knowledge questions OR all required info gathered	Proceeds directly to answer with dimension context
Clarify	Specific support with missing dimensions	Shows interactive inputs in widget

Simple Interaction handles conversational messages that don’t require a knowledge-base lookup. The engine generates a brief, friendly reply (for example, “Hello! How can I help you today?”) and does not invoke any triage dimensions. Answer is the default path for general knowledge questions that your Guru can answer without needing to know the user’s specific environment. It is also the path taken when all required dimension values have been collected or when the clarification limit has been reached. Clarify is triggered when the engine detects that the question is about specific support and one or more required dimensions are still missing. The widget renders interactive inputs so the user can provide the needed context before the Guru generates an answer.

The clarification limit (default: 2) controls how many rounds of clarifying questions the triage engine asks before answering with whatever info it has. This prevents frustrating loops where users are asked too many questions before getting help.

Setting Up Triage

This section walks through the full configuration process: enabling triage, adding rules, reordering them, and connecting a ticket action.

Enabling Triage

To enable triage for your Guru:

Go to your Guru’s detail page
Click Triage in the sidebar
Toggle Enable Triage on

Triage is disabled by default. You can enable or disable it at any time without losing your configured rules.

Adding Triage Rules

Click the Add Rule button to open the rule creation modal. Rules appear as nodes in an interactive decision DAG canvas, with edges between them representing visibility conditions. A side Live preview panel renders what end users actually see in the widget for the current rule set, updating as you edit.

Edit Triage Rule modal with Visibility conditions

Use the Rearrange button (next to the zoom controls) to re-run auto-layout if the graph gets messy after edits. The order in which dimensions are presented to users is controlled from the Outline panel on the left of the canvas; see Reordering the Form. The modal has these fields:

Field	Description	Example
Dimension Name	The category being classified	”Operating System”, “Product Tier”, “Environment”
Options	Predefined choices entered as chips (press Enter or comma to add each one). Leave empty for free-text input.	”Windows”, “MacOS”, “Linux”
Question Template	The question shown to the user when this dimension needs to be collected	”What operating system are you using?”
Visibility conditions	When this rule should appear in the form. Empty means the rule is a root and is always considered. Add one or more conditions to gate it on earlier answers (see Conditional Rules).	Show when `os` equals any of `Linux, MacOS`
Required dimension	When checked, the user must answer this dimension before the agent proceeds	Checked / Unchecked

Both Dimension Name and Question Template are required fields. The modal will not allow you to save a rule without filling in both.

Conditional Rules (Decision DAG)

Rules can be made conditional on earlier answers so the widget only asks for a dimension when it’s relevant. For example, only ask “Which Linux distro?” when the user already answered “Linux” to the operating system question. There are two ways to add a condition:

Visibility Conditions section in the rule modal. Pick a parent question (another rule with predefined options) and toggle one or more of its option values that should unlock this rule.
Drag an individual answer onto another rule on the canvas. Every option/answer on a parent node has its own handle; dragging that specific answer onto a child node makes the child conditionally appear in the triage form whenever the user picks that answer for the parent. For example, dragging OS = Linux onto the Distro node adds (or extends) a condition parent=OS, values=[Linux] so Distro only shows after the user picks Linux. Drop on the child’s left edge handle. To remove a value from an existing condition, click the small × on its chip on the edge.

Triage Rules DAG canvas with Live preview

A rule is shown when at least one condition is satisfied. Within a condition, any of the selected values counts as a match. (Both layers are OR; there is no AND.)

Shape	Behavior
No conditions	Root rule, always visible (subject to triage classification).
One condition with one value	Classic tree: shown only when the parent resolves to that value.
One condition with multiple values	Shown when the parent resolves to any of those values.
Multiple conditions	Shown when any condition is satisfied.

Free-text rules (rules with no options) cannot be used as parents because there is nothing to branch on.

To express AND (e.g., “shown when OS is Linux AND severity is high”), chain the rules: make the second rule conditional on the first, and make the consuming rule conditional on the second.

Guards

The backend blocks configurations that would break the DAG:

Cycles — a rule cannot (directly or transitively) depend on itself.
Depth cap — the longest ancestor chain is bounded.
Stale option references — if you try to remove an option value that a child rule’s condition still references, the edit is rejected with the list of dependent children. Remove or change those conditions first.
Free-text parents — a rule with no predefined options cannot be used as a parent (there is nothing to branch on).
Cross-guru parents — a condition’s parent must belong to the same Guru.

Reordering the Form

The Outline panel on the left of the canvas mirrors the rule DAG as a nested, draggable tree. The order shown in the outline is the order users see the dimensions in the live preview, the widget, and every other surface that renders the triage form. To reorder, hover a row to reveal its drag handle (the dotted grip on the left), then drag it up or down within its parent group. Roots reorder among the other roots; children reorder among their siblings under the same parent. Drops across parents are ignored on purpose because reparenting changes the rule’s visibility conditions, which lives in the rule’s edit modal. A few details that come up:

Per-edge ordering: ordering is stored per (parent → child) edge, so a rule that appears under two parents can sit at a different position under each.
Multi-parent rules: a rule with more than one parent appears once under each parent in the outline, marked with a small branch icon. Each appearance is independently expandable.
Click to focus: clicking a row highlights the matching node on the canvas with a blue ring so you can locate it in a busy graph.
Collapse: hide the outline with the panel-collapse button at the top right of the outline; reopen it with the Outline button that appears in the canvas’s top-left corner.

Reordering only affects display order; it never changes the DAG. Visibility still depends on the conditions you configured: a child is hidden until at least one of its conditions is satisfied, regardless of where it sits in the outline.

Editing and Deleting Rules

Each node on the canvas exposes Edit and Delete buttons. Editing opens the same modal pre-filled with the rule’s current values. Deleting shows a confirmation dialog before removing the rule, and if any other rules’ conditions reference the rule being deleted, the dialog lists those dependents and warns that they will become root rules (always visible) once their last condition is scrubbed.

Delete confirmation showing dependent child rules

When a rule is deleted, any condition on other rules that referenced it is scrubbed automatically. Children that lose their last condition become root rules.

Configuring Ticket Action

Below the rules table, you can select an API Call action to use for creating support tickets from the widget. Only actions of type API Call are shown in the dropdown. Select None to disable ticket creation.

To use ticket creation, first create an API Call action in the Actions tab, then select it here. See the Actions guide for details on creating API Call actions.

The ticket action dropdown updates immediately when you make a selection. There is no separate save button. If you remove the selected action from the Actions tab, the ticket action configuration will be cleared automatically.

When triage is enabled, users interact with the triage system directly in the widget. The input type displayed depends on the number of options configured for each dimension. Each dimension appears as a labeled section with its question template text, a required/optional badge, and the appropriate input control.

Interactive Dimension Inputs

The widget automatically renders one of three input types based on the number of predefined options for each dimension:

Option Count	Input Type	Description
2-4 options	Button row	All options shown as clickable buttons. Users click one to select it.
5+ options	Dropdown select	Options shown in a select menu for a cleaner interface.
No options (free text)	Text input	A single-line text field, or a multi-line textarea for error logs and descriptions.

The “Other” Option

Every dimension with predefined options also shows an Other button alongside the preset choices. Clicking Other replaces the buttons or dropdown with a free-text input field where users can type a custom value. Clicking Other again toggles back to the preset options. This ensures users are never blocked when their situation doesn’t match the predefined choices. For example, if your operating system options are “Windows”, “MacOS”, and “Linux”, a user running FreeBSD can click Other and type their OS manually.

Submit Validation

Required dimensions must have a value before the Submit button becomes active. Optional dimensions can be left blank and are clearly labeled with an “Optional” badge. The submit button stays disabled until all required fields are filled in, providing clear visual feedback about what information is still needed.

Additional Details

Below all dimension inputs, the triage form includes an optional Additional Details textarea. Users can provide extra context about their issue that doesn’t fit into any specific dimension. This text is:

Included in the formatted triage submission sent as a message (e.g., Additional Details: <text>)
Appended to the ticket form’s Description field when the user creates a ticket after triage

When a ticket action is configured (see Configuring Ticket Action), users see a Create Ticket button below the most recent AI answer. Clicking it opens a ticket form that combines standard fields with any parameters defined on the linked Action.

Standard Fields

Every ticket form includes these fields:

Subject: auto-generated from the conversation, summarizing the user’s question. Editable before submission.
Description: pre-filled with the full conversation history (user messages and AI responses), including any triage clarification steps. If the user provided additional details during triage, they are appended at the end of the description. Editable before submission.
Email: the user’s email address for follow-up communication.
Name (optional): the user’s name.

If data-pass-user-info is configured on the widget, the email and name fields are pre-filled automatically from the user’s stored identity in localStorage. See the Website Widget guide for details on configuring user info passthrough.

Action Parameters as Form Fields

Any parameters you define on the linked API Call action appear as additional fields in the ticket form. These parameters are automatically populated from the conversation context, including values the user provided during triage. For example, if your ticket action has these parameters defined:

Parameter	Type	What to Extract
`operating_system`	String	Operating System
`version`	String	Version
`component`	String	Component

The ticket form will display an Operating System, Version, and Component field below the standard fields. If the user already provided these values during the triage flow (for example, they selected “Linux” as their operating system), those fields are pre-filled automatically. Users can review and edit these values before submitting.

This means the ticket sent to your external system (Zendesk, Jira, Linear, GitHub, or any REST API) includes structured, machine-readable parameter values alongside the conversation context. The standard form fields (subject, description, email, name) are automatically injected into the request body by Gurubase. You do not need to add placeholders for them. Gurubase replaces any static "subject" value with the form’s subject, appends the conversation history to the content field, and adds a requester object with the user’s email and name. Only your custom Action parameters need {parameter_name} placeholders in the body.

Example: Zendesk Ticket Action

To create tickets in Zendesk, set up an API Call action with these settings: Endpoint: POST https://{your-subdomain}.zendesk.com/api/v2/tickets.json Authentication: Enable Basic Auth with [email protected]/token as the username and create a {ZENDESK_API_TOKEN} secret for the password. Request Body:

{
  "ticket": {
    "subject": "Bug report from Gurubase",
    "tags": ["gurubase_ai_created"],
    "comment": {
      "body": "Ticket created via Gurubase"
    },
    "priority": "normal",
    "custom_fields": [
      { "id": 12345, "value": "{operating_system}" },
      { "id": 12346, "value": "{version}" },
      { "id": 12347, "value": "{component}" }
    ]
  }
}

You only need {parameter_name} placeholders for your custom Action parameters like {operating_system}, {version}, and {component}. Gurubase automatically handles the rest: the static "subject" value is replaced with the subject from the ticket form, the conversation history is appended to the "body" field, and a requester object with the user’s email is added. Your support team sees structured metadata on every ticket without any manual data entry.

To get the most out of ticket creation with triage, name your Action parameters to match your triage dimensions. When a triage dimension collects “Operating System” and your Action parameter extracts “Operating System”, the value flows through automatically from triage to the ticket form.

Best Practices

Start with 2-3 required dimensions

Don’t overwhelm users with too many questions upfront. Focus on the dimensions that most improve answer quality. For example, operating system and product tier are common high-impact choices for technical support. You can always add more dimensions later once you see which ones make a meaningful difference in answer accuracy.A good rule of thumb: if knowing a dimension value changes the answer significantly, make it required. If it only slightly improves the answer, make it optional.

Write clear question templates

The question template is shown verbatim to users in the widget. Make it conversational, specific, and easy to understand at a glance.

Avoid	Use Instead
”OS?"	"What operating system are you using?"
"Plan"	"What product plan are you on?"
"Env"	"What environment are you experiencing this in (production, staging, or development)?”

Clear templates reduce confusion and improve response rates. Write them as if you’re having a conversation with the user.

Use predefined options when possible

Buttons and dropdowns are faster than typing and produce more consistent data. A user clicking “Windows” is faster and cleaner than typing “windows”, “Windows 11”, “Win”, or “win10”.Reserve free-text inputs for truly open-ended dimensions like error messages, log output, or detailed descriptions where predefined options wouldn’t make sense.

Keep the clarification limit low

The default limit of 2 rounds is a good starting point. This means the engine will ask for missing dimensions at most twice before answering with whatever context it has collected so far.Higher limits may frustrate users who just want a quick answer. If you find that 2 rounds aren’t enough, consider whether you need to restructure your dimensions (for example, combining two related dimensions into one) rather than increasing the limit.

Review triage analytics regularly

Check which dimensions are most frequently resolved and whether they correlate with higher trust scores and fewer follow-up questions.Questions to ask during review:

Which dimensions are resolved most often? These are working well.
Are users frequently clicking “Other”? You may need to expand your predefined options.
Are optional dimensions rarely filled in? Consider removing them to simplify the experience.
Are certain dimension combinations common? This might indicate you need a more targeted dimension.

Importing and Exporting Rules

The triage editor includes Export and Import buttons next to Add Rule. Use them to back up a configuration, copy a setup between gurus, or restore from a snapshot.

Export

Click Export to download the current guru’s triage rules as a JSON file (<slug>-triage-rules-<YYYYMMDD>.json). The file contains every rule with its dimension, options, question template, required flag, display order, and conditions. Conditions reference other rules via a file-scoped local_id, not database IDs, so the same file imports cleanly into any guru.

Import

Importing replaces all current triage rules for the guru. Pick a JSON file and the editor will:

Validate the file (shape, parent references, free-text-parent rules, value containment, cycles, depth cap).
Show a preview dialog with the full diff: which existing rules will be deleted and which new rules will be created, plus warnings for things like name collisions.
Run the destructive replace only after you click Replace all rules.

The preview lays out the full diff and any warnings before anything is written:

Import Triage Rules dialog showing the diff of rules to delete and rules to create

If validation fails the dialog lists every error with its path and code so you can fix the file in one pass instead of re-uploading after each error.

Import is destructive. Export the current rules first if you want a backup, then import the new file.

The replace is wrapped in a single transaction and inserts rules in topological order (roots first, then their children). If anything goes wrong mid-import, the existing rules are untouched.

Next Steps

Actions

Create API Call actions for ticket creation and other integrations

Analytics

Monitor triage effectiveness and question patterns

Website Widget