{"id":21333,"date":"2019-06-04T05:46:49","date_gmt":"2019-06-04T04:46:49","guid":{"rendered":"https:\/\/developer.kore.ai\/v10\/?p=21333"},"modified":"2024-07-22T13:18:03","modified_gmt":"2024-07-22T12:18:03","slug":"conversation-history-api","status":"publish","type":"post","link":"https:\/\/developer.kore.ai\/v10\/docs\/bots\/api-guide\/conversation-history-api\/","title":{"rendered":"Conversation History API"},"content":{"rendered":"
\r\n\t
\r\n\t\t
\r\n\t\t\t

To fetch the conversational messages between the bot and user in reverse chronological order. This API supports pagination. You can provide offset\/skip and limit to get a certain number of messages at a time.<\/p>\n

This is a newer version of the old API<\/a> which will be deprecated soon. This revised API addresses the limitation of the older version on Botkit enablement or Agent Transfer.<\/p>\n\n\n\n\n\n\n\n
Method<\/strong><\/td>\nGET and POST<\/td>\n<\/tr>\n
Endpoint<\/strong><\/td>\nGET method<\/strong>: https:\/\/{{host}}\/api\/public\/bot\/{{BotID}}\/getMessages?userId={{userID}}&skip=10&limit=10<\/code><\/p>\n

Note<\/strong>: By default the GET method shows the RTM interactions. If you want to retrieve any channel interaction, you must pass the channelType parameter in the GET method. For example, to retrieve the WebHook channel interactions, enter channelType = IVR in the GET call. For the channelType parameter values, see Request Body Parameters <\/a> section.
\nPOST method<\/strong> https:\/\/{{host}}\/api\/public\/bot\/{{BotID}}\/getMessages<\/code>
\nand https:\/\/{{host}}\/api\/public\/getMessages<\/code> for Bot Admin Console.
\nNote<\/strong>: A POST method call can also be used to include Session-Id and MetaTags in the retrieved Conversation History.<\/td>\n<\/tr>\n

Content Type<\/strong><\/td>\napplication\/json<\/code><\/td>\n<\/tr>\n
Authorization<\/strong><\/td>\nauth: {{JWT}}<\/code><\/p>\n

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

API Scope<\/strong><\/td>\n\n
    \n
  • \n
      \n
    • Bot Builder: Chat History<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n

      OR<\/p>\n

        \n
      • Admin Console: Bot Analytics > Chat History<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n<\/tbody>\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><\/div><\/section>
        \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>\nRequired\/Optional<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
        host<\/td>\nRequired<\/td>\nEnvironment URL, for example, https:\/\/bots.kore.ai<\/td>\n<\/tr>\n
        BotID<\/td>\nOptional<\/td>\nBot ID or Stream ID. You can access it from the General Settings page of the bot.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

         <\/p>\n

        Sample Request<\/span><\/h2>\n

        Sample Request for GET Method<\/strong><\/p>\n

        curl -X GET \\\r\n'https:\/\/bots.kore.ai\/api\/public\/bot\/{{BotId}}\/getMessages?userId=u-XXX-XXX&\r\nchannelType=ivr&dateFrom=2019-04-01&dateTo=2019-04-05' \\ \r\n-H 'auth: {{YOUR_JWT_ACCESS_TOKEN}}'\r\n<\/pre>\n
        Sample Request for POST method<\/strong><\/p>\n
        curl -X POST \\\r\n  'https:\/\/{{host}}\/api\/public\/bot\/{{botId}}\/getMessages' \\\r\n  --header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \\\r\n  --header 'Content-Type: application\/json' \\\r\n  --data '{\r\n    \"userId\"           : \"u-xxxx-xxxxx-xxxx\",\r\n\t\"skip\"             : 0,                           \r\n\t\"limit\"            : 100,                       \r\n\t\"dateFrom\"         : \"2019-04-01\",\r\n\t\"dateTo\"           : \"2019-04-01\",\r\n\t\"channelType\"      : \"rcs\",\r\n\t\"sessionId\"        : [\"5eadxxxxxxxxxxxxx\",\"5ebxxxxxxxxxxxxxxx\"],\r\n\t\"tags\"\t         : {\r\n\t\t          \"and\"   : [\r\n\t\t\t            {\r\n\t\t\t              \"name\"  : \"tagname\",\r\n\t\t\t              \"values\"  : [\"tagvalue1\",\"tagvalue2\"],\r\n                                      \"type\"    : \"tagtype\"\r\n                                     },\r\n                                   {\r\n                                    \"name\"  : \"tagname\",\r\n    \t\t\t            \"values\"  : [\"tagvalue1\",\"tagvalue2\"],\r\n                                    \"type\"    : \"tagtype\"  \r\n                                   }\r\n                                  ]\t\r\n                       }\r\n           }'\r\n<\/pre>\n
        Request Query Parameters<\/span><\/h2>\n\n\n\n\n\n\n\n
        Parameter<\/th>\nRequired\/Optional<\/th>\nDescription<\/th>\n<\/tr>\n
        channelType<\/td>\nrequired<\/td>\nChannel type name for which you want to see the interactions; the default is “rtm” .<\/p>\n
        Accepted channel types are:<\/p>\n
          \n
        • “skypeforbusiness”,<\/li>\n
        • “msteams”,<\/li>\n
        • “twitter”,<\/li>\n
        • “spark”,<\/li>\n
        • “rtm”,<\/li>\n
        • “facebook”,<\/li>\n
        • “slack”,<\/li>\n
        • “skype”,<\/li>\n
        • “kore”,<\/li>\n
        • “email”,<\/li>\n
        • “sms”,<\/li>\n
        • “wfacebook”,<\/li>\n
        • “ringcentral”,<\/li>\n
        • “jabber”,<\/li>\n
        • “yammer”,<\/li>\n
        • “alexa”,<\/li>\n
        • “twiliovoice”,<\/li>\n
        • “telegram”,<\/li>\n
        • “ivr”,<\/li>\n
        • “ivrVoice”,<\/li>\n
        • “line”,<\/li>\n
        • “liveperson”,<\/li>\n
        • “googleactions”,<\/li>\n
        • “hangoutchat”,<\/li>\n
        • “mattermost”,<\/li>\n
        • “rcs”.<\/li>\n<\/ul>\n
          Note<\/b>: In case of multi-webhook channel configuration, \u201civr\u201d gives the conversations for the first WebHook instance. For other WebHoo instance, specify theivrInstID<\/code>, you can get it from the WebHook URL which is of the form: {{host_url}}\/chatbot\/hooks\/{{BotId}}\/hookInstance\/{{ivrInstID}}<\/code>)<\/td>\n<\/tr>\n
        userId<\/td>\nrequired for GET<\/p>\n
        optional for POST<\/td>\n
        		The ID of the user whose conversation history to access. Can be user email id or enterprise assigned unique id.<\/td>\n<\/tr>\n
        dateFrom<\/td>\noptional<\/td>\nAccepts the yyyy-mm-dd date format.
        \n(or) yyyy-mm-ddThh:mm:ss.msZ
        \neg:2019-04-01 (or) 2019-04-01T13:25:58.515ZIf not provided, calculated as 7 days behind dateTo<\/em>.
        \nNote<\/b>: This field cannot be used in combination with msgId.<\/td>\n<\/tr>\n
        dateTo<\/td>\noptional<\/td>\nAccepts the yyyy-mm-dd date format.
        \n(or) yyyy-mm-ddThh:mm:ss.msZ
        \neg:2019-04-01 (or) 2019-04-01 T13:26:05.598ZIf not provided, calculated as 7 days from dateFrom<\/em>. If dateFrom<\/em> is also not provided then set to Today<\/strong>.
        \nNote<\/b>: This field cannot be used in combination with msgId<\/td>\n<\/tr>\n<\/thead>\n<\/table>\n
        \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<\/div>\n
         <\/p>\n
        Request Body Parameters<\/span><\/h2>\n\n\n\n\n\n\n\n\n\n\n
        Parameter<\/th>\nRequired\/Optional<\/th>\nDescription<\/th>\n<\/tr>\n
        skip\/offset<\/td>\noptional<\/td>\nThe number of messages to be skipped.<\/td>\n<\/tr>\n
        limit<\/td>\noptional<\/td>\nThe number of messages to be shown on each page.<\/td>\n<\/tr>\n
        forward<\/td>\noptional<\/td>\nTakes string values – “true” or “false”. Specifies the direction of the messages to be retrieved.<\/span><\/p>\n
          \n
        • If the value is “true”, then the conversation history is retrieved in the order old to the most recent one.<\/span><\/li>\n
        • If the value is “false,” then the conversation history is retrieved in reverse order, from the most recent to the oldest message.<\/li>\n<\/ul>\n<\/td>\n<\/tr>\n
        msgId<\/td>\noptional<\/td>\nA specific Message-Id if known. This would fetch the records starting from that message either forward or backward depending upon the direction (see below) requested.<\/p>\n
        In case only the specific conversation is required, set the limit to 1<\/p>\n
        Note<\/u>: This field cannot be used in combination with dateFrom and dateTo.<\/td>\n<\/tr>\n
        direction<\/td>\noptional when msgId is given<\/td>\n\n
          \n
        • <0 reverse<\/li>\n
        • =0 bidirectional<\/li>\n
        • >0 forward<\/li>\n<\/ul>\n
          Default direction is forward.<\/td>\n<\/tr>\n
        sessionId<\/td>\noptional<\/td>\nA specific Session-Id if known. Refer here to obtain the session id<\/a><\/td>\n<\/tr>\n
        tags<\/td>\noptional<\/td>\nMeta tags to filter the conversations.<\/td>\n<\/tr>\n<\/thead>\n<\/table>\n
         <\/p>\n
        Sample Response<\/span><\/h2>\n
        Sample response for the GET method<\/strong><\/p>\n
        {\r\n\"total\": 1,\r\n\"moreAvailable\": false,\r\n\"icon\": \"https:\/\/dlnwzkim0wron.cloudfront.net\/f-87c47629-7exxxxxxxx-a807ccfb1cf0.png\",\r\n\"messages\": [\r\n{\r\n\"_id\": \"ms-9de62385-c8bd-5053-86c2-7axxxxxxxxxx72\",\r\n\"channels\": [\r\n{\r\n\"to\": \"st-3dfe0cc0-6c34-5b46-bb15xxxxxxxcf\",\r\n\"type\": \"ivr\",\r\n\"channelDispName\": \"WW\"\r\n}\r\n],\r\n\"type\": \"incoming\",\r\n\"status\": \"received\",\r\n\"createdBy\": \"u-47d826af-3a83-51f7-a049-dexxxxxx\",\r\n\"lmodifiedBy\": \"u-47d826af-3a83-51f7-a049-dexxxxxxx\",\r\n\"createdOn\": \"2023-03-28T11:06:38.793Z\",\r\n\"lmodifiedOn\": \"2023-03-28T11:06:38.793Z\",\r\n\"botId\": \"st-3dfe0cc0-6c34-5b46-bb15-bf2dxxxxxxf\",\r\n\"orgId\": \"o-312ffdea-4dbc-56e9-abfa-1d2xxxxxxx8\",\r\n\"accountId\": \"61f8ea4799bf74163xxxxxxx35\",\r\n\"isBB\": 0,\r\n\"ms\": 1,\r\n\"chnl\": \"ivr\",\r\n\"isD\": 0,\r\n\"components\": [\r\n{\r\n\"_id\": \"cp-4b3b4800-5d5a-5179-a9dc-c09dxxxxxxx91\",\r\n\"cT\": \"text\",\r\n\"data\": {\r\n\"text\": \"hi\"\r\n},\r\n\"thumbnails\": []\r\n}\r\n],\r\n\"timestampValue\": 1680001598803,\r\n\"__v\": 0,\r\n\"lang\": \"en\",\r\n\"sT\": 1,\r\n\"sessionId\": \"6422ca31a7cf935ce74ec355\",\r\n\"EOD\": 3,\r\n\"nodeType\": 3,\r\n\"tr0_I\": \"smalltalk_9f46b71b:3a74d188fe43591674878c8d958f0299\",\r\n\"tr_pId\": \"dg-30c18288-694b-5e27-8744-c27fxxxxxxxe:nd-msg-4944e1d5-26b9-4cda-b219-016e57b7e905:2cxxxxxxx06a98a4b40ce6bf35adfb3b\",\r\n\"cluster_id\": \"Others\",\r\n\"resourceid\": \"messagestore\",\r\n\"tags\": {\r\n\"messageTags\": [],\r\n\"userTags\": [],\r\n\"sessionTags\": [\r\n{\r\n\"value\": \"rr\",\r\n\"name\": \"ss\"\r\n}\r\n]\r\n}\r\n}\r\n]\r\n}\r\n<\/pre>\n
        Sample Response from POST method:<\/strong><\/p>\n
        {\r\n  \"total\": 1,\r\n  \"moreAvailable\": false,\r\n  \"messages\"  : [\r\n                {\r\n                  \"_id\": \"ms-xxxxxxxxxxxxxxxxxxxx\",\r\n                  \"type\": \"incoming\",\r\n                  \"status\": \"sent to cs\",\r\n                  \"createdBy\":\"u-xxxxxxxxxxxxxxxxxxx\",\r\n                  \"lmodifiedBy\": u-xxxxxxxxxxxxxxxxxxx\",\r\n                  \"lmodifiedOn\": \"2019-04-10T10:21:45.103Z\",\r\n                  \"channels\": [\r\n                     {\r\n                      \"type\": \"rcs\"\r\n                        }\r\n                     ],\r\n                  \"botId\":\"st-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\r\n                  \"orgId\": \u201co-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\r\n                  \"accountId\": \"5xxxxxxxxxxxxxxxxxxxxxxxx\",\r\n                  \"isBB\": 0,\r\n                  \"ms\": 1,\r\n                  \"channel\": \"rcs\",\r\n                  \"components\": [\r\n                    {\r\n                      \"_id\":\"cp-xxxxxxxxxxx\",\r\n                      \"cT\": \"text\",\r\n                      \"data\": {\r\n                          \"text\": \"23\"\r\n                           },\r\n                      \"thumbnails\": []\r\n                      }\r\n                    ],\r\n                    \"createdOn\": \"2019-04-10T10:21:45.106Z\",\r\n                    \"timestampValue\": 1554891705106,\r\n                    \"__v\": 0,\r\n                    \"sessionId\": \"5cadbefc6a81a71559f6bece\"\r\n               }\r\n             ]\r\n }\r\n<\/pre>\n
        <\/div><\/div>\n\r\n\t\t<\/div>\r\n\t<\/div>\r\n<\/div><\/div><\/div><\/div><\/div><\/section>
        \r\n\t
        \r\n\t\t
        \r\n\t\t\t
         <\/p>\n
        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\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>\nThe 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
        icon<\/td>\nThe URL of the bot logo.<\/td>\n<\/tr>\n
        messages<\/td>\nContains complete information about the message.<\/td>\n<\/tr>\n
        messages._id<\/td>\nThe unique identifier for the message record.<\/td>\n<\/tr>\n
        messages.type<\/td>\nThe message type – incoming (user input) or outgoing (bot response).<\/td>\n<\/tr>\n
        messages.status<\/td>\nProcessing status of the message: received, queued, in progress, delivered, or pending.<\/td>\n<\/tr>\n
        messages.lmodifiedOn<\/td>\nThe last modified time for the record.<\/td>\n<\/tr>\n
        messages.createdBy<\/td>\nThe user ID of the end user who was chatting with the bot.<\/td>\n<\/tr>\n
        messages.channels<\/td>\nThe channels object provides additional information about the channel through which the conversation was initiated.<\/td>\n<\/tr>\n
        messages.channels.type<\/td>\nName of the channel through which the conversation is initiated. The default is ‘rtm’.<\/td>\n<\/tr>\n
        messages.channels.channelUId<\/td>\nThe end-user’s identity provided by the channel.<\/td>\n<\/tr>\n
        messages.components<\/td>\nAdditional information about the message record.<\/td>\n<\/tr>\n
        messages.components._id<\/td>\nThe unique id of the component.<\/td>\n<\/tr>\n
        messages.components.cT<\/td>\nType of the user input (component type): text, audio, video, image, attachment, contact, task, filelink, location, email, alert, action, timeline, meeting, error, upgrade, NLResponse, or contextUpdate.<\/td>\n<\/tr>\n
        messages.components.data<\/td>\nThe data object.<\/td>\n<\/tr>\n
        messages.components.data.text<\/td>\nThe message shown to the user or the bot, depending on the message type.<\/td>\n<\/tr>\n
        messages.components.thumbnails<\/td>\nThe thumbnails object.<\/td>\n<\/tr>\n
        messages.components.thumbnails._id<\/td>\nThe unique id of the thumbnails.<\/td>\n<\/tr>\n
        messages.components.thumbnails.width<\/td>\nThe width of the thumbnails.<\/td>\n<\/tr>\n
        messages.components.thumbnails.height<\/td>\nThe height of the thumbnails.<\/td>\n<\/tr>\n
        messages.components.thumbnails.size<\/td>\nThe size of the thumbnails.<\/td>\n<\/tr>\n
        messages.components.thumbnails.url<\/td>\nThe URL of the thumbnails.<\/td>\n<\/tr>\n
        messages.botId<\/td>\nBot ID or Stream ID.<\/td>\n<\/tr>\n
        messages.orgId<\/td>\nThe organization ID to which the bot belongs to.<\/td>\n<\/tr>\n
        messages.accountId<\/td>\nThe account id to which the bot belongs to.<\/td>\n<\/tr>\n
        messages.isBB<\/td>\nInforms whether the conversation was initiated from the Bot Builder; 1 for Yes, 0 for No.<\/td>\n<\/tr>\n
        messages.isD<\/td>\nInforms whether the conversation was initiated by a developer; 1 for Yes, 0 for No.<\/td>\n<\/tr>\n
        messages.lang<\/td>\nThe conversation’s language.<\/td>\n<\/tr>\n
        messages.ms<\/td>\nMessage source; enum[0,1,2,3]; 0-task alert, 1-text, 2-task(action), and 3-others.<\/td>\n<\/tr>\n
        messages.chnl<\/td>\nThe end user’s conversation channel.<\/td>\n<\/tr>\n
        messages.createdOn<\/td>\nThe record creation date.<\/td>\n<\/tr>\n
        messages.timestampValue<\/td>\nThe creation date converted into the timestamp format.<\/td>\n<\/tr>\n
        messages.__v<\/td>\nThe field is used for internal purposes. No specific significance.<\/td>\n<\/tr>\n
        messages.resourceid<\/td>\nThe field is used for internal purposes. No specific significance.<\/td>\n<\/tr>\n
        messages.tags<\/td>\nMeta tags to filter the conversations.<\/td>\n<\/tr>\n
        messages.tags.messageTags<\/td>\nMessage tags object; custom tags added to the message in the conversation.<\/td>\n<\/tr>\n
        messages.tags.messageTags.value<\/td>\nTag’s value.<\/td>\n<\/tr>\n
        messages.tags.messageTags.name<\/td>\nTag’s name.<\/td>\n<\/tr>\n
        messages.tags.userTags<\/td>\nUser tags object; custom tags added to the user’s profile information.<\/td>\n<\/tr>\n
        messages.tags.userTags.value<\/td>\nTag’s value.<\/td>\n<\/tr>\n
        messages.tags.userTags.name<\/td>\nTag’s name.<\/td>\n<\/tr>\n
        messages.tags.sessionTags<\/td>\nSession tags object; custom tags added to the conversation session.<\/td>\n<\/tr>\n
        messages.tags.sessionTags.value<\/td>\nTag’s value.<\/td>\n<\/tr>\n
        messages.tags.sessionTags.name<\/td>\nTag’s name.<\/td>\n<\/tr>\n<\/thead>\n<\/table>\n\r\n\t\t<\/div>\r\n\t<\/div>\r\n<\/div><\/div><\/div><\/div><\/div><\/section>
        <\/div><\/div><\/div><\/div><\/div><\/div><\/section>\n","protected":false},"excerpt":{"rendered":"To fetch the conversational messages between the bot and user in reverse chronological order. This API supports pagination. You can provide offset\/skip and limit to get a certain number of messages at a time. This is a newer version of the old API which will be deprecated soon. This revised API addresses the limitation of...","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-21333","post","type-post","status-publish","format-standard","hentry","category-api-guide"],"_links":{"self":[{"href":"https:\/\/developer.kore.ai\/v10\/wp-json\/wp\/v2\/posts\/21333","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developer.kore.ai\/v10\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/developer.kore.ai\/v10\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/developer.kore.ai\/v10\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/developer.kore.ai\/v10\/wp-json\/wp\/v2\/comments?post=21333"}],"version-history":[{"count":67,"href":"https:\/\/developer.kore.ai\/v10\/wp-json\/wp\/v2\/posts\/21333\/revisions"}],"predecessor-version":[{"id":56811,"href":"https:\/\/developer.kore.ai\/v10\/wp-json\/wp\/v2\/posts\/21333\/revisions\/56811"}],"wp:attachment":[{"href":"https:\/\/developer.kore.ai\/v10\/wp-json\/wp\/v2\/media?parent=21333"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/developer.kore.ai\/v10\/wp-json\/wp\/v2\/categories?post=21333"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/developer.kore.ai\/v10\/wp-json\/wp\/v2\/tags?post=21333"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}