{"id":17801,"date":"2016-07-12T13:58:24","date_gmt":"2016-07-12T13:58:24","guid":{"rendered":"http:\/\/apidocs.kore.com\/?post_type=docs&p=3754"},"modified":"2021-03-17T10:36:26","modified_gmt":"2021-03-17T10:36:26","slug":"bots-platform-api-reference","status":"publish","type":"post","link":"https:\/\/developer.kore.ai\/v8-1\/docs\/bots\/sdks\/bots-platform-api-reference\/","title":{"rendered":"Web Socket Connect & RTM"},"content":{"rendered":"
\r\n\t
\r\n\t\t
\r\n\t\t\t

Kore.ai SDK libraries use the web socket channel to communicate with Kore.ai Bots Platform. To initialize a web socket session, the Kore.ai SDKs use the following Bots Platform endpoints. When using the Kore.ai Bots Platform SDKs, only the JWT token must be generated and passed to the client SDK.<\/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

Initializing<\/span><\/h2>\n

This section describes how the Kore.ai SDKs initialize a web socket session and is for reference only.<\/p>\n

Prerequisites<\/span><\/h3>\n

The client app is registered and Client ID and Secret Key are\u00a0generated in the Kore.ai Bot Builder tool.<\/p>\n

Step1<\/strong><\/span><\/h3>\n

The JWT is generated at server side using client app credentials and user information. The JWT is passed\u00a0to the client\u00a0app.<\/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

Step 2<\/strong><\/span><\/h3>\n

The client app exchanges the JWT token for the accessToken<\/code>\u00a0on the\u00a0Bots Platform using the following Bots Platform endpoint.\u00a0<\/span>This section describes how to format the request to post a message in a chat\u00a0with the \/api\/1.1\/<\/span>oAuth<\/span>\/token\/jwtgrant<\/span><\/code>\u00a0endpoint based on\u00a0the following JSON syntax.<\/p>\n

POST
\nhttps:\/\/{{APIHost}}\/api\/1.1\/oAuth\/token\/jwtgrant<\/code><\/p>\n

{\r\n    \"assertion\": \u201c{{JWT Token}}\u201d,\r\n    \"botInfo\": {\r\n        \"chatBot\": \"{{Bot Name}}\",\r\n        \"taskBotId\": \"st-f74a3430-3b19-55a3-be41-1ab1a35c4685\"\r\n    }\r\n)<\/pre>\n
Sample cURL<\/strong><\/h4>\n
curl 'https:\/\/{{APIHost}}\/api\/1.1\/oAuth\/token\/jwtgrant' \\\r\n  -H 'content-type: application\/json' \u00a0\\\r\n  --data-binary '{\"assertion\":\"{JWT Token}}\",\"botInfo\":{\"chatBot\":\"{{Bot Name}}\",\"taskBotId\":\"st-f74a3430-3b19-55a3-be41-1ab1a35c4685\"}}<\/pre>\n
Response<\/h4>\n
The follow sample JSON response shows the accessToken<\/code> and user associated with that token.<\/p>\n
{\r\n   \"authorization\": {\r\n\t\"accessToken\": \"ZdV2OL_UZ_MvHog-rs8k9KJFNWBICvquSc3jpeaRDE_-\",\r\n                 \/\/ access token to user at \/api\/rtm\r\n\t\"token_type\": \"bearer\",\r\n\t\"expiresDate\": \"2019-06-28T06:52:23.160Z\",\r\n                \/\/expiry date for access token\r\n\t\"issuedDate\": \"2019-02-28T06:52:23.160Z\" \r\n               \/\/access token issuedDate\r\n\t},\r\n   \"userInfo\": {\r\n\t\"userId\": \"u-4f6c68e0-551a-5dd9-a33a-1af3dc9cadcc\", \r\n                 \/\/ user id which is unique for the user and can be used at bot messages api\r\n\t\"accountId\": \"5c66514d09ab3565deb2e30a\", \r\n                 \/\/ account id in which the user is present\r\n\t\"orgId\": \"o-88aad7f1-0d32-5765-93d7-f40c80402114\",\r\n                \/\/ organization id of the user\r\n\t\"identity\": \"cs-5b08ed1e-5fa7-5aaa-9c21-28bf8c90b739\/admin1212@qakore.xyz\", \r\n                \/\/identity of user from the channel perspective\r\n\t\"enrollType\": \"free\", \r\n                \/\/Enrollment type (Free\/ Paid etc)\r\n\t\"managedBy\": \"5c66514d09ab3565deb2e30a\", \r\n                \/\/(The account id)\r\n\t\"fName\": \"\", \r\n                \/\/first name of the user\r\n                \/\/ (fetched if the user is registered on the platform)\r\n\t\"lName\": \"\" \r\n                \/\/last name of the user\r\n                \/\/ (fetched if the user is registered on the platform)\r\n\t}\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
Step 3<\/strong><\/span><\/h3>\n
The client app acquires the web socket URL using the following endpoint.\u00a0This section describes how to format the request to get the web socket URL\u00a0with the \/api\/1.1\/rtm\/start<\/code>\u00a0endpoint based on\u00a0the following JSON syntax.<\/p>\n
Note:<\/strong> This URL is short lived and expires in 30 seconds. You must ensure it is used to connect before\u00a0expiration.<\/p>\n
POST
\nhttps:\/\/{{APIHost}}\/api\/1.1\/rtm\/start<\/code><\/p>\n
{\r\n    \"botInfo\": {\r\n        \"chatBot\": \"Twitter\",\r\n        \"taskBotId\": \"st-f74a3430-3b19-55a3-be41-1ab1a35c4685\"\r\n    }\r\n}<\/pre>\n
The accessToken<\/code>\u00a0is passed in the bearer<\/code> parameter in the Authorization header.<\/p>\n
Sample cURL<\/strong><\/h4>\n
curl 'https:\/\/{{APIHost}}\/api\/1.1\/rtm\/start' \\\r\n  -H 'content-type: application\/json' \\\r\n  -H 'Authorization: bearer {{accessToken}}' \\\r\n  --data-binary '{\"botInfo\":{\"chatBot\":\"{{Bot Name}}\",\"taskBotId\":\"st-f74a3430-3b19-55a3-be41-1ab1a35c4685\"}'<\/pre>\n
Response<\/h4>\n
The following sample JSON response shows the web socket URL.<\/p>\n
{\"url\":\"wss:\/\/xxx.yyy.com:443\/rtm\/bot?sid=GhKrtrEC61g7hAnmvKAVnJIHG0DS1Lzv\"}<\/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
RTM Events Reference<\/span><\/span><\/h2>\n
The following real-time events can be exchanged between the client app\u00a0and the Kore.ai Bots Platform<\/span><\/p>\n
RTM Client Events<\/span><\/span><\/h3>\n
This section describes the RTM Client Event JSON\u00a0responses sent to the Kore.ai Bots Platform from the client app over a web socket. Event Type:<\/strong>\u00a0\/bot.message<\/code> Description:<\/strong> Triggered when a user posts a message. The following payload is used to send a user-typed message to the Bots Platform.<\/p>\n
{\r\n    \"clientMessageId\": 1466692440896,\r\n    \"message\": {\r\n        \"body\": \"Here is the message.\",\r\n        \"attachments\": [\r\n\r\n      ]\r\n    },\r\n    \"resourceid\": \"\/bot.message\",\r\n    \"botInfo\": {\r\n        \"chatBot\": \"CNN\",\r\n        \"taskBotId\": \"st-8aaf0939-c34a-5976-8e2e-5c91e685b2ce\"\r\n    },\r\n    \"id\": 1466692440896\r\n}<\/pre>\n
RTM Server Events<\/span><\/span><\/h3>\n
This section describes the RTM Server Event JSON responses sent to the client app over a web socket.<\/span><\/p>\n
Event Type:<\/strong>\u00a0ack<\/code><\/p>\n
Description:<\/strong> An acknowledgment sent whenever an event is received from the client app. The following payload is used to acknowledge an event from the client app.<\/p>\n
{\r\n    \"ok\": true,\r\n    \"replyto\": 1466692440896,\r\n    \"message\": \"delivered\",\r\n    \"type\": \"ack\"\r\n}<\/pre>\n
Event Type:<\/strong>\u00a0bot_response<\/code><\/p>\n
Description:<\/strong> An acknowledgment sent whenever a message is processed from the client app. The following payload is sent when a message from the client app is processed.<\/p>\n
{\r\n    \"type\": \"bot_response\",\r\n    \"from\": \"bot\",\r\n    \"message\": [\r\n        {\r\n            \"type\": \"text\",\r\n            \"cInfo\": {\r\n                \"body\": \" Hi.  \"\r\n            }\r\n      }\r\n   ],\r\n    \"botInfo\": {\r\n        \"chatBot\": \"CNN\",\r\n        \"taskBotId\": \"st-8aaf0939-c34a-5976-8e2e-5c91e685b2ce\"\r\n    },\r\n    \"createdOn\": \"2016-06-23T14:34:00.025Z\",\r\n    \"icon\": \"https:\/\/devbots.kore.com\/api\/getMediaStream\/market\/f-683e82be-fc25-5921-bf41-4104780f71c2.png\"\r\n}<\/pre>\n
Event Type:<\/strong>\u00a0user_message<\/code><\/p>\n
Description:<\/strong>\u00a0Sent to the client app when a user enters and sends a message to the server from another simultaneous session. The following sample payload is sent to the client app.<\/p>\n
{\r\n    \"botInfo\": {\r\n        \"chatBot\": \"CNN\",\r\n        \"taskBotId\": \"st-8aaf0939-c34a-5976-8e2e-5c91e685b2ce\"\r\n    },\r\n    \"from\": \"self\",\r\n    \"message\": {\r\n        \"body\": \"how are you doing \",\r\n        \"attachments\": []\r\n    },\r\n    \"id\": 1466692871803,\r\n    \"type\": \"user_message\"\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
Get Conversation History<\/span><\/h2>\n
The client app requests the Bots platform endpoint \/api\/botmessages\/rtm?botId={{botId}}<\/code> using the access token as generated in Step 2 above to get the previous messages exchanged between the user and the chatbot. The response from the mentioned endpoint can be used to display the conversation history in the chat window.<\/p>\n
This section describes how to format the request to get the web socket URL with the \/api\/botmessages\/rtm<\/code> endpoint based on the following JSON syntax.<\/p>\n
GET\r\nhttps:\/\/{{APIHost}}\/api\/botmessages\/rtm?botId={{botId}}<\/pre>\n
Query Parameters<\/strong>:<\/p>\n