Analytics Transactions: Data Structure and Insights

Every interaction between a user and your project is recorded in a transaction

Overview

The following describes the JSON structure Parloa uses to send transaction data to the analytics hook after a release. Each transaction represents one conversational turn between a user and the bot, including the user’s request, the bot’s response, and metadata generated during the interaction.

Key Features of Analytics Transactions

Each analytics transaction contains the following information:

• Metadata about the release, call, and transaction.

• User utterances (request.text), recognized intents, and slot data.

• Bot responses, including text, SSML, and intermediate responses.

• Processing details, such as response times and errors/warnings.

• Storage variables used during the turn, including empty or blacklisted variables.

Transactions Data Format

Below is the detailed structure of a transaction JSON object sent to the analytics hook, including processed user interactions:

Key	Type	Description	Mandatory
transactionId	string	Globally unique identifier for the transaction.	Yes
requestTimestamp	string	GMT timestamp when the request was made to Parloa.	Yes
responseTime	number	Processing time in milliseconds for the transaction.	Yes
userContextId	string	Internal Parloa ID mapping the requester to the release.	Yes
releaseId	string	Parloa ID of the release initiating the request.	Yes
requesterId	string	Platform-specific requester ID, at times equivalent to a user ID.	Yes
intent	object	Details of the incoming intent, processing state, and transitions.	Yes
intent.name	string	The name of the incoming intent	Yes
intent.handledByState	object		Yes
intent.handledByState.id	string	The ID of the state that handled the request	Yes
intent.handledByState.name	string	The name of the state that handled the request	Yes
intent.handled	string	Either the intent was handled locally or globally	Yes
intent.explicitlyHandled	boolean	True when the intent was not handled by an else branch	Yes
intent.initialState	object		Yes
intent.initialState.id	string	The ID of the state at the start of the transaction	Yes
intent.initialState.name	string	The name of the state at the start of the transaction	Yes
intent.nextState	object		Yes
intent.nextState.id	string	The ID of the state from which the next transaction will start	Yes
intent.nextState.name	string	The name of the state from which the next transaction will start	Yes
language	string	Language code of the release, in BCP 47 format.	Yes
meta	object	Meta-information containing occurrences of errors and warnings.	Yes
meta.errors.occurences	number	The number of errors occurred during the transaction	Yes
meta.warnings.occurences	number	The number of warnings occurred during the transaction	Yes
variables	array	Collection of stored variables and their values.	Yes
variables.0.id	string	The immutable identifier of this variable	Yes
variables.0.name	string	A name that can be changed by the VUI designer inside Parloa	Yes
variables.0.value	any	The current value of the variable at the end of the transaction	Yes
platform	string	The platform from which the request originated.	Yes
request	object	Raw request received by Parloa. Note: The structure and content of this field may vary depending on the platform.	Yes
response	object	Raw response sent to the requesting platform. Note: The structure and content of this field may vary depending on the platform.	Yes

Example Transactions

The following JSON examples illustrate transactions as sent by the analytics engine. These include a complete user-bot interaction, from the user’s utterance (request.text) to the bot’s response (response.prompt).

Example 1: Simple Interaction

This example demonstrates a single turn in a bot flow with minimal data.

{
  "transactionId": "12345abcd",
  "requestTimestamp": "2024-11-15T10:00:00.000Z",
  "responseTime": 120,
  "intent": {
    "name": "confirm",
    "handled": "locally",
    "explicitlyHandled": true,
    "initialState": {
      "id": "abc123",
      "name": "Initial Confirmation"
    },
    "nextState": {
      "id": "def456",
      "name": "Final State"
    }
  },
  "meta": {
    "errors": { "occurrences": 0, "affectedSteps": [] },
    "warnings": { "occurrences": 0, "affectedSteps": [] }
  },
  "variables": [
    { "id": "userName", "name": "userName", "value": "Alice" }
  ],
  "platform": "phoneV2",
  "request": {
    "text": "Yes",
    "intent": { "name": "confirm", "confidence": 0.95 }
  },
  "response": {
    "prompt": "Thank you for confirming."
  }
}

Example 2: Complex Interaction

This example includes additional metadata, intermediate responses, and multiple storage variables.

[
    {
        "meta": {
            "warnings": {
                "occurrences": 0,
                "affectedSteps": []
            },
            "errors": {
                "occurrences": 0,
                "affectedSteps": []
            }
        },
        "responseTime": 23,
        "platform": "phoneV2",
        "intent": {
            "initialState": {
                "id": "a25aa2af-7b9c-4c48-a5b1-326795aca923",
                "dialogName": "main",
                "name": "Nachfrage weiteres Anliegen"
            },
            "explicitlyHandled": true,
            "name": "Nein",
            "nextState": {
                "id": "STATE.base",
                "dialogName": "main",
                "name": "Routing"
            },
            "handled": "locally",
            "handledByState": {
                "id": "a25aa2af-7b9c-4c48-a5b1-326795aca923",
                "dialogName": "main",
                "name": "Nachfrage weiteres Anliegen"
            }
        },
        "transactionId": "60ba45ba981733dfa6613bf8",
        "variables": [
            {
                "id": "lastSentiment",
                "name": "lastSentiment",
                "value": ""
            },
            {
                "id": "sentimentCounter",
                "name": "sentimentCounter",
                "value": ""
            }
        ],
        "response": {
            "continueListening": false,
            "prompt": "<speak version=\"1.0\" xmlns:mstts=\"https://www.w3.org/2001/mstts\" xml:lang=\"de-DE\"><voice name=\"de-DE-KatjaNeural\">Alles klar, dann danke ich f\u00fcr das nette Gespr\u00e4ch und sage Tsch\u00fc\u00df, bis zum n\u00e4chsten Mal! <break strength=\"medium\" time=\"2012ms\" /></voice></speak>",
            "callMeta": {
                "callerId": "[phone]",
                "callId": "a8f35368-3feb-123a-618c-d094667acbd8",
                "instanceId": "60a68b0cb4678b14c6d1c67c"
            },
            "callControlMessages": [],
            "endTalk": true,
            "reprompt": ""
        },
        "requesterId": "[phone]",
        "request": {
            "callMeta": {
                "callerId": "[phone]",
                "callId": "a8f35368-3feb-123a-618c-d094667acbd8",
                "instanceId": "60a68b0cb4678b14c6d1c67c"
            },
            "intentRanking": [
                {
                    "id": -4300620255518597600,
                    "confidence": 0.999983549118042,
                    "name": "Nein"
                },
                {
                    "id": -997796091434561900,
                    "confidence": 7.319988071685657e-06,
                    "name": "HelpIntent"
                },
                {
                    "id": 4869120587039172000,
                    "confidence": 1.3637103668528994e-09,
                    "name": "askForAgent"
                }
            ],
            "text": "Nein danke",
            "slots": [],
            "intent": {
                "id": -4300620255518597600,
                "confidence": 0.999983549118042,
                "name": "Nein"
            }
        },
        "releaseId": "60a68b0cb4678b14c6d1c67c",
        "userContextId": "60a6cda164ea2442f87f0848",
        "requestTimestamp": "2021-06-04T15:24:42.882Z",
        "language":"de-DE"
    }
]

Understanding Raw Analytics Data

Analytics data, as sent from the engine, includes all available information:

• Raw storage variables: Includes variables regardless of format, name, or whether they are empty.

• Complete metadata: Tracks warnings, errors, and the callflow.

• Intent ranking: Shows all possible intents along with confidence scores.

• Slots/entities: Extracted entities and their values.

💡 Note: While analytics data is detailed, it may require processing or filtering before storing it in your database.

Intermediate Responses

Intermediate bot responses, if any, are stored in the intermediateResponses.ssml field. These responses occur between a user’s utterance and the bot’s main reply.

How to Locate Specific Data

• User utterance: Found in request.text.

• Bot response: Found in response.prompt.

• Intent name: Located in intent.name.

• Slot data: Found in request.slots.

Key Notes for Integration

• Raw Data Size: Transactions can become large, especially for bots with numerous storage variables. Consider filtering empty variables before storing them in a database.

• Events and _event Variable:

  • The _event variable captures all events during a session.

  • Individual storage variables like EventName or EventResult only reflect the most recent event.

• Customization: Customers can request the OpenAPI YAML schema for analytics integration. Providing tailored examples can help clarify data structure.