REST API

Xatkit exposes information about a running bot through a monitoring REST API. This page details the different endpoints, expected parameters, and response examples.

Monitoring API

Status of the bot

Provides high-level information on the running bot.

Endpoint

GET /status

Response

{
  "status": "alive"
}

List Monitoring Data

Lists all the monitoring information. Note: this method does not support pagination yet (see this issue), so the response may be big for long-running applications.

Endpoint

GET /analytics/monitoring

Response

[
	[{
		"sessionId": "7df67aeb-4e20-4ee4-86dd-8f0df52e3720",
		"entries": [{
			"timestamp": 1582543925719,
			"utterance": "whats up",
			"intent": "Default_Fallback_Intent",
			"confidence": 1.0
		}, {
			"timestamp": 1582543930723,
			"utterance": "help me pls",
			"intent": "Default_Fallback_Intent",
			"confidence": 1.0
		}],
		"matchedUtteranceCount": 0,
		"unmatchedUtteranceCount": 2
	}, {
		"sessionId": "22d48fa1-bb93-42fc-bf7e-7a61903fb0e4",
		"entries": [{
			"timestamp": 1582543939678,
			"utterance": "hi",
			"intent": "Welcome",
			"confidence": 1.0
		}, {
			"timestamp": 1582543942658,
			"utterance": "how are you?",
			"intent": "HowAreYou",
			"confidence": 1.0
		}, {
			"timestamp": 1582543948698,
			"utterance": "me too! thanks!",
			"intent": "Default_Fallback_Intent",
			"confidence": 1.0
		}],
		"matchedUtteranceCount": 2,
		"unmatchedUtteranceCount": 1,
		"avgSessionConfidence": 1.0
	}], {
		"nSessions": 2,
		"avgRecognitionConfidence": 1.0,
		"totalUnmatchedUtterances": 3,
		"totalMatchedUtterances": 2
	}
]

Note: the timestamp fields contain timestamps in milliseconds.

Note: the avgSessionConfidence fields only appears in those sessions with matchedUtteranceCount >= 1, since the session confidence is computed taking into account the matched utterances.

Note: the avgRecognitionConfidence field only appears if there is at least 1 session with matchedUtteranceCount >= 1 for the same reason.

List Session Data

Lists the monitoring information corresponding to the provided sessionId.

Endpoint

GET /analytics/monitoring/session?sessionId=id

Parameters

Name	Type	Description
sessionId	string	Mandatory: the identifier of the Xatkit session to retrieve the information from

Response

{
    "sessionId": "72f8fa90-8d3e-4804-b00d-5612a95fb644",
    "entries": [
        {
            "timestamp": 1573750605388,
            "utterance": "How are you?",
            "intent": "HowAreYou",
            "confidence": 1.0
        },
        {
            "timestamp": 1573750623741,
            "utterance": "Here is something you won't understand!",
            "intent": "Default_Fallback_Intent",
            "confidence": 1.0
        },
        {
            "timestamp": 1573750630281,
            "utterance": "I knew it",
            "intent": "Default_Fallback_Intent",
            "confidence": 1.0
        }
    ],
    "matchedUtteranceCount": 1,
    "unmatchedUtteranceCount": 2
}

Note: the timestamp fields contain timestamps in milliseconds.

List Unmatched Utterances

Lists all the user inputs that haven't been successfully translated into intents.

Endpoint

GET /analytics/monitoring/unmatched

Response

[
    {
        "sessionId": "72f8fa90-8d3e-4804-b00d-5612a95fb644",
        "timestamp": 1573750623741,
        "utterance": "Here is something you won't understand!"
    },
    {
        "sessionId": "72f8fa90-8d3e-4804-b00d-5612a95fb644",
        "timestamp": 1573750630281,
        "utterance": "I knew it"
    }
]

Note: the timestamp fields contain timestamps in milliseconds.

List Matched Utterances

Lists all the user inputs that have been successfully translated into intents.

Endpoint

GET /analytics/monitoring/matched

Response

[
    {
        "sessionId": "72f8fa90-8d3e-4804-b00d-5612a95fb644",
        "timestamp": 1573750605388,
        "utterance": "How are you?",
        "intent": "HowAreYou",
        "confidence": 1.0
    }
]

Note: the timestamp fields contain timestamps in milliseconds.

Get Sessions Stats

Returns a set of session-level statistics (e.g. average time/session, average number of matched inputs/session, etc).

Endpoint

GET /analytics/monitoring/sessions/stats

Response

{
    "averageMatchedUtteranceCount": 1.0,
    "averageUnmatchedUtteranceCount": 2.0,
    "averageSessionTime": 43.246
}

Note: the averageSessionTime field represents the average session time in seconds.

Storing monitoring data

Xatkit uses an internal MapDB database to be able to register the bot activity. But for more efficient and long-term storage you can also configure Xatkit to store the running bot's data into an InfluxDB database or a PostgreSQL relational one.