{"id":21343,"date":"2019-06-04T07:34:33","date_gmt":"2019-06-04T06:34:33","guid":{"rendered":"https:\/\/developer.kore.ai\/v10-1\/?p=21343"},"modified":"2023-07-20T13:07:07","modified_gmt":"2023-07-20T12:07:07","slug":"sessions-api","status":"publish","type":"post","link":"https:\/\/developer.kore.ai\/v10-1\/docs\/bots\/api-guide\/sessions-api\/","title":{"rendered":"Sessions History API"},"content":{"rendered":"
<\/div>\r\n\t
\r\n\t\t
\r\n\t\t\t

This API retrieves the conversation sessions created. It returns information such as session metadata, user and bot identifiers, session duration, language, status, and other relevant metrics.<\/p>\n\n\n\n\n\n\n\n
Method<\/strong><\/td>\nPOST<\/td>\n<\/tr>\n
Endpoint<\/strong><\/td>\nhttps:\/\/{{host}}\/api\/public\/bot\/{{BotID}}\/getSessions?containmentType={{containmentType}}<\/code>
\nand https:\/\/{{host}}\/api\/public\/getSessions?containmentType={{containmentType}}<\/code>for BAC<\/td>\n<\/tr>\n
Content Type<\/strong><\/td>\napplication\/json<\/code><\/td>\n<\/tr>\n
Authorization<\/strong><\/td>\n\n

auth: {{JWT}}<\/code><\/p>\n

See How to generate the JWT Token.<\/a><\/td>\n<\/tr>\n

API Scope<\/strong><\/td>\n\n
    \n
  • Bot Builder: Bot Sessions<\/li>\n

    OR<\/p>\n

  • Admin Console: Bot Analytics > Bot Sessions<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\r\n\t\t<\/div>\r\n\t<\/div>\r\n
    <\/div>\r\n\t
    \r\n\t\t
    \r\n\t\t\t

    Path Parameters<\/span><\/h2>\n\n\n\n\n\n\n
    Parameter<\/th>\nDescription<\/th>\n<\/tr>\n
    host<\/td>\nEnvironment URL, for example, https:\/\/bots.kore.ai<\/td>\n<\/tr>\n
    BotID<\/td>\nBot ID or Stream ID. You can access it from the General Settings page of the bot.<\/td>\n<\/tr>\n
    containmentType
    (introduced in ver9.0)<\/strong><\/td>\n    		\n

    Use to filter the results based on the type of the session i.e Self-service vs. Drop-off vs. Agent Transfer
    Valid values:<\/p>\n

      \n
    • dropOff,<\/li>\n
    • selfService,<\/li>\n
    • agent.<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n<\/thead>\n<\/table>\n

      Sample Request<\/span><\/h2>\n
        \n
      • Without a body<\/b>\n
        curl --location --request POST 'https:\/\/{{host}}\/api\/public\/getSessions?containmentType={{containmentType}}' \\\r\n     --header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \\\r\n     --header 'Content-Type: application\/json' \\\r\n     --data-raw ''<\/pre>\n<\/li>\n
      • With a body<\/b>\n
        curl --location --request POST 'https:\/\/{{host}}\/api\/public\/getSessions?containmentType={{containmentType}}' \\\r\n     --header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \\\r\n     --header 'Content-Type: application\/json' \\\r\n     --data-raw '{\r\n        \"skip\" : 0,                          \r\n        \"limit\" : 100,                      \r\n        \"dateFrom\" : \"2020-02-11\",\r\n        \"dateTo\" : \"2020-02-12\"\r\n }'<\/pre>\n<\/li>\n
      • For a specific bot<\/b>\n
        curl --location --request POST 'https:\/\/{{host}}\/api\/public\/bot\/{{BotId}}\/getSessions?containmentType={{containmentType}}' \\\r\n     --header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \\\r\n     --header 'Content-Type: application\/json' \\\r\n     --data-raw '{\r\n        \"skip\" : 0,                          \r\n        \"limit\" : 100,                      \r\n        \"dateFrom\" : \"2020-02-11\",\r\n        \"dateTo\" : \"2020-02-12\"\r\n }'<\/pre>\n<\/li>\n
      • For specific session Ids<\/b>\n
        curl --location --request POST 'https:\/\/{{host}}\/api\/public\/bot\/{{BotId}}\/getSessions' \\\r\n     --header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \\\r\n     --header 'Content-Type: application\/json' \\\r\n     --data-raw '{\r\n        \"sessionId\": [\"6465cf6e4769ed4e822b82a1\",\"6465cf6e47Q9ed4e822b82a1\"]\r\n }'<\/pre>\n<\/li>\n<\/ul>\n\r\n\t\t<\/div>\r\n\t<\/div>\r\n
        <\/div>\r\n\t
        \r\n\t\t
        \r\n\t\t\t
        Request Body Parameters<\/span><\/h2>\n\n\n\n\n\n\n\n\n\n\n
        Parameter<\/th>\nDescription<\/th>\nRequired\/Optional<\/th>\n<\/tr>\n
        userId<\/td>\nThe ID of the user whose conversation history to access. Can be a user email id or enterprise assigned unique id.<\/td>\nOptional<\/td>\n<\/tr>\n
        skip\/offset<\/td>\nThe number of messages to be skipped.<\/td>\nOptional<\/td>\n<\/tr>\n
        limit<\/td>\nThe number of messages to be shown on each page.
        \nThe latest sessions are returned first; the sessions are returned in descending order of start time.<\/td>\n        		Optional<\/td>\n<\/tr>\n
        dateFrom<\/td>\nTakes the date format yyyy-mm-dd
        \n(or) yyyy-mm-ddThh:mm:ss.msZ
        \neg:2019-04-01 (or) 2019-04-01T13:25:58.515Z. If not provided, calculated as 7 days behind dataTo<\/em>.<\/td>\n        		Optional<\/td>\n<\/tr>\n
        dateTo<\/td>\nTakes the date format yyyy-mm-dd
        \n(or) yyyy-mm-ddThh:mm:ss.msZ
        \neg:2019-04-01 (or) 2019-04-01 T13:26:05.598Z. If not provided, calculated as 7 days from dateFrom<\/em>. If dateFrom<\/em> is also not provided then set to Today<\/strong>.<\/p>\n
          \n
        • The dateTo<\/strong> or dateFrom<\/strong> parameter accepts the YYYY-MM-DD date format. The time format is considered as a GMT zone in the API endpoint via Sessions API.<\/li>\n
        • When retrieving the data from the bot builder > dashboard<\/strong>, the local time zone (IST) is used; the time is converted from GMT to IST format, and then the data is retrieved.<\/li>\n<\/ul>\n<\/td>\n
        		Optional<\/td>\n<\/tr>\n
        tags<\/td>\nMeta tags to filter the conversations.<\/td>\nOptional<\/td>\n<\/tr>\n
        sessionType
        \n(introduced in v8.0)<\/td>\n        		\n
        Type to filter the conversations – can be:<\/p>\n
          \n
        • non-interactive – sessions that have bot messages presented without any message from the user<\/li>\n
        • interactive – sessions that include one or more messages from the user<\/li>\n<\/ul>\n<\/td>\n
        		Optional<\/td>\n<\/tr>\n
        sessionId
        \n(introduced in v10.1.3)<\/td>\n        		\n
        An array of session IDs to filter the conversations. It can have a maximum of 50 session IDs. (Duplicate session IDs are ignored, but they are counted.)<\/p>\n
        Note<\/b>: If you use \u2018sessionId\u2019 in the Body, other parameters\/filters are ignored.<\/td>\n
        		Optional<\/td>\n<\/tr>\n<\/table>\n
        Note<\/strong>: The duration between dateTo<\/em> and dateFrom<\/em> should be less than 7 days, else an error will be thrown.<\/p>\n\r\n\t\t<\/div>\r\n\t<\/div>\r\n
        <\/div>\r\n\t
        \r\n\t\t
        \r\n\t\t\t
        Sample Response<\/span><\/h2>\n
          \n
        • For dropOff<\/em> sessions<\/strong>\n
          {\r\n  \"total\": 1,\r\n  \"moreAvailable\": false,\r\n  \"sessions\": [\r\n   {\r\n     \"sessionId\": \"xxxxaxxexxxaxexdxxxdxxxe\",\r\n     \"botId\": \"st-ffeffxxx-xxxc-xexa-axxx-cxxabxxxxcxx\",\r\n     \"channel\": \"rtm\",\r\n     \"userId\": \"u-xxfexxxd-xxex-xdxe-xaec-xeaxbxxxxfxx\",\r\n     \"start_time\": \"2021-04-26T11:27:25.977Z\",\r\n     \"end_time\": \"2021-04-26T11:27:26.145Z\",\r\n     \"session_lang\": [\r\n       \"en\"\r\n      ],\r\n     \"sessionType\": \"interactive\",\r\n     \"containmentType\": \"dropOff\",\r\n     \"isDeveloper\": false,\r\n     \"tags\": {\r\n       \"userTags\": [\r\n        {\r\n         \"value\": \"newuser\",\r\n         \"name\": \"regular\"\r\n        }\r\n      ],\r\n      \"sessionTags\": []\r\n     },\r\n     \"noOfMessagesExchanged\": 1,\r\n     \"noOfTasksExecuted\": 0\r\n   }\r\n  ]\r\n}<\/pre>\n<\/li>\n
        • For selfService<\/em> sessions<\/strong>\n
          {\r\n  \"total\": 2,\r\n  \"moreAvailable\": false,\r\n  \"sessions\": [\r\n   {\r\n     \"sessionId\": \"xxxxaxxexxxaxexdxxxdxxxe\",\r\n     \"botId\": \"st-ffeffxxx-xxxc-xexa-axxx-cxxabxxxxcxx\",\r\n     \"channel\": \"rtm\",\r\n     \"userId\": \"u-xxfexxxd-xxex-xdxe-xaec-xeaxbxxxxfxx\",\r\n     \"start_time\": \"2021-04-26T11:27:25.977Z\",\r\n     \"end_time\": \"2021-04-26T11:27:26.145Z\",\r\n     \"session_lang\": [\r\n       \"en\"\r\n      ],\r\n     \"sessionType\": \"non-interactive\",\r\n     \"containmentType\": \"selfService\",\r\n     \"isDeveloper\": false,\r\n     \"tags\": {\r\n       \"userTags\": [\r\n        {\r\n         \"value\": \"newuser\",\r\n         \"name\": \"regular\"\r\n        }\r\n       ],\r\n       \"sessionTags\": []\r\n     },\r\n     \"noOfMessagesExchanged\": 6,\r\n     \"noOfTasksExecuted\": 0\r\n    },\r\n   {\r\n     \"sessionId\": \"xxxxaxxexxxaxexdxxxdxxxe\",\r\n     \"botId\": \"st-ffeffxxx-xxxc-xexa-axxx-cxxabxxxxcxx\",\r\n     \"channel\": \"rtm\",\r\n     \"userId\": \"u-xxfexxxd-xxex-xdxe-xaec-xeaxbxxxxfxx\",\r\n     \"start_time\": \"2021-04-26T11:27:25.977Z\",\r\n     \"end_time\": \"2021-04-26T11:27:26.145Z\",\r\n     \"session_lang\": [\r\n       \"en\"\r\n      ],\r\n      \"sessionType\": \"non-interactive\",\r\n      \"containmentType\": \"selfService\",\r\n      \"isDeveloper\": false,\r\n     \"tags\": {\r\n       \"userTags\": [\r\n         {\r\n          \"value\": \"newuser\",\r\n          \"name\": \"regular\"\r\n        }\r\n      ],\r\n     \"sessionTags\": []\r\n     },\r\n     \"noOfMessagesExchanged\": 8,\r\n     \"noOfTasksExecuted\": 0\r\n    }\r\n  ]\r\n}<\/pre>\n<\/li>\n
        • For agent<\/em> sessions<\/strong>\n
          {\r\n  \"total\": 1,\r\n  \"moreAvailable\": false,\r\n  \"sessions\": [\r\n   {\r\n     \"sessionId\": \"xxxxaxxexxxaxexdxxxdxxxe\",\r\n     \"botId\": \"st-ffeffxxx-xxxc-xexa-axxx-cxxabxxxxcxx\",\r\n     \"channel\": \"rtm\",\r\n     \"userId\": \"u-xxfexxxd-xxex-xdxe-xaec-xeaxbxxxxfxx\",\r\n     \"start_time\": \"2021-04-26T11:27:25.977Z\",\r\n     \"end_time\": \"2021-04-26T11:27:26.145Z\",\r\n     \"session_lang\": [\r\n       \"en\"\r\n      ],\r\n\t \"sessionType\": \"interactive\",\r\n         \"containmentType\": \"agent\", \r\n\t \"isDeveloper\": false,\r\n\t \"tags\": {\r\n\t\t\"userTags\": [],\r\n\t\t\"sessionTags\": []\r\n\t },\r\n\t \"noOfMessagesExchanged\": 7,\r\n\t \"noOfTasksExecuted\": 2\r\n\t}\r\n  ]\r\n}<\/pre>\n<\/li>\n
        • For one or more session Ids<\/strong>\n
          {\r\n    \"total\": 1,\r\n    \"moreAvailable\": false,\r\n    \"sessions\": [\r\n        {\r\n            \"sessionId\": \"6465cf6e4769ed4e822b82a1\",\r\n            \"botId\": \"st-dc600cf5-b1c5-581e-a2c3-eb81fe39c927\",\r\n            \"channel\": \"rtm\",\r\n            \"userId\": \"u-8c4ca335-3152-5622-9cbb-51c6daf6c12f\",\r\n            \"start_time\": \"2023-05-18T07:10:38.695Z\",\r\n            \"end_time\": \"2023-05-18T07:10:39.201Z\",\r\n            \"session_lang\": [\r\n                \"en\"\r\n            ],\r\n            \"sessionType\": \"interactive\",\r\n            \"isDeveloper\": false,\r\n            \"sessionStatus\": \"closed\",\r\n            \"tags\": {\r\n                \"userTags\": [],\r\n                \"sessionTags\": []\r\n            },\r\n            \"noOfMessagesExchanged\": 3,\r\n            \"noOfTasksExecuted\": 1,\r\n            \"containmentType\": \"selfService\"\r\n        }\r\n    ],\r\n    \"invalidSessions\": [\r\n        \"6465cf6e47Q9ed4e822b82a1\"\r\n    ]\r\n}<\/pre>\n<\/li>\n<\/ul>\n\r\n\t\t<\/div>\r\n\t<\/div>\r\n
          <\/div>\r\n\t
          \r\n\t\t
          \r\n\t\t\t
          Response Body Parameters<\/span><\/h2>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
          Parameter<\/th>\nDescription<\/th>\n<\/tr>\n
          total<\/td>\n\n
          The total number of records identified as per the API request parameters. The response will include a maximum of X records. If more than X records are identified, then the \u2018moreAvailable\u2019 field in the response will have the value as \u2018True\u2019.<\/p>\n
          It is recommended to programmatically iterate the request by dynamically updating the values of the \u2018skip\u2019 and \u2018limit\u2019 parameters in the request.<\/td>\n<\/tr>\n
          moreAvailable<\/td>\nIndicates if the API has returned all the records or if more are available, based on the pagination criteria.
          \nTrue<\/strong> if more records are available. False<\/strong> if there are no more records to be retrieved.<\/td>\n<\/tr>\n
          sessions<\/td>\nContains complete information about the session.<\/td>\n<\/tr>\n
          sessions.sessionId<\/td>\nThe unique identifier for the session record.<\/td>\n<\/tr>\n
          sessions.botId<\/td>\nBot ID or Stream ID.<\/td>\n<\/tr>\n
          sessions.channel<\/td>\nThe channel in which the end user is having the conversation: sms, email, rtm, slack, skype, twitter, msteams, api, kore, facebook, or skypeforbusiness.<\/td>\n<\/tr>\n
          sessions.userId<\/td>\nThe user Id of the end user who is having a conversation with the bot.<\/td>\n<\/tr>\n
          sessions.start_time<\/td>\nThe start time of the session. (ISO Date format YYYY-MM-DDThh:mm:ss.mmmZ)<\/td>\n<\/tr>\n
          sessions.end_time<\/td>\nThe end time of the session. (ISO Date format YYYY-MM-DDThh:mm:ss.mmmZ)<\/td>\n<\/tr>\n
          sessions.session_lang<\/td>\nAll the languages in which the conversation happened during the session.<\/td>\n<\/tr>\nsessions.sessionType<\/td>\n\n
          The type to filter the conversations:<\/p>\n
            \n
          • non-interactive \u2013 sessions having only bot messages, no message from the user.<\/li>\n
          • interactive \u2013 sessions having one or more messages from the user.<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n
          sessions.containmentType<\/td>\nUsed to filter the results based on the type of the session: selfservice, dropOff, or agent.<\/td>\n<\/tr>\n
          sessions.isDeveloper<\/td>\nInforms whether the session was initiated by a developer; 1 for Yes, 0 for No.<\/td>\n<\/tr>\n
          sessions.sessionStatus<\/td>\nThe status of the session – active or closed.<\/td>\n<\/tr>\n
          sessions.tags<\/td>\nMeta tags to filter the sessions.<\/td>\n<\/tr>\n
          sessions.tags.userTags<\/td>\nUser tags object; custom tags added to the user’s profile information.<\/td>\n<\/tr>\n
          sessions.tags.userTags.value<\/td>\nTag’s value.<\/td>\n<\/tr>\n
          sessions.tags.userTags.name<\/td>\nTag’s name.<\/td>\n<\/tr>\n
          sessions.tags.sessionTags<\/td>\nSession tags object; custom tags added to the conversation session.<\/td>\n<\/tr>\n
          sessions.tags.sessionTags.value<\/td>\nTag’s value.<\/td>\n<\/tr>\n
          sessions.tags.sessionTags.name<\/td>\nTag’s name.<\/td>\n<\/tr>\n
          sessions.noOfMessagesExchanged<\/td>\nThe number of messages exchanged in the session.<\/td>\n<\/tr>\n
          sessions.noOfTasksExecuted<\/td>\nThe number of tasks executed in the session.<\/td>\n<\/tr>\n
          invalidSessions<\/td>\nAn array listing session IDs that were not found.<\/td>\n<\/tr>\n<\/thead>\n<\/table>\n\r\n\t\t<\/div>\r\n\t<\/div>\r\n
          <\/div><\/div><\/div><\/div><\/div><\/div><\/section>
          <\/div><\/div><\/div><\/div><\/div><\/section>\n","protected":false},"excerpt":{"rendered":"This API retrieves the conversation sessions created. It returns information such as session metadata, user and bot identifiers, session duration, language, status, and other relevant metrics. Method POST Endpoint https:\/\/{{host}}\/api\/public\/bot\/{{BotID}}\/getSessions?containmentType={{containmentType}} and https:\/\/{{host}}\/api\/public\/getSessions?containmentType={{containmentType}}for BAC Content Type application\/json Authorization auth: {{JWT}} See How to generate the JWT Token. API Scope Bot Builder: Bot Sessions OR Admin Console:...","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[17],"tags":[],"class_list":["post-21343","post","type-post","status-publish","format-standard","hentry","category-api-guide"],"_links":{"self":[{"href":"https:\/\/developer.kore.ai\/v10-1\/wp-json\/wp\/v2\/posts\/21343","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developer.kore.ai\/v10-1\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/developer.kore.ai\/v10-1\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/developer.kore.ai\/v10-1\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/developer.kore.ai\/v10-1\/wp-json\/wp\/v2\/comments?post=21343"}],"version-history":[{"count":55,"href":"https:\/\/developer.kore.ai\/v10-1\/wp-json\/wp\/v2\/posts\/21343\/revisions"}],"predecessor-version":[{"id":58090,"href":"https:\/\/developer.kore.ai\/v10-1\/wp-json\/wp\/v2\/posts\/21343\/revisions\/58090"}],"wp:attachment":[{"href":"https:\/\/developer.kore.ai\/v10-1\/wp-json\/wp\/v2\/media?parent=21343"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/developer.kore.ai\/v10-1\/wp-json\/wp\/v2\/categories?post=21343"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/developer.kore.ai\/v10-1\/wp-json\/wp\/v2\/tags?post=21343"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}