Task Execution-Based Containment Report API

This task-wise Containment Report offers a comparative analysis of the impact of task executions on overall containment. It breaks down task-wise successes and failures by containment type, including Drop-off, Self-service, and Agent Hand-off, providing a detailed overview for better understanding and decision-making.

Method	POST and GET
Endpoint	It’s a combination of POST and GET methods. The POST method is used to set the filters and the GET method is used to fetch data as per the set filters. Post Method: Set filters. The response contains the API Response ID (“_id”) `https://{{host}}/api/public/bot/{{botID}}/taskContainmentReport` Get Method: Use the API Response ID (“_id”) to get data as per the set filters. `https://{{host}}/api/public/bot/{{botID}}/taskContainmentReport/status/{{_id}}`
Content Type	`application/json`
Authorization	`auth: {{JWT}}` See How to generate the JWT Token.
API Scope	Bot Builder: Metrics Admin Console: Not Applicable

Path Parameters

Parameter	Required/Optional	Description
host	Required	Environment URL. For example, `https://bots.kore.ai`
BotID	Required	Bot ID or Stream ID can be accessed from the General Settings page of the virtual assistant.
_id	Required (only for GET)	The API Response ID returned by the POST method in the response object; Use it in the GET method to get data as per the set filters via the POST method.

Sample Request for the POST Method

The following sample request shows how to retrieve task-execution based analytics data for different containment types with specific filters. You can modify the type and filters parameters to retrieve different types of analytics data as needed.

curl --location 'https://prod-bots.korebots.com/api/public/bot/st-8xxxxxxc-cxx2-5xxf-axx5-9xxxxxxxxxxb/taskContainmentReport' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
    "filters": {
        "dateFrom": "2024-04-22",
        "dateTo": "2024-04-30T00:00:00.000Z",
        "ConversationStatus": "Active",
        "ConversationType": "Interactive",
        "AggregationType": "Daily"
    }
}'

Request Body Parameters

Parameter	Required/Optional	Description
dateFrom	Optional	The start time selected for the report generation. If not provided, the system considers 7 days prior to the *dateTo* value. The following formats are accepted: `>yyyy-mm-dd` `>yyyy-mm-ddThh:mm:ss.msZ`
dateTo	Optional	The end time selected for the report generation. If not provided, the system considers 7 days after the *dateFrom* value. If *dateFrom* is also not provided then it is set to Today and the timeframe considered is the previous 7 days from Today. The following formats are accepted: `>yyyy-mm-dd` `>yyyy-mm-ddThh:mm:ss.msZ` The maximum or allowed time range selection is 90 days.
includeTaskName	Optional	An array of strings representing task names for which the execution report is generated.
ConversationType	Optional	The following conversation types for which data is available: Interactive Non-Interactive
ConversationStatus	Optional	The current conversation status, *Active, or Closed*.
AggregationType	Optional	One of the following report aggregation types: Daily: Generates daily reports. The allowed/maximum data range selection is 30 days. Cumulative: Generates weekly, monthly, or custom date range reports.
tags	Optional	Emitted custom tags represented as an array of objects to filter the task execution data.

Sample Response for the Post Method

The response returns the API Response ID “_id“ (as highlighted in the sample payload below). Please use this value as a query parameter in the GET request.

{
   "status": "IN_PROGRESS",
   "percentageComplete": 0,
   "streamId": "st-9xxxxxx9-0xx9-5xxd-8xxa-7xxxxxxxxx56",
   "jobType": "TASK_EXECUTION_CONTAINMENT_REPORT",
   "action": "QUERY",
   "countOfDockStatuses": 1,
   "createdBy": "u-exxxxxx6-6xx1-5xx5-axx4-5xxxxxxxxxd2",
   "expireAt": "2024-03-08T12:30:46.247Z",
   "statusLogs": [],
   "_id": "ds-9xxxxxxd-0xx4-5xx8-axx8-axxxxxxxd083",
   "lMod": "2024-03-08T12:15:46.000Z",
   "createdOn": "2024-03-08T12:15:46.253Z",
   "requestedTime": "2024-03-08T12:15:46.253Z",
   "__v": 0
}

Response Body Parameters

Parameter	Description
status	Status of the task execution. Successful execution of a task is marked as ‘Success‘. Any failure in executing the task, including drop-off, is marked as a ‘Failure.’
percentageComplete	The percentage of task execution completed.
streamId	Can be accessed from the General Settings page of the Virtual Assistant.
jobType	Task Execution Containment Report.
action	Query action for task execution.
countOfDockStatuses	The number of dock statuses generated for the task execution-based report.
createdBy	The user ID of the end user who created the task execution-based report for a virtual assistant.
expireAt	Task execution expiry timestamp.
statusLogs	An array of status logs for the task execution.
_id	The API Response ID.
lMod	The last modified time for the task execution-based report.
createdOn	The task execution-based report creation date.
requestedTime	The time of request for the task execution-based report.
__v	The field is used for internal purposes. No specific significance.

Sample Request for the GET Method

The _id generated by the POST method, (for example, considerds-9xxxxxxd-0xx4-5xx8-axx8-axxxxxxxd083 shown in the sample POST response) should be used as the query parameter in the GET Method.

curl --location
'https://prod-bots.korebots.com/api/public/bot/st-8xxxxxxc-cxx2-5xxf-axx5-9xxxxxxxxxxb/taskContainmentReport/status/ds-9xxxxxxd-0xx4-5xx8-axx8-axxxxxxxd083' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}'

Sample Response for the GET Method

