> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gurubase.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Triage
> Automatically classify and route user questions with intelligent triage rules
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
Determines whether a question needs clarification, can be answered directly,
or is a simple greeting
Asks about relevant dimensions via interactive UI elements in the widget:
buttons, dropdowns, or text fields
Greetings get quick responses, general knowledge goes straight to an answer,
and specific support gets full triage
***
## How It Works
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.
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
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.
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.
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:
1. Go to your Guru's detail page
2. Click **Triage** in the sidebar
3. 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 in a table showing each dimension's order, name, options, question template, and whether it is required.
The modal has four fields:
| Field | Description | Example |
| --------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------- |
| **Dimension Name** | The category being classified | "Operating System", "Product Tier", "Environment" |
| **Options** | Predefined choices (press Enter 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?" |
| **Required** | Whether this dimension must be answered before the Guru can respond | 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.
### Editing and Deleting Rules
Each rule in the table has **Edit** and **Delete** buttons in the Actions column. Editing opens the same modal pre-filled with the rule's current values. Deleting shows a confirmation dialog before removing the rule.
### Reordering Rules
Use the up/down arrow buttons in the **Order** column to change rule priority. The order determines which dimensions are presented first when the widget asks for clarification.
### 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](/guides/actions) 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.
***
## Widget Experience
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: `)
* Appended to the ticket form's **Description** field when the user creates a ticket after triage
### Ticket Creation from Widget
When a ticket action is configured (see [Configuring Ticket Action](#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](/integrations/bots/website-widget#user-identification) 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 `your-email@company.com/token` as the username and create a `{ZENDESK_API_TOKEN}` secret for the password.
**Request Body:**
```json theme={null}
{
"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
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.
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.
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.
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.
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.
***
## Next Steps
Create API Call actions for ticket creation and other integrations
Monitor triage effectiveness and question patterns
Configure the widget that powers the triage UX