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 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 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.

Next Steps

Actions

Create API Call actions for ticket creation and other integrations

Analytics

Monitor triage effectiveness and question patterns

Website Widget

Configure the widget that powers the triage UX

Get Started