{
   "tasksExecutionReport": {
   "total": 8,
   "data": {
   "2024-03-07": [
       {
         "totalExecution": 1,
         "totalSession": 1,
         "selfServiceSessions": 1,
         "dropOffSessions": 0,
         "agentTransferSessions": 0,
         "dateRange": "2024-03-07",
         "taskType": "dialog",
         "taskName": "Tags 1",
         "Status": "success",
         "selfServiceSessionsInPercentage": 100,
         "dropOffSessionsInPercentage": 0,
         "agentTransferSessionsInPercentage": 0
      },
      {
         "totalExecution": 2,
         "totalSession": 2,
         "selfServiceSessions": 0,
         "dropOffSessions": 0,
         "agentTransferSessions": 2,
         "dateRange": "2024-03-07",
         "taskType": "dialog",
         "taskName": "Agent Transfer",
         "Status": "success",
         "selfServiceSessionsInPercentage": 0,
         "dropOffSessionsInPercentage": 0,
         "agentTransferSessionsInPercentage": 100
       },
       {
         "totalExecution": 12,
         "totalSession": 6,
         "selfServiceSessions": 2,
         "dropOffSessions": 2,
         "agentTransferSessions": 2,
         "dateRange": "2024-03-07",
         "taskType": "dialog",
         "taskName": "Age Predictor",
         "Status": "success",
         "selfServiceSessionsInPercentage": "33.33",
         "dropOffSessionsInPercentage": "33.33",
         "agentTransferSessionsInPercentage": "33.33"
       },
       {
         "totalExecution": 1,
         "totalSession": 1,
         "selfServiceSessions": 1,
         "dropOffSessions": 0,
         "agentTransferSessions": 0,
         "dateRange": "2024-03-07",
         "taskType": "dialog",
         "taskName": "Tags 2",
         "Status": "success",
         "selfServiceSessionsInPercentage": 100,
         "dropOffSessionsInPercentage": 0,
         "agentTransferSessionsInPercentage": 0
       },
       {
         "totalExecution": 1,
         "totalSession": 1,
         "selfServiceSessions": 1,
         "dropOffSessions": 0,
         "agentTransferSessions": 0,
         "dateRange": "2024-03-07",
         "taskType": "dialog",
         "taskName": "Phone Number Verification",
         "Status": "failtask",
         "selfServiceSessionsInPercentage": 100,
         "dropOffSessionsInPercentage": 0,
         "agentTransferSessionsInPercentage": 0
       },
       {
         "totalExecution": 1,
         "totalSession": 1,
         "selfServiceSessions": 0,
         "dropOffSessions": 1,
         "agentTransferSessions": 0,
         "dateRange": "2024-03-07",
         "taskType": "dialog",
         "taskName": "Create Booking",
         "Status": "failtask",
         "selfServiceSessionsInPercentage": 0,
         "dropOffSessionsInPercentage": 100,
         "agentTransferSessionsInPercentage": 0
       },
       {
         "totalExecution": 2,
         "totalSession": 2,
         "selfServiceSessions": 0,
         "dropOffSessions": 2,
         "agentTransferSessions": 0,
         "dateRange": "2024-03-07",
         "taskType": "dialog",
         "taskName": "Age Predictor",
         "Status": "failtask",
         "selfServiceSessionsInPercentage": 0,
         "dropOffSessionsInPercentage": 100,
         "agentTransferSessionsInPercentage": 0
       },
       {
         "totalExecution": 1,
         "totalSession": 1,
         "selfServiceSessions": 1,
         "dropOffSessions": 0,
         "agentTransferSessions": 0,
         "dateRange": "2024-03-07",
         "taskType": "dialog",
         "taskName": "Currency",
         "Status": "success",
         "selfServiceSessionsInPercentage": 100,
         "dropOffSessionsInPercentage": 0,
         "agentTransferSessionsInPercentage": 0
        }
      ]
    }
  },
  "status": "SUCCESS"
}

Response Body Parameters

Parameter	Description
totalExecution	The overall count of the successful or failed tasks executed for a conversation session.
totalSession	Total number of conversation sessions during which the specified task is executed. If a task is executed more than once within a single conversation session and yields different results, the session will be counted twice. For instance, if Task 1 is performed twice in the same conversation session, with one execution being successful and the other failing, this session will be counted under both the Success and Failure categories for Task 1.
selfServiceSessions	Total number of conversation sessions that are marked as Self-service during which the specified task is executed (Success or Failure). Self-service sessions refer to the conversations that the virtual assistant contains.
dropOffSessions	Total number of conversation sessions that are marked as Drop-off during which the specified task is executed (Success or Failure). A session is classified as Drop-off when the user abandons the conversation in one of the following scenarios: Leaves the conversation abruptly without completing the task. Leaves the conversation after the task resulted in a failure. The last utterance of the user does not detect any intent. The virtual assistant stops responding due to any reason.
agentTransferSessions	The total number of conversation sessions marked as Agent Transfer during which the specified task is executed (Success or Failure). A session is classified as an Agent Transfer if the conversation leads to an agent transfer in a session.
dateRange	The date range based on the selected “dateFrom” and “dateTo” values.
taskType	The type of task executed for a conversation session. The task executed can be a Dialog, Alert task, FAQ.
taskName	Name of the task executed, including Dialog Tasks, Alert Tasks, and FAQs.
Status	Tasks that are successfully executed are marked as ‘Success’. Unsuccessful tasks, including drop-off, are marked as ‘Failure’.
selfServiceSessionsInPercentage	The percentage of sessions that are classified as Self-Service out of the total number of sessions that are displayed for a task status.
dropOffSessionsInPercentage	The percentage of sessions that are classified as drop-off out of the total number of sessions that are displayed for a task status.
agentTransferSessionsInPercentage	The percentage of sessions that are classified as Agent Hand-off or transfer out of the total number of sessions that are displayed for a task status.