{"id":21333,"date":"2019-06-04T05:46:49","date_gmt":"2019-06-04T04:46:49","guid":{"rendered":"https:\/\/developer.kore.ai\/v8-1\/?p=21333"},"modified":"2021-02-05T11:01:51","modified_gmt":"2021-02-05T11:01:51","slug":"conversation-history-api","status":"publish","type":"post","link":"https:\/\/developer.kore.ai\/v8-1\/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

Fetches 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 soon be deprecated. This revised API addresses the limitation of the older version on enabling BotKit or Agent Transfer.<\/p>\n

To use this API, app needs the Bot Builder API scope of Chat History<\/em>.
\nOR the Admin API Scope of Chat History<\/em> under Bot Analytics<\/em>.<\/p>\n

GET<\/b>https:\/\/{{host}}\/api\/public\/bot\/{{BotID}}\/getMessages?userId={{userID}}&skip=10&limit=10<\/code><\/p>\n

A POST API call can also be used to include Session-Id and MetaTags in the retrieved Conversation History.<\/p>\n

POST<\/strong> https:\/\/{{host}}\/api\/public\/bot\/{{BotID}}\/getMessages<\/code>
\nand https:\/\/{{host}}\/api\/public\/getMessages<\/code> for Bot Admin Console<\/p>\n\r\n\t\t<\/div>\r\n\t<\/div>\r\n

<\/div><\/div>\r\n\t
\r\n\t\t
\r\n\t\t\t

Parameters<\/span><\/h3>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Parameter<\/th>\nDescription<\/th>\n<\/tr>\n
BotID (optional)<\/td>\nBot ID. You can access it from the bot\u2019s General Settings page.<\/td>\n<\/tr>\n
userId (mandatory for GET call
\noptional for POST call)<\/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
skip\/offset (optional)<\/td>\nThe number of messages to be skipped.<\/td>\n<\/tr>\n
limit (optional)<\/td>\nThe number of messages to be shown on each page.<\/td>\n<\/tr>\n
forward (optional)<\/td>\nTakes boolean values true\/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 the reverse order i.e, the most recent to the oldest message<\/span><\/li>\n<\/ul>\n<\/td>\n<\/tr>\n
dateFrom (optional)<\/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.515ZIf not provided, calculated as 7 days behind dateTo<\/em>.
\nNote<\/u>: This field cannot be used in combination with msgId.<\/td>\n<\/tr>\n
dateTo (optional)<\/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.598ZIf not provided, calculated as 7 days from dateFrom<\/em>. If dateFrom<\/em> is also not provided then set to Today<\/strong>.
\nNote<\/u>: This field cannot be used in combination with msgId<\/td>\n<\/tr>\n
channelType (optional)<\/td>\nName of the channel of whose conversation history is needed, default is \u2018rtm\u2019 <\/span>.<\/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<\/u>: In case of multi-webhook channel configuration, “ivr” will give the conversations for the first WebHook instance. For those related to other instance, specify the ivrInstID<\/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

msgId (optional)<\/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 (optional 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 (optional)<\/td>\nA specific Session-Id if known. Refer here to obtain the session id<\/a><\/td>\n<\/tr>\n
tags (optional)<\/td>\nMeta tags to filter the conversations.<\/td>\n<\/tr>\n<\/thead>\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><\/div>\r\n\t
\r\n\t\t
\r\n\t\t\t

Authorization<\/span><\/h3>\n

Invoke the API with JWT in the header with the following syntax:<\/p>\n

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

<\/div><\/div>\r\n\t
\r\n\t\t
\r\n\t\t\t

Response content type<\/span><\/h3>\n

application\/JSON<\/code><\/p>\n\r\n\t\t<\/div>\r\n\t<\/div>\r\n

<\/div><\/div>\r\n\t
\r\n\t\t
\r\n\t\t\t

Sample Request<\/span><\/h3>\n
curl -X GET \\\r\n'https:\/\/bots.kore.ai\/api\/public\/bot\/{{BotId}}\/getMessages?userId=u-XXX-XXX&\r\nchannelType=facebook&dateFrom=2019-04-01&dateTo=2019-04-05' \\ \r\n-H 'auth: {{YOUR_JWT_ACCESS_TOKEN}}'<\/pre>\n
Sample Request for POST call<\/strong><\/p>\n
curl -X POST \\\r\n  https:\/\/bots.kore.ai\/api\/public\/getMessages \\\r\n  -H 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \\\r\n  -d '{\r\n        userId           : u-xxxx-xxxxx-xxxx\r\n\tskip             : 0,                           \r\n\tlimit            : 100,                       \r\n\tdateFrom         : \u201c2019-04-01\u201d  (or)  \u201c2019-04-01T13:25:58.515Z\u201d,\r\n\tdateTo           : \u201c2019-04-01\u201d  (or)  \u201c2019-04-01T13:25:58.515Z\u201d,\r\n\tchannelType      : \u201crcs\u201d,\r\n\tsessionId        : [\u201c5eadxxxxxxxxxxxxx\u201d,\u201d5ebxxxxxxxxxxxxxxx\u201d],\r\n\ttags\t         : {\r\n\t\t          and   : [\r\n\t\t\t            {\r\n\t\t\t              \u201cname\u201d  : \u201dtagname\u201d,\r\n\t\t\t              \u201cvalues\u201d  : [\u201ctagvalue1\u201d,\u201dtagvalue2\u201d],\r\n                                      \u201ctype\u201d    : \u201ctagtype\u201d \/\/ user\/message\/session\t\r\n                                     },\r\n                                   {\r\n                                    \u201cname\u201d  : \u201dtagname\u201d,\r\n    \t\t\t            \u201cvalues\u201d  : [\u201ctagvalue1\u201d,\u201dtagvalue2\u201d],\r\n                                    \u201ctype\u201d    : \u201ctagtype\u201d  \/\/ user\/message\/session\t\r\n                                   }\r\n                                  ]\t\r\n                       }\r\n           }\r\n<\/pre>\n\r\n\t\t<\/div>\r\n\t<\/div>\r\n
<\/div><\/div>\r\n\t
\r\n\t\t
\r\n\t\t\t
Sample Response<\/span><\/h3>\n
{\r\n    \"total\": 1,\r\n    \"moreAvailable\": false,\r\n    \"messages\": [\r\n        {\r\n            \"_id\": \"ms-e172XXXXXX9a492cd2\",\r\n            \"type\": \"outgoing\",\r\n            \"status\": \"pending\",\r\n            \"lmodifiedOn\": \"2019-04-01T13:25:58.512Z\",\r\n            \"createdBy\": \"u-dfb0a15XXXXXXXXX6afa4c74d\",\r\n            \"channels\": [\r\n                {\r\n                    \"type\": \"rcs\"\r\n                }\r\n            ],\r\n            \"components\": [\r\n                {\r\n                    \"_id\": \"cp-4fbXXXXXXXXXX6ebdd586531\",\r\n                    \"cT\": \"text\",\r\n                    \"data\": {\r\n                        \"text\": \"Thanks! I now have access to your Kore Assistant account. Don\u2019t worry, I never access your account without you asking me to do something for you.\"\r\n                    },\r\n                    \"thumbnails\": []\r\n                }\r\n            ],\r\n            \"botId\": \"st-fe7XXXXXX6e115e94c\",\r\n            \"orgId\": \"o-5a64XXXXXXXXXa58cd43460c3\",\r\n            \"accountId\": \"5c9c95bXXXXX23c523dbc\",\r\n            \"isBB\": 1,\r\n            \"ms\": 1,\r\n            \"chnl\": \"rcs\",\r\n            \"createdOn\": \"2019-04-01T13:25:58.515Z\",\r\n            \"timestampValue\": 1554125158515,\r\n            \"__v\": 0,\r\n            \"resourceid\": \"messagestore\",\r\n            \"tags\": {\r\n                \"messageTags\": [],\r\n                \"userTags\": [\r\n                    {\r\n                        \"value\": \"+919346804623\",\r\n                        \"name\": \"RCSID\"\r\n                    }\r\n                ],\r\n                \"sessionTags\": []\r\n            }        }\r\n    ]\r\n}<\/pre>\n
Sample Response from POST call:<\/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\": \"rtm\"\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\": \"rtm\",\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\r\n\t\t<\/div>\r\n\t<\/div>\r\n
<\/div><\/div><\/div><\/div><\/div><\/div><\/div><\/section>\n","protected":false},"excerpt":{"rendered":"Fetches 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 soon be deprecated. This revised API addresses the limitation of the...","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\/v8-1\/wp-json\/wp\/v2\/posts\/21333","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developer.kore.ai\/v8-1\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/developer.kore.ai\/v8-1\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/developer.kore.ai\/v8-1\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/developer.kore.ai\/v8-1\/wp-json\/wp\/v2\/comments?post=21333"}],"version-history":[{"count":24,"href":"https:\/\/developer.kore.ai\/v8-1\/wp-json\/wp\/v2\/posts\/21333\/revisions"}],"predecessor-version":[{"id":24608,"href":"https:\/\/developer.kore.ai\/v8-1\/wp-json\/wp\/v2\/posts\/21333\/revisions\/24608"}],"wp:attachment":[{"href":"https:\/\/developer.kore.ai\/v8-1\/wp-json\/wp\/v2\/media?parent=21333"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/developer.kore.ai\/v8-1\/wp-json\/wp\/v2\/categories?post=21333"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/developer.kore.ai\/v8-1\/wp-json\/wp\/v2\/tags?post=21333"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}