Kore.ai SDK ライブラリは、Kore.ai ボット プラットフォームとの通信に Web ソケット チャネルを使用します。Web ソケット セッションを初期化するために、Kore.ai SDK は以下の ボット プラットフォームのエンド ポイントを使用します。Kore.ai ボット プラットフォーム SDK を使用する場合は、JWT トークンのみを生成してクライアント SDK に渡す必要があります。
初期化
このセクションでは、Kore.ai SDK が Web ソケット セッションを初期化する方法について説明します。これは参照用です。
必要条件
クライアント アプリが登録され、Kore.ai ボットビルダー ツールでクライアント ID とシークレット キーが生成されます。
ステップ 1
JWT は、クライアント アプリの資格情報とユーザー情報を使用してサーバー側で生成されます。JWT はクライアント アプリに渡されます。
ステップ 2
クライアント アプリは、以下のボット プラットフォームのエンドポイントを使用して、ボット プラットフォーム上の accessToken 用に JWT トークンを交換します。このセクションでは、以下の JSON 構文に基づいて、 /api/1.1/oAuth/token/jwtgrant エンドポイントを使用してチャットにメッセージを投稿するリクエストのフォーマットについて説明します。 POST https://{{APIHost}}/api/1.1/oAuth/token/jwtgrant
{ "assertion": “{{JWT Token}}”, "botInfo": { "chatBot": "{{Bot Name}}", "taskBotId": "st-f74a3430-3b19-55a3-be41-1ab1a35c4685" } )
サンプル cURL
curl 'https://{{APIHost}}/api/1.1/oAuth/token/jwtgrant' \ -H 'content-type: application/json' \ --data-binary '{"assertion":"{JWT Token}}","botInfo":{"chatBot":"{{Bot Name}}","taskBotId":"st-f74a3430-3b19-55a3-be41-1ab1a35c4685"}}
レスポンス
以下のサンプル JSON レスポンスでは、 accessToken およびそのトークンに関連付けられたユーザーが表示されています。
{ "authorization": { "accessToken": "ZdV2OL_UZ_MvHog-rs8k9KJFNWBICvquSc3jpeaRDE_-", // access token to user at /api/rtm "token_type": "bearer", "expiresDate": "2019-06-28T06:52:23.160Z", //expiry date for access token "issuedDate": "2019-02-28T06:52:23.160Z" //access token issuedDate }, "userInfo": { "userId": "u-4f6c68e0-551a-5dd9-a33a-1af3dc9cadcc", // user id which is unique for the user and can be used at bot messages api "accountId": "5c66514d09ab3565deb2e30a", // account id in which the user is present "orgId": "o-88aad7f1-0d32-5765-93d7-f40c80402114", // organization id of the user "identity": "cs-5b08ed1e-5fa7-5aaa-9c21-28bf8c90b739/admin1212@qakore.xyz", //identity of user from the channel perspective "enrollType": "free", //Enrollment type (Free/ Paid etc) "managedBy": "5c66514d09ab3565deb2e30a", //(The account id) "fName": "", //first name of the user // (fetched if the user is registered on the platform) "lName": "" //last name of the user // (fetched if the user is registered on the platform) } }
ステップ 3
クライアント アプリは、以下のエンドポイントを使用して Web ソケットの URL を取得します。このセクションでは、以下の JSON 構文に基づいて、 /api/1.1/rtm/start エンドポイントを使用して Web ソケット URL を取得するリクエストのフォーマットについて説明します。
メモ: この URL は有効期間が短く、30 秒後に期限切れになります。有効期限が切れる前に、接続に使用されていることを確認する必要があります。
POST https://{{APIHost}}/api/1.1/rtm/start
{ "botInfo": { "chatBot": "Twitter", "taskBotId": "st-f74a3430-3b19-55a3-be41-1ab1a35c4685" }}
accessToken は、承認ヘッダーの bearer パラメータで渡されます。
サンプル cURL
curl 'https://{{APIHost}}/api/1.1/rtm/start' \ -H 'content-type: application/json' \ -H 'Authorization: bearer {{accessToken}}' \ --data-binary '{"botInfo":{"chatBot":"{{Bot Name}}","taskBotId":"st-f74a3430-3b19-55a3-be41-1ab1a35c4685"}'
レスポンス
以下の JSON レスポンスのサンプルは、Web ソケットの URL を示しています。
{"url":"wss://xxx.yyy.com:443/rtm/bot?sid=GhKrtrEC61g7hAnmvKAVnJIHG0DS1Lzv"}
RTM イベント リファレンス
クライアント アプリと Kore.ai ボット プラットフォームの間では、以下のようなリアルタイム イ ベントがやり取りされます。
RTM クライアント イベント
このセクションでは、クライアント アプリからWeb ソケット経由で Kore.ai ボット プラットフォームに送信される RTM クライアント イベントの JSON レスポンスについて説明します。イベント タイプ /bot.message 説明: ユーザーがメッセージを投稿したときにトリガーされました。以下のペイロードは、ユーザーが入力したメッセージを ボット プラットフォームに送信するために使用されます。
{ "clientMessageId": 1466692440896, "message": { "body": "Here is the message.", "attachments": [ ] }, "resourceid": "/bot.message", "botInfo": { "chatBot": "CNN", "taskBotId": "st-8aaf0939-c34a-5976-8e2e-5c91e685b2ce" }, "id": 1466692440896 }
RTM サーバー イベント
このセクションでは、Web ソケットを介してクライアント アプリに送信される RTM サーバー イベント JSON レスポンスについて説明します。イベント タイプ ack 説明：クライアント アプリからイベントを受信するたびに送信される受信確認。以下のペイロードは、クライアント アプリからのイベントを確認するために使用されます。
{ "ok": true, "replyto": 1466692440896, "message": "delivered", "type": "ack" }
イベント タイプ: bot_response 説明：クライアントアプリからのメッセージを処理するたびに送信される受信確認。以下のペイロードは、クライアント アプリからのメッセージを処理する際に送信されます。
{ "type": "bot_response", "from": "bot", "message": [ { "type": "text", "cInfo": { "body": " Hi." } } ], "botInfo": { "chatBot": "CNN", "taskBotId": "st-8aaf0939-c34a-5976-8e2e-5c91e685b2ce" }, "createdOn": "2016-06-23T14:34:00.025Z", "icon": "https://devbots.kore.com/api/getMediaStream/market/f-683e82be-fc25-5921-bf41-4104780f71c2.png" }
イベント タイプ: user_message 説明: ユーザーが別の同時セッションからサーバーにメッセージを入力して送信したときに、クライアント アプリに送信されます。以下のペイロードのサンプルが、クライアント アプリに送信されます。
{ "botInfo": { "chatBot": "CNN", "taskBotId": "st-8aaf0939-c34a-5976-8e2e-5c91e685b2ce" }, "from": "self", "message": { "body": "how are you doing ", "attachments": [] }, "id": 1466692871803, "type": "user_message" }
会話履歴の取得
クライアント アプリは、上記ステップ 2 で生成したアクセス トークンを使用して、ボット プラットフォームのエンドポイント /api/botmessages/rtm?botId={{botId}}にリクエストし、ユーザーとチャットボットの間で交わされた過去のメッセージを取得します。このエンドポイントからのレスポンスを使用して、チャット ウィンドウに会話の履歴を表示できます。このセクションでは、以下の JSON 構文に基づいて、 /api/botmessages/rtm エンドポイントを使用して Web ソケット URL を取得するリクエストのフォーマットについて説明します。
GET https://{{APIHost}}/api/botmessages/rtm?botId={{botId}}
クエリ パラメータ:
- botId (必須): ボット ID には、ボットの「一般設定」ページからアクセスできます。
- スキップ/オフセット（オプション）: スキップするメッセージの数。
- リミット（オプション）: 取得するメッセージの数。
- ヘッダーの 承認 パラメータとしてベアラーと一緒に渡される
accessToken
サンプル cURL
curl 'https://{{APIHost}}/api/botmessages/rtm?botId={{botId}}&limit=10' \ -H 'accept: application/json' \ -H 'Authorization: bearer -{{accessToken}}' \ -H 'content-type: application/json'
サンプル レスポンス
{ "total": 2, "moreAvailable": false, "messages": [ { "_id": "ms-8a83d099-dd93-5b6b-836b-ac77bdfe9d4a", "channels": [ { "type": "rtm" } ], "type": "incoming", "status": "sent to cs", "createdBy": "u-211f287f-17c8-51ac-b768-15c68e19afb2", "lmodifiedBy": "u-211f287f-17c8-51ac-b768-15c68e19afb2", "lmodifiedOn": "2019-12-03T05:07:44.008Z", "botId": "st-2f579dbf-9dc1-548c-972f-f19d33160a07", "orgId": "o-44741779-1971-5ab9-a0f7-aaf4e21dbe4e", "accountId": "5a675150ff600b3d7665d2a6", "isBB": 0, "ms": 1, "chnl": "rtm", "components": [ { "_id": "cp-1edc5033-a9cb-5011-8b2b-5986b7fa45cc", "cT": "text", "data": { "text": "Hi" }, "thumbnails": [ ] } ], "createdOn": "2019-12-03T05:07:44.097Z", "timestampValue": 1575349664097, "__v": 0, "lang": "en", "sessionId": "5de5eda04cdcff145752dbf6", "nodeType": 0, "tr0_I": "dg-61e5609f-76e7-5c42-b66f-7bb8b3af2433:intent0", "tr0_O": "dg-61e5609f-76e7-5c42-b66f-7bb8b3af2433:entity1:4a04988ee640428d1847fc433081be0b", "tr0_T": "0", "tr_isSS": 1, "resourceid": "messagestore", "tags": { "messageTags": [ ], "userTags": [ ], "sessionTags": [ ] } }, { "_id": "ms-80e8dbf3-ca69-5ee2-a2c1-1c6a70100c08", "channels": [ { "type": "rtm" } ], "type": "outgoing", "status": "pending", "lmodifiedOn": "2019-12-03T05:07:45.165Z", "createdBy": "u-211f287f-17c8-51ac-b768-15c68e19afb2", "components": [ { "_id": "cp-209a0641-130b-57ce-b0d3-d651691084bb", "cT": "text", "data": { "text": "Please enter the text to comment on the issue" }, "thumbnails": [ ] } ], "botId": "st-2f579dbf-9dc1-548c-972f-f19d33160a07", "orgId": "o-44741779-1971-5ab9-a0f7-aaf4e21dbe4e", "accountId": "5a675150ff600b3d7665d2a6", "tN": "Add Comment to Issue", "isBB": 0, "ms": 1, "chnl": "rtm", "lang": "en", "createdOn": "2019-12-03T05:07:45.171Z", "timestampValue": 1575349665171, "__v": 0, "sessionId": "5de5eda04cdcff145752dbf6", "resourceid": "messagestore", "tags": { "messageTags": [ ], "userTags": [ ], "sessionTags": [ ] } } ] }
次のステップ
ボット プラットフォーム API のエンドポイントおよび RTM イベントは、クライアント アプリまたは Kore.ai ボット SDK で使用できます。詳しくは、「Kore.ai ボット SDK」をご覧ください。