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

The following table details the structure of a transaction JSON object sent to the analytics hook, including processed user interactions. The Channel column indicates the interaction type:

• Phone: Fields specific to voice interactions using the Phone channel.

• Text: Fields specific to text-based interactions using the Text Chat API (version 2).

• Both: Fields that apply to both Phone and Text interactions.

Key	Type	Description	Mandatory	Channel
apiVersion	string	API version of the Text Chat interaction (for example, TextchatV2RequestBody).	Yes	Text
callControlMessages	array	Messages controlling the call flow.	No	Phone
callMeta	object	Metadata about the call.	No	Phone
collectedDtmf	string	DTMF digits collected from user input.	No	Phone
conversationId	string	Unique identifier for the conversation session.	Yes	Text
continueListening	boolean	Indicates whether the bot should continue listening after a response.	No	Phone
customSTT	string	Custom speech-to-text configuration for the call.	No	Phone
endConversation	boolean	Indicates whether the conversation should end after the response.	No	Text
endTalk	boolean	Indicates whether the bot should stop listening after playing the prompt.	No	Phone
errorMessage	string	Error message related to the call.	No	Phone
event	string	Type of event that occurred during the call (Phone) or the event triggered by the request (Text).	No	Both
intent	object	Details of the incoming intent, processing state, and transitions.	Yes	Both
intent.explicitlyHandled	boolean	True when the intent was not handled by an else branch.	Yes	Both
intent.handled	string	Indicates whether the intent was handled locally or globally.	Yes	Both
intent.handledByState	object	Information about the state that handled the request.	Yes	Both
intent.handledByState.id	string	The ID of the state that handled the request.	Yes	Both
intent.handledByState.name	string	The name of the state that handled the request.	Yes	Both
intent.initialState	object	Information about the state at the start of the transaction.	Yes	Both
intent.initialState.id	string	The ID of the state at the start of the transaction.	Yes	Both
intent.initialState.name	string	The name of the state at the start of the transaction.	Yes	Both
intent.name	string	The name of the incoming intent.	Yes	Both
intent.nextState	object	Information about the state from which the next transaction will start.	Yes	Both
intent.nextState.id	string	The ID of the state from which the next transaction will start.	Yes	Both
intent.nextState.name	string	The name of the state from which the next transaction will start.	Yes	Both
language	string	Language code of the release, in BCP 47 format.	Yes	Both
meta	object	Meta-information containing occurrences of errors and warnings.	Yes	Both
meta.errors.occurrences	number	The number of errors that occurred during the transaction.	Yes	Both
meta.warnings.occurrences	number	The number of warnings that occurred during the transaction.	Yes	Both
platform	string	The platform from which the request originated.	Yes	Both
prePrompts	array	Pre-prompts played before the main prompt.	No	Phone
prompt	string	Main prompt played to the user.	No	Phone
releaseId	string	Parloa ID of the release initiating the request.	Yes	Both
reprompt	string	Reprompt played if no input is detected.	No	Phone
request	object	Raw request received by Parloa. Note: The structure and content may vary depending on the platform.	Yes	Both
requestTimestamp	string	GMT timestamp when the request was made to Parloa.	Yes	Both
requesterId	string	Platform-specific requester ID, at times equivalent to a user ID.	Yes	Text
response	object	Raw response sent to the requesting platform. Note: The structure and content may vary depending on the platform.	Yes	Both
responseElements	array	Array of response elements produced by the bot.	No	Text
responseTime	number	Processing time in milliseconds for the transaction.	Yes	Both
shouldSendNoInputEvent	boolean	Indicates whether a no-input event should be sent if the user does not respond.	No	Phone
stt	object	Speech-to-text results from the user's voice input.	No	Phone
transactionId	string	Globally unique identifier for the transaction.	Yes	Both
userContextId	string	Internal Parloa ID mapping the requester to the release.	Yes	Both
variables	array	Collection of stored variables and their values.	Yes	Both
variables.0.id	string	The immutable identifier of this variable.	Yes	Both
variables.0.name	string	A name that can be changed by the VUI designer inside Parloa.	Yes	Both
variables.0.value	any	The current value of the variable at the end of the transaction.	Yes	Both

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.