Ticket IQ
Configuration settings for the TicketAI prediction engine, widget layout, and escalation notifications.
The Settings > Configuration > TicketIQ section controls tenant-level settings for TicketAI, the prediction engine that matches incoming tickets to KB articles and surfaces AI-driven recommendations in agent-facing IT Service Management (ITSM) integrations. The two primary settings, Policy and Widget, accept JSON configurations and control prediction behavior and widget layout respectively; the remaining settings are checkboxes and integers that adjust supporting behavior.
Policy
Type
Text field (JSON)
Default
JSON object with "enabled": false
Controls how TicketAI matches incoming tickets to knowledge base (KB) articles, defining query fields, preprocessing functions, matching method, confidence thresholds, score normalization, and enabled prediction types. TicketAI returns no predictions until you set enabled to true in this JSON. When the widget server processes a TicketAI request, it uses a channel-level policy first, then a bot-level policy, then this tenant-level field as the final fallback.
The default value below reflects a minimal working configuration. The full schema supports additional properties documented in the sections below.
Core
enabled
Boolean
false
Master switch for all TicketAI predictions. Set to true to activate ticket matching. Leaving this false means the widget server returns no predictions regardless of any other settings.
queryFields
Array of strings
["title", "description"]
The ticket fields sent to the matching engine. Adjust this if your ticketing system stores relevant content in fields other than title and description.
preProcessing
Object
See default
JavaScript function strings applied to each query field before the engine passes it to the matching service. Each key is a valid query field name (title, description, or searchText); the value is a function string with the signature function(fieldValue), where fieldValue is the raw string from that ticket field. The function must return a string; a non-string return falls back to the original field value. The default description function strips a common "Message: Short Description of Issue:" prefix that some integrations prepend to ticket descriptions.
Matching and processing
processing.method
String
"sequential"
Controls how the engine queries ticket fields. "sequential" tries fields in the order listed in processing.fields and stops as soon as a result reaches sequentialStopScore, which is more efficient. "parallel" runs all fields simultaneously and merges the results, which may surface more matches at the cost of speed.
processing.fields
Array of strings
["title", "title+description"]
The fields or combined field expressions passed to the matching engine. "title+description" concatenates both fields into a single query.
processing.sequentialStopScore
Integer
90
Only applies when method is "sequential". If a match reaches this confidence score, the engine stops evaluating remaining fields. Lowering this value causes the engine to query more fields before stopping; raising it requires a higher-confidence early match before it stops.
bolScoreFunc
String (JS function)
See default
JavaScript function string that computes the BOL (Bag of Lematta) confidence score. The function has the signature function(numOfBOLKB), where numOfBOLKB is an integer count of BOL KB matches. The function must return a floating-point score. The default function returns a decreasing score as more matches are found, reflecting lower confidence when many articles match.
confidenceScoreThreshold
Object
See default
Minimum confidence score each model must produce before its results are surfaced. The engine discards results below these thresholds. Keys: intent (default 80), bol (default 60), keywordsearch (default 30), kbClassifier (default 40). Lower thresholds return more results with less confidence; higher thresholds return fewer but stronger matches.
scoreNormalization
Object
See default
JavaScript function strings that remap raw model scores before results are returned. Each key is a model type; valid keys are intent, bol, keywordsearch, kb_classifier, and publicKBs. Each value is a function string with the signature function(score), where score is the raw numeric score from that model. The function must return a number; the return value is used directly with no clamping or validation. On exception, the original score is preserved. An absent key leaves that model's scores unchanged. confidenceScoreThreshold filtering runs before normalization, so only results that already passed the threshold are normalized. See Score normalization input ranges below for the expected input range per model type.
maxNumOfKB
Integer
5
Maximum number of KB articles returned per prediction call. Increase this if agents need more suggestions; decrease it to surface only the highest-confidence matches.
maxNumSimilarTickets
Integer
5
Maximum number of similar past tickets returned alongside KB predictions.
fulfillmentEnable
Object
Not set
Restricts which model types are allowed to contribute results. Keys: intent, bol, keywordsearch. Set a key to false to disable that model entirely for this tenant. When not set, all models run.
enableEntityMatching
Boolean
false
Enables entity matching validation when the tenant-server path processes requests. Adds a matching check based on entities extracted from the ticket.
isConversation
Boolean
false
When true, the engine treats the incoming ticket as a multi-turn conversation thread and adjusts its matching logic accordingly, rather than treating it as a single message.
predictionTimeout
Object
30 per model
Per-model request timeouts in seconds. Keys: nlp, sentiment, escalation. Any model not specified defaults to 30. Increase these values if models are timing out under load.
Score normalization input ranges
The score argument each normalization function receives depends on the model type.
intent
0–100
Score is numeric.
bol
0–100
Defaults to exactly 98 when no intent-derived score is available.
keywordsearch
Varies
The default normalization function is calibrated for scores starting around 30. Verify the actual range for your deployment before customizing.
kb_classifier
Varies
The kb_classifier normalization key behaves differently depending on which KB Classifier mode your tenant uses. Contact Aisera before configuring a normalization function for this key as it may not produce the expected results.
publicKBs
Always 50
Public KB results receive a fixed score of 50 before normalization runs.
Prediction types
predictions
Array of strings
Not set
The prediction types the engine runs for each request. Only types listed here are executed; omitting a type disables it entirely. Valid values: "predictions", "relatedKBs", "similarTickets", "similarRequestTickets", "publicKBs", "majorIncidents", "sentiment", "sentimentV2", "sentimentV3", "escalation", "cannedAnswers", "favoriteCannedAnswers", "freeFormSearch", "emotion". Limit this array to the types your use case requires to avoid unnecessary processing.
KB classifier
useKBClassifier
Boolean
false
Enables the v1 KB classifier post-processor, which re-ranks KB article results after initial matching.
useKBClassifierV2
Boolean
false
Enables the v2 KB classifier post-processor. When both useKBClassifier and useKBClassifierV2 are true, v2 takes precedence.
KBClassifierMode
String
"replace"
Controls how the classifier merges its output with existing predictions. "replace" discards previous KB results and substitutes the classifier's output; "append" adds the classifier's results to the existing list.
Intent extraction
intentExtractorService.enabled
Boolean
false
Enables the intent extractor, which pulls a concise intent phrase from the ticket before passing it to prediction models.
intentExtractorService.allowInSearch
Boolean
false
When true, the intent extractor also runs during search requests, not just prediction requests.
intentExtractorService.predictions
Array of strings
Not set
The prediction model types that receive the extracted intent phrase as their input instead of the raw ticket fields.
Free-form search
freeFormSearch.enabled
Boolean
false
Enables free-form search, which allows unstructured text queries against the knowledge base.
freeFormSearch.isSearchOnly
Boolean
false
When true, only free-form search runs for the request and all other prediction models are bypassed.
LLM field predictions
llmFieldPredictions
Boolean
false
When true, field prediction requests are routed through the Large Language Model (LLM) prediction path instead of the standard model path.
Services
The following service objects enable specific AI capabilities. Each accepts an enabled flag, a flow or prompt identifier, and a deadlineInSec timeout in seconds.
fieldPredictions
promptName, flowId
Predicts values for ticket fields such as category or priority. Set versionEnabled: true to use the v2 prediction API path.
sentimentService
promptName
Analyzes the sentiment of the incoming ticket.
ragService
flowId
Retrieval-Augmented Generation service for knowledge-grounded responses.
summaryService
flowId
Generates a summary of the ticket content.
nextBestAction
flowId
Suggests the next best action for the agent based on the ticket.
wrapUp
flowId
Generates a wrap-up summary after ticket resolution.
generateKnowledge
Object
{}
Configuration for automatic KB article generation from resolved tickets.
generatedKnowledgeTemplate
String
""
Template name for generated KB articles. Set to "none" to disable knowledge generation.
Phrase retriever
phraseRetriever.summaryTypeAttributes
Object
{"SUMMARY": {}}
Configuration for the phrase retriever, keyed by summary type. Each key maps to a configuration object for that summary type. Valid keys: "SUMMARY", "EMAIL_RESPONSE", "KB_ARTICLE", "ANSWER".
Canned answers
Canned answers are pre-written KB articles or response templates that agents can insert into a ticket reply with one click. The TicketIQ widget surfaces the most relevant ones based on the ticket's content.
Example: An IT agent opens a ticket — "My VPN won't connect after the Windows update." The widget surfaces:
How to reinstall the VPN client after a Windows update
VPN troubleshooting steps for Windows 10/11
Reset VPN credentials
The agent clicks the most relevant article and it populates their reply field.
Canned answers differ from relatedKBs in purpose and audience. relatedKBs surfaces articles to help the agent understand the issue; cannedAnswers surfaces content specifically curated as ready-to-send agent replies — typically shorter, resolution-focused, and written in a directive voice.
cannedAnswer.enabled
Boolean
false
Enables canned answer lookups, which surface pre-written responses alongside ticket predictions.
cannedAnswer.maxCannedAnswers
Integer
10
Maximum number of canned answers returned per request.
cannedAnswer.botId
Integer
0
The bot ID used to scope canned answer lookups.
cannedAnswer.datasourceId
String or Array
Not set
The datasource(s) to search for canned answers. Accepts a comma-separated string of IDs or an array of integers.
cannedAnswer.useScript
Boolean
false
When true, the bot ID is determined dynamically by executing script rather than using the static botId value.
cannedAnswer.script
String (JS function)
Not set
JavaScript function string that determines the bot ID used for canned answer lookups. The function has the signature function(input), where input is the ticket object. The function must return a number (integer bot ID). A non-numeric return or exception resolves to bot ID 0. When bot ID is 0, the system falls back to the static cannedAnswer.botId value; if that is also 0 or absent, no canned answers are fetched. Only evaluated when useScript is true. For the input object shape, see Post-processing function reference below.
cannedAnswer.defaultQueryText
String (JS function)
Not set
JavaScript function string that provides the canned answer search query when the primary query (derived from the ticket title and description) is empty. The function has the signature function(input), where input is the ticket object. The function must return a string. A non-string return, an empty string, or an exception terminates the canned answer search with no results — there is no further fallback to the ticket title or any other value. Note: when this function is called, input.queryText contains the empty primary query; use other ticket fields such as input.title to construct a meaningful fallback. For the input object shape, see Post-processing function reference below.
cannedAnswer.favorites
Boolean
false
Enables the favorites canned answers endpoint, which returns answers the agent has marked as favorites.
Examples:
The following example shows a cannedAnswer.script function that routes to different bots based on ticket content type:
The following example shows a cannedAnswer.defaultQueryText function. Note that input.queryText is empty when this function is called — use other ticket fields to construct the query:
Auto-complete
autoCompleteTickets.datasourceId
String
Not set
The datasource(s) to search when generating auto-complete suggestions for ticket fields.
autoCompleteTickets.maxTickets
Integer
10
Maximum number of auto-complete suggestions returned.
Post-processing
postProcessing
String (JS function)
Not set
JavaScript function string that runs after all predictions are assembled, before results are returned to the caller. The function has the signature function(input), where input.ticketObj is the originating ticket and input.responseData is the complete prediction output. Returning a non-empty value replaces responseData entirely; returning null, undefined, [], or {}, or throwing an exception, leaves the original responseData unchanged. See Post-processing function reference below for input and output shapes.
predictionPostProcessing
Object
{}
Per-prediction-type JavaScript function strings that run before each type's results are returned. Valid keys: predictions, relatedKBs, publicKBs, kbClassifier, similarTickets, sentiment. Each value is a function string with the same signature as postProcessing. The same return behavior applies: non-empty replaces, empty or exception preserves. See Post-processing function reference below for shapes.
Post-processing function reference
Both postProcessing and predictionPostProcessing functions receive function(input), where input has two properties: ticketObj and responseData.
ticketObj fields:
id
String
External ticket ID from the originating ITSM system.
ticketId
Number
Internal numeric ticket ID.
displayId
String
Human-readable ticket display identifier.
title
String
Ticket title or subject line.
description
String
Ticket body or description.
contentType
String
Ticket type, such as "Incident".
dataSourceId
String
ID of the data source this ticket belongs to.
tenantId
String
Tenant ID.
isConversation
Boolean
Whether the ticket represents a multi-turn conversation.
agentId
String
ID of the handling agent. Present only when the request includes an agent ID header.
postProcessing responseData fields:
The responseData object contains the assembled output from all active prediction models. Only keys for enabled prediction types are present; exact fields depend on the predictions array in Prediction types.
predictions
Array of field prediction objects.
relatedKBs
Array of KB result objects.
similarTickets
Array of similar historical ticket objects.
sentiment
Sentiment result objects.
escalation
Escalation result objects.
cannedAnswers
Array of canned answer objects.
favoriteCannedAnswers
Array of favorited canned answer objects.
majorIncidents
Major incident objects.
ticketIntent
Ticket intent objects.
intents
Intent objects.
predictionPostProcessing responseData shape per key:
Key
responseData shape
predictions
Array of field prediction objects.
relatedKBs
Array of KB result objects.
publicKBs
Array of KB result objects, same shape as relatedKBs.
kbClassifier
Array of KB result objects, same shape as relatedKBs.
sentiment
Sentiment result object.
similarTickets
Object { similarTickets: [...] }, a wrapper object, not a plain array. Destructure accordingly.
KB result object:
title
String
Title of the KB article section.
documentKey
String
Unique document key.
documentTitle
String
Document-level title.
sectionTitle
String
Title of the matched section within the document.
url
String
URL to the KB article.
contentId
String
Content identifier.
source
String
Model that produced this result. One of "bol", "intent", "keywordsearch", "kb_classifier".
answerContents
Any
Structured answer content, if available.
content
String
Article text.
score
String
Confidence score as a decimal string. For example, "87.50". This is a string, not a number.
intentId
String or null
Associated intent ID, if applicable.
datasourceId
String
ID of the data source containing this article.
isPrivate
Boolean
Whether the article is in a private knowledge base.
useful
Any
Agent feedback value, if populated.
feedbackValue
Any
Feedback value, if populated.
Examples:
The following example shows a postProcessing function that removes KB results below a custom score threshold:
The following examples show predictionPostProcessing functions for two keys. Note that similarTickets passes a wrapper object as responseData rather than a plain array — the function must return the same wrapper shape.
Access control
aclKeys
Array of objects
Not set
Scopes KB search and Retrieval-Augmented Generation (RAG) results to the user's Access Control List (ACL) context. Each entry requires two properties: name and valueMapping. name must match an existing top-level key on the ticket object after customFields flattening, it acts as both the filter gate (entries are skipped when name does not exist on the ticket object) and the output key name in the session attributes. valueMapping is a dot-notation path that extracts the actual value from the ticket object. Ticket customFields are automatically flattened to the top level before path resolution: a custom field { key: "severity", value: "2" } becomes ticket.severity = "2". See ACL keys reference below for the available ticket fields.
ACL keys reference
aclKeys entries are evaluated against the following ticket object fields. Values in customFields are additionally flattened to the top level before path resolution.
id
String
External ticket ID.
displayId
String
Human-readable display identifier.
title
String
Ticket title or subject line.
description
String
Ticket body or description.
status
Object
Ticket status object. Access nested fields with dot notation, for example status.statusCode.
category
String
Ticket category.
type
String
Ticket type, for example "Incident".
ticketUri
String
URL of the ticket in the originating ITSM system.
agentId
String
ID of the handling agent.
userEmail
String
Email address of the ticket submitter.
locale
String
Request locale, for example "en_US".
queryText
String
Computed query text derived from the ticket.
customFields
Array
Array of { key, value } pairs. Each pair is also flattened to the top level as ticket[key] = value before valueMapping is evaluated.
valueMapping uses dot-notation to traverse nested fields. For example, to extract statusCode from the status object, set valueMapping to "status.statusCode" and name to "status" so the filter gate passes.
If two entries share the same name, the second entry silently overwrites the first in the session attributes output.
Widget
Type
Text field (JSON)
Default
Not configured
Stores the layout and behavior configuration for a TicketAI widget embedded in an external ITSM system. A UUID identifies each widget, allowing a single tenant to run multiple independent widget instances. When the widget loads, it fetches this configuration by tenant ID and widget UUID. Changes take effect immediately on the next widget load.
Top-level properties
appToken
String
Required
Authentication token for this widget instance. Used to authenticate all widget requests.
refreshToken
String
""
OAuth (Open Authorization) refresh token for the widget session.
externalSystemType
String
Required
The ITSM system this widget is embedded in. Valid values: "zendesk", "serviceNow", "serviceNowWorkspace", "jira", "salesforce". Controls the default behavior for agent actions such as applying a KB article: Zendesk and ServiceNow default to a draft comment; Jira and Salesforce default to a persisted comment.
zendesk
Object
{}
System-specific configuration for Zendesk. Reserved for future use.
serviceNow
Object
{}
System-specific configuration for ServiceNow. Reserved for future use.
jira
Object
{}
System-specific configuration for Jira. Reserved for future use.
salesForce
Object
{}
System-specific configuration for Salesforce. Reserved for future use.
Widget layout
The sections array defines the widget's structure and contains three fixed sections: top, main, and bottom. All panels live within main, which uses a "tabs" layout, the only supported value. The two supported tabs are resolution and recommendations.
Each tab contains a sections array of panel objects. Every panel has a name identifying the panel type, an enabled flag, and a config object with panel-specific settings.
Resolution tab panels
The resolution tab surfaces AI-recommended solutions for the current ticket.
churn_analysis
Churn or risk analysis for the ticket. Accepts config.labels, an array of severity label strings, and config.colors, an array of color values in matching order.
ticket_summary
AI-generated summary of the ticket. Accepts the same config.labels and config.colors structure as churn_analysis.
predictions
Predicted values for ticket fields such as category or priority. Accepts config.colors, an object mapping severity keys success, warning, error to color values, and config.excludeFields, an array of field mapping IDs to hide.
kb
AI-recommended KB articles. See KB panel configuration below for the full set of options.
macro
AI-recommended macro responses. Accepts config.amount, config.skip, and config.feedback.
intent
The classified intent for the ticket. See Intent panel configuration below.
Recommendations tab panels
The recommendations tab surfaces related items for agent reference.
macro
Same configuration as the macro panel in the resolution tab.
kb
Same configuration as the kb panel in the resolution tab.
similar_tickets
Similar historical tickets. Accepts config.amount and config.skip.
major_incidents
Detected major incidents related to the ticket. Accepts config.amount and config.skip.
Common panel configuration
Most panels share these config properties:
enabled
Boolean
true
Whether the panel is visible in the widget. Set to false to hide it.
config.amount
Integer
Varies
Maximum number of results to display in the panel.
config.skip
Integer
0
Number of results to skip. Used for pagination.
config.feedback.enabled
Boolean
true
Whether agents can submit thumbs-up/down feedback on results in this panel.
KB panel configuration
The kb panel accepts additional configuration:
config.escalationFlow.enabled
Boolean
false
Whether to show a Refine Results escalation button in the KB panel.
config.escalationFlow.flowId
String
""
The flow ID to invoke when the escalation button is clicked. Requires escalationFlow.enabled: true.
config.slots.enabled
Boolean
true
Whether slot-filling is enabled when an agent applies a KB article.
config.onApply
Array of objects
See example
Defines the action taken when an agent clicks Apply on a KB article. Each entry specifies a condition and an action. Multiple entries allow different actions based on whether the comment is public or private.
config.onApply entry structure:
condition.isPrivate
Boolean
When true, this rule applies to private/internal comments. When false, it applies to public comments.
action
String
The action to take. Valid values: "persistComment" saves the comment immediately, "draftComment" stages the comment for agent review before saving, "draftEmail" opens an email compose window. Salesforce only.
Intent panel configuration
config.amount
Integer
1
Number of primary intents to display.
config.feedback.enabled
Boolean
true
Whether agents can submit feedback on intent classifications.
config.alternateIntent.enabled
Boolean
true
Whether to show a dropdown of alternate intent suggestions alongside the primary classification.
config.alternateIntent.maxIntentsInList
Integer
20
Maximum number of alternate intents shown in the dropdown.
Consolidated API Timeout (in seconds)
Type
Integer
Default
60
Sets the maximum number of seconds the consolidated predictions API waits for TicketAI results before returning a response. When the API is called, it dispatches prediction jobs to a background thread and waits up to this value for them to complete: field predictions, related KBs, similar tickets, and major incidents. If predictions finish in time, the API returns full results. If the timeout expires, the API returns immediately with empty arrays for all prediction types rather than hanging the caller. Increase this value if your tenant's prediction workload regularly exceeds 60 seconds; decrease it if you need the integration to fail fast.
Use Tenant server for Testing API. Default is ticketiq widgets server
Type
Checkbox
Default
Disabled
Routes TicketAI consolidated prediction requests to tenant-server instead of the widget server's built-in prediction engine. By default, the widget server handles both /v1/service/consolidated-predictions and /v1/service/auto-resolution-prediction using its own internal logic. When enabled, both endpoints proxy requests directly to the tenant-server and return that response. Enable this when you need to test or validate the tenant-server prediction path against live traffic without changing client-side integrations.
This is a routing switch intended for testing and diagnosis, not permanent production use.
See also: Consolidated API Timeout (in seconds)
Use Title First in TicketAI RelatedKbs instead of description
Type
Checkbox
Default
Disabled
When enabled, related KB searches use the ticket title as the primary query and description as secondary. When disabled, the engine uses description as the primary query. This setting only applies when enabled is false in the Policy JSON; if Policy is active, its queryFields and preProcessing settings govern query field ordering instead.
See also: Policy
Enable escalation report notification through email
Type
Checkbox
Default
Disabled
Controls whether the Aisera Platform sends escalation report emails to configured recipients. When disabled, all escalation notification jobs exit immediately without sending any emails, regardless of how notifications are configured.
When enabled, escalation notifications run in two modes. In real-time mode, the Aisera Platform sends a notification per ticket immediately when escalation occurs. In scheduled mode, a batch email covers all matched tickets on a configured interval (daily, weekly, or monthly). Both modes use HTML email templates with recipients, trigger conditions, and templates defined per notification record.
Enable this when your team needs proactive email alerts about ticket escalations, either as they occur or in periodic digest form. This is most useful for support managers or on-call teams who monitor escalation trends but are not watching the TicketIQ dashboard in real time.
Enabling this flag alone does not configure escalation emails. Create notification records defining recipients, schedules, and templates via the escalation notifications API before enabling this setting. Email delivery also requires a working MailClient integration configured for the tenant.
Disabling this flag silently suppresses all escalation emails; jobs complete with a SUCCEEDED status but the Aisera Platform sends no emails. The manual trigger endpoint (POST /v1/tenants/{tenantId}/escalationnotifications/trigger) also respects this setting.
Last updated
Was this helpful?