Understanding Public API Data Dictionary & Conversation Result Types in Kore.ai XO

Knowledge Articles
1

This article provides a consolidated reference for:

  1. Public API Data Dictionary Resources
  2. Logic behind Conversation Analytics Result Types
  3. How intents and tasks are classified in reporting

:one: Data Dictionary for Public APIs

For detailed schema definitions, request/response structures, and field-level descriptions of Kore.ai public APIs, please refer to:

This documentation includes:

  • Endpoint definitions
  • Request/response payload structures
  • Field descriptions
  • Authentication requirements
  • Example API calls

For advanced integrations, backend validation, or payload interpretation, the API documentation serves as the primary reference.

:two: Conversation Analytics – Result Type Logic

Conversation Analytics tracks bot performance at two levels:

  1. Intent Identification
  2. Task Completion

Understanding these two layers is critical for interpreting reports accurately.

:magnifying_glass_tilted_right: Level 1: Intent Identification

This stage evaluates whether the system successfully understood the user’s input.

:white_check_mark: successintent

The system successfully resolved the user input to exactly one intent (Dialog, FAQ, or Action).

  • Bot clearly understood the request.
  • A single, confident match was identified.

Example:
User: “Book a meeting for tomorrow”
→ Intent identified: “Schedule Meeting”
→ Result: successintent

:cross_mark: failintent

The system could not resolve the user input to a single intent due to:

  • No matching intent
  • Multiple ambiguous matches
  • Low confidence score

Example:
User: “I need help”
→ Multiple possible matches or unclear context
→ Result: failintent

:warning: unhandledUtterance

The user input does not align with the expected input format or context.

This occurs when:

  • Input does not match expected entity type
  • The platform cannot interpret the value provided

Example:
Bot asks: “Enter your date of birth”
User enters: “john@email.com”
→ Result: unhandledUtterance

In simple terms, when the platform does not recognize or cannot process the user input meaningfully, it is classified as an unhandled utterance.

:counterclockwise_arrows_button: Level 2: Task Completion

Once an intent is identified and a task begins (Dialog/FAQ/Action), the system tracks whether it completes successfully.

:white_check_mark: success (successTask)

An identified task runs from start to completion successfully.

This means:

  • All required inputs were captured
  • No failure path was triggered
  • The dialog/action completed as designed

Example:
User starts “Reset Password” dialog → completes all steps → receives confirmation
→ Result: success

:cross_mark: failtask (failedTask)

A task was initiated but did not complete.

This may occur due to:

  • User drop-off
  • Triggered error path
  • Validation failure
  • Session inactivity

Special Case – Abandonment Flow

If:

  • The failure reason is inactivity, AND
  • The dialog is configured with an abandonment flow

Then:

  • The record may be reclassified from failtask to success for reporting purposes.

This ensures reporting accuracy when abandonment handling is intentionally designed.

:bar_chart: Flow Summary Table

Stage Outcome Result Type
User sends message One intent identified successintent
User sends message No intent / ambiguous match failintent
Task runs to completion Finished successfully success
Task started but not finished Drop-off / error / inactivity failtask
User input not recognized or invalid for expected context Not mapped to intent properly unhandledUtterance

:repeat_button: How It All Connects

Think of the lifecycle in two layers:

Step 1: Did the bot understand the user?

  • Yes → successintent
  • No → failintent
  • Input not interpretable → unhandledUtterance

Step 2: Did the task complete successfully?

  • Yes → success
  • No → failtask

This two-level tracking enables:

  • Accurate conversation performance measurement
  • Identification of NLU gaps
  • Detection of drop-offs
  • Optimization of dialog flows
  • Clear reporting for stakeholders

:bullseye: Why This Matters

Understanding these classifications helps you:

  • Improve intent training quality
  • Reduce ambiguous matches
  • Optimize dialog completion rates
  • Interpret analytics dashboards accurately
  • Identify friction points in conversation flows

If you require further clarification on API fields, analytics Behavior, or reporting interpretation, please contact Kore.ai Support or refer to the official documentation linked above.