{"id":21333,"date":"2019-06-04T05:46:49","date_gmt":"2019-06-04T04:46:49","guid":{"rendered":"https:\/\/developer.kore.ai\/v9-3\/?p=21333"},"modified":"2022-12-29T15:07:41","modified_gmt":"2022-12-29T15:07:41","slug":"conversation-history-api","status":"publish","type":"post","link":"https:\/\/developer.kore.ai\/v9-3\/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 soon be deprecated. 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<\/td>\n<\/tr>\n
Endpoint<\/strong><\/td>\n\n

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

Note<\/strong>: A POST API call can also be used to include Session-Id and MetaTags in the retrieved Conversation History.
\nPOST https:\/\/{{host}}\/api\/public\/bot\/{{BotID}}\/getMessages<\/code>
\nand https:\/\/{{host}}\/api\/public\/getMessages<\/code> for Bot Admin Console.<\/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: Chat History<\/li>\n

    OR<\/p>\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
    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
     <\/p>\n
    Request Body Parameters<\/span><\/h2>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
    Parameter<\/th>\nRequired\/Optional<\/th>\nDescription<\/th>\n<\/tr>\n
    userId<\/td>\n\n
     required for GET call<\/p>\n
    optional 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<\/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>\n\n
    Takes 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<\/td>\noptional<\/td>\nTakes the date format yyyy-mm-dd
    (or) yyyy-mm-ddThh:mm:ss.msZ
    eg:2019-04-01 (or) 2019-04-01T13:25:58.515ZIf not provided, calculated as 7 days behind dateTo<\/em>.
    Note<\/u>: This field cannot be used in combination with msgId.<\/td>\n<\/tr>\n
    dateTo<\/td>\noptional<\/td>\nTakes the date format yyyy-mm-dd
    (or) yyyy-mm-ddThh:mm:ss.msZ
    eg: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>.
    Note<\/u>: This field cannot be used in combination with msgId<\/td>\n<\/tr>\n
    channelType<\/td>\noptional<\/td>\n\n
    Name 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<\/td>\noptional<\/td>\n\n
    A 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
    \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
    Sample Response<\/span><\/h2>\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
    <\/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>\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
    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 soon be deprecated. 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\/v9-3\/wp-json\/wp\/v2\/posts\/21333","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developer.kore.ai\/v9-3\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/developer.kore.ai\/v9-3\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/developer.kore.ai\/v9-3\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/developer.kore.ai\/v9-3\/wp-json\/wp\/v2\/comments?post=21333"}],"version-history":[{"count":57,"href":"https:\/\/developer.kore.ai\/v9-3\/wp-json\/wp\/v2\/posts\/21333\/revisions"}],"predecessor-version":[{"id":50218,"href":"https:\/\/developer.kore.ai\/v9-3\/wp-json\/wp\/v2\/posts\/21333\/revisions\/50218"}],"wp:attachment":[{"href":"https:\/\/developer.kore.ai\/v9-3\/wp-json\/wp\/v2\/media?parent=21333"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/developer.kore.ai\/v9-3\/wp-json\/wp\/v2\/categories?post=21333"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/developer.kore.ai\/v9-3\/wp-json\/wp\/v2\/tags?post=21333"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}