BotKit SDK の関数

Kore.ai BotKit SDK は、ボットの制御を強化し、ユーザー体験を向上させるために使用できる関数を提供しています。
BotKit SDKでは、以下の関数がサポートされています。

• sdk.sendUserMessage
• sdk.sendBotMessage
• sdk.AsyncResponse
• sdk.respondToHook
• sdk.saveData
• sdk.registerBot
• sdk.getSavedData
• sdk.getMessages
• sdk.resetBot
• sdk.startAgentSession
• sdk.clearAgentSession
• sdk.extendRequestId
• sdk.skipUserMessage
• sdk.skipBotMessage
• sdk.closeConversationSession

sdk.sendUserMessage

この関数は、メッセージをボット ユーザーに送信します。
使用方法
on_bot_message イベント コールバック内で使用します。on_bot_message イベントは、ボットがユーザーにレスポンスを送信すると、呼び出されます。SDK では、 message のようなペイロード データを変更し、ボット プラットフォームに送信することができます。
構文

sdk.sendUserMessage(payload, callback)

パラメータ:

• payload — 以下に示すような、JSON のレスポンス ペイロードです:

  { "message":"Spell-corrected message sent by bot to the user", "originalMessage":"Original message sent by bot to the user", "taskId":"Dialog task ID", "nodeId":"Current node ID in the dialog flow", "channel":"Channel name", "context": <context object> }

  上記のメッセージ ペイロードは、ユーザーの言語が検出され、スペルの修正が行われたときのものです。ユーザーの言語が検出されない場合は、以下のようなメッセージ構成になります。

  { "message":"Original message sent by bot to the user", "originalMessage":"Original message sent by bot to the user", "languageInfo": { "currentLanguage": "current user language", "detectedLanguages": [ "language detected 1", "language detected 2" ], "spellCorrectedInput": [ "language 1": "spell correction in language 1", "language 2": "spell correction in language 2" ] } }

• callback ー イベント完了時に呼び出される関数で、更新されたメッセージとコンテキストを ボット プラットフォームに送信します。

サンプル
次のコードスニペットは、 sdk.sendUserMessage 関数がユーザーにエラーを返すサンプルを示しています。

return sdk.sendUserMessage(payload, function(err){ if(err) console.log("err", err);

以下のコード サンプルでは、ユーザーがライブ エージェントに切り替わったときのユーザーへの初期メッセージを表示しています。

formdata.welcome_message = ""; var visitorId = _.get(payload, 'channel.channelInfos.from'); if (!visitorId) { visitorId = _.get(payload, 'channel.from'); } visitorId = payload.context.session.UserContext._id; userDataMap[visitorId] = payload; data.message = "An Agent will be assigned to you shortly!!!"; sdk.sendUserMessage(payload, callback);

次のコード サンプルでは、 sdk.sendUserMessage 関数でユーザーに送信されるメッセージは、ユーザーが選択した通貨変換に基づいています。isTemplate パラメータは、カスタム メッセージ フォーマットを使用するか、デフォルト メッセージ フォーマットを使用するかを決定します。

on_user_message : function(requestId, payload, callback) { message = payload.message.toLowerCase();console.log("MESSAGE",payload.message); //payload .context.session.BotContext.currency = "koko"; if ( message == "Yes" || message == "yes") { var overrideMessagePayload = { body : " Enter the currency code for which the amount will be converted", isTemplate :false }; data.overrideMessagePayload = overrideMessagePayload; currCode = true; return sdk.sendUserMessage(payload); } else if ( message == "No" || message == "no" ) { var overrideMessagePayload = { body : "Ok, Enter the country name so that I can fetch it on your behalf", isTemplate :false }; payload.overrideMessagePayload = overrideMessagePayload; countryname = true; return sdk.sendUserMessage(payload);

プラットフォームの Ver 8.0 のリリース後は、ユーザー、メッセージ、およびセッションのメタタグを追加できるようになりました。必要なペイロードの構文は以下のようになります:

metaTags":{ "userMetaTags":[ { "name":"<string>", "value":"<string>" } ], "sessionMetaTags":[ { "name":"<string>", "value":"<string>" } ], "messageMetaTags":[ { "name":"<string>", "value":"<string>" } ] }

sdk.sendBotMessage

<span style="font-weight: 400">この関数は、ボットにメッセージを送信します。</span><br /><strong>使用方法
使用法
on_user_message イベントコールバック内で使用されます。ユーザーがボットにメッセージを送信すると on_user_message イベントが呼び出されます。SDK では、 message のようなペイロード データを変更して、ボット プラットフォームに送信することができます。
ユーザー メッセージの検証チェックが行われます。メッセージは 3,000 文字以下で、各単語は 1,200 文字以下です。
構文:

sdk.sendBotMessage(payload, callback)

パラメータ:

• payload — 以下に示すような、JSON のレスポンス ペイロードです:

  { "message":"Message sent by the user", "channel":"Channel name", "context": <context object> }

• callback ー イベント完了時に呼び出される関数で、更新されたメッセージとコンテキストを ボット プラットフォームに送信します。

サンプル
以下のコードスニペットは、ユーザーのレスポンスをボットに送信します。

on_user_message: function(requestId, payload, callback) { sdk.sendBotMessage(payload, callback); },

この on_user_message の関数では、メッセージはユーザーに直接返され、ライブ エージェントへの転送でない場合は、ボットに送られます。

on_user_message: function(requestId, payload, callback) { if (payload.message === "Hi") { payload.message = "Hello"; //Sends back 'Hello' to user. return sdk.sendUserMessage(payload, callback); } else if (!payload.agent_transfer) { //Forward the message to bot return sdk.sendBotMessage(payload, callback); } else { payload.message = "Agent Message"; return sdk.sendUserMessage(payload, callback); } };

プラットフォームの Ver 8.0 のリリース後は、ユーザー、メッセージ、およびセッションのメタタグを追加できるようになりました。必要なペイロードの構文は以下のようになります:

metaTags":{ "userMetaTags":[ { "name":"<string>", "value":"<string>" } ], "sessionMetaTags":[ { "name":"<string>", "value":"<string>" } ], "messageMetaTags":[ { "name":"<string>", "value":"<string>" } ] }

sdk.AsyncResponse

この関数は、ボット プラットフォームに送信する非同期レスポンスを用意します。
使用方法
ダイアログ タスクの実行フローが Webhook ノードに到達した場合、ボット プラットフォームは SDK に対して on_webhook イベント呼出しを行います。on_webhook イベント呼出しは、2 種類のレスポンスをサポートしています:

• 同期レスポンス ー ビジネス ロジックの実行が許容時間内に完了できる場合、SDKは callback(null, payload) 関数を使用して同期レスポンスを行うことができます。
• 非同期レスポンス ー ビジネス ロジックの実行に時間が必要な場合、SDKは callback(null, new sdk.AsyncResponse()) 関数を呼び出し、HTTPコード202 を ボット プラットフォームに送信することで、非同期レスポンスを行うことができます。レスポンスの準備ができると、SDK は sdk.respondToHook(payload) 関数を呼び出すことができます。

構文:

sdk.AsyncResponse() callback(null, new sdk.AsyncResponse())

パラメータ:
なし。
サンプル
この on_webhook 関数のサンプルでは、ボットはユーザーが選択したタクシーの予約を非同期的に待機します。

on_webhook : function(requestId, payload, componentName, callback) { var context = payload.context; if (componentName === 'FindNearbyCabs') { findCabs() .then(function(cabList) { context.cabList = cabList; callback(null, data); }); } else if (componentName === 'BookTheCab') { sdk.saveData(requestId, payload) .then(function() { bookTheCab(requestId, context.entities.selectedCab.id, context.session.UserSession.location, context.entities.whereTo); callback(null, new sdk.AsyncResponse()); }); } }

sdk.respondToHook

この関数は、Webhook のレスポンスをボット プラットフォームに 送信します。
使用方法
ダイアログ タスクの実行フローが Webhook ノードに到達した場合、ボット プラットフォームは SDK に対して on_webhook イベント呼出しを行います。on_webhook イベント呼出しでは、2 種類のレスポンスをサポートしています。

• 同期レスポンス ー ビジネス ロジックの実行が許容時間内に完了できる場合、SDKは callback(null, payload) 関数を使用して同期レスポンスを行うことができます。
• 非同期レスポンス ー ビジネス ロジックの実行に時間が必要な場合、SDKは callback(null, new sdk.AsyncResponse()) 関数を呼び出し、HTTPコード202 をボット プラットフォームに送信することで、非同期レスポンスを行うことができます。応答の準備ができると、SDK は sdk.respondToHook(payload) 関数を呼び出すことができます。

構文:

sdk.respondToHook(payload)

パラメータ:

• payload – 以下に示すような、JSON のレスポンス ペイロードです:

  { "taskId":"Dialog task ID", "nodeId":"Current node ID in the dialog flow", "channel":"Channel name", "context": <context object> }

サンプル
以下のコードスニペットでは、タクシーの予約に失敗した場合、イベントが同期的に処理されます。逆に、タクシーの予約は Webhook で非同期に処理されます。

function onBookingFailure(requestId) { sdk.getSavedData(requestId) .then(function(payload) { payload.context.successful = false; sdk.respondToHook(payload); }); } //call cabBookingService with the requestId.このサービスは、非同期にレスポンスすることが期待されています。//'requestId' must be passed along all asynchronous flows, to allow the BotKit to respond // back to the hook once the async process is completed. function bookTheCab(requestId, cabId, userLoc, destination) { cabBookingService(requestId, cabId, userLoc, destination, { on_success: onBookingSuccess, on_failure: onBookingFailure }); }

sdk.registerBot

この関数は、ボットを登録し、ランタイムにコールバック イベントを利用できるようにします。
使用方法
BotKit SDK は、各ボットに対して 1 つの Node.js ファイルを作成するように設計されています。ボットのコールバックはすべて、この Node.js ファイルで管理されます。ボットを登録するには、以下のような変数や関数をエクスポートする必要があります:

module.exports = {       botId : “xxxxx”,       botName : ““xxxxx”,       on_user_message : function(requestId, data, callback) {            //code goes here       },       on_bot_message : function(requestId, data, componentName, callback) {            //code goes here       },      on_webhook : function(requestId, data, componentName, callback) {            //code goes here       }, }

構文：
ボットを登録するには、次を呼び出します

sdk.registerBot(require('./<Bot Name>.js'));

パラメータ:

• ボットが登録するための Node.js ファイル

サンプル
以下のコード サンプルでは、 botId と botNameによるボットの登録を示しています。

module.exports = { botId : botId, botName : botName, on_user_message : function(requestId, payload, callback) { debug('on_user_message'); onUserMessage(requestId, payload, callback); }, on_bot_message : function(requestId, payload, callback) { debug('on_bot_message'); onBotMessage(requestId, payload, callback); }, on_agent_transfer : function(requestId, payload, callback) { console.log("on agent transfer event"); debug('on_webhook'); onAgentTransfer(requestId, payload, callback); }, gethistory: gethistory };

sdk.saveData

この関数は、データを Redis インメモリ データ構造ストアに保存します。
使用方法
on_webhook イベント呼出しに非同期に応答する場合、requestIdでペイロードを Redis ストアに保存できます。ビジネス ロジックの実行が完了したら、Webhook の応答を準備しながら、 sdk.getSavedData(requestId)function を使用してデータを読み取ることができます。
構文:

sdk.saveData(requestId, payload)

パラメータ:

• requestId ー 非同期の on_webhook イベント呼出しからの requestId 。
• payload — 以下に示すような、JSON のレスポンス ペイロードです:

  { "taskId":"Dialog task ID", "nodeId":"Current node ID in the dialog flow", "channel":"Channel name", "context": <context object> }

サンプル
この on_webhook イベントでは、タクシーを予約したいというユーザーのリクエストがRedis ストアに保存され、予約の非同期処理が開始されます。

on_webhook : function(requestId, payload, componentId, callback) { var context = data.context; if (componentId === 'FindNearbyCabs') { findCabs() .then(function(cabList) { context.cabList = cabList; callback(null, payload); }); } else if (componentName === 'BookTheCab') { sdk.saveData(requestId, payload) .then(function() { //Assuming the cab booking was successful.A mock service to book the cab can be called here. payload.successful = 'true'; payload.bookedCab = context.entities.selectedCab || {}; callback(null, payload); }); } }

sdk.getSavedData

この関数は、Redis インメモリデータ構造ストアのデータを読み込みます。
使用方法
on_webhook イベント呼びたしに非同期で応答する場合、 requestIdでペイロードを Redis ストアに保存できます。ビジネス ロジックの実行が完了すると、Webhook のレスポンスを準備しながら、 sdk.getSavedData(requestId)function を使用してデータを読み取ることができます。
構文:

sdk.getSavedData(requestId, payload)

パラメータ:

• requestId – requestId  非同期のon_webhookイベント呼出し 。（非同期の <on_webhook> イベント呼出しからの <requestId/>。
• payload — 以下に示すような、JSON のレスポンス ペイロードです:

  {{ "taskId":"Dialog task ID", "nodeId":"Current node ID in the dialog flow", "channel":"Channel name", "context": <context object> }

サンプル
このコード サンプルでは、 sdk.getSavedData 関数を使用して、選択したタクシーと予約情報を返したり、非同期予約 webhook イベントが失敗した場合に、選択した予約の失敗メッセージをユーザーに送信します。

/*/ * Webhook に成功フラグで非同期に応答します。*/ function onBookingSuccess(requestId) { sdk.getSavedData(requestId) .then(function(payload) { payload.context.bookedCab = payload.entities.selectedCab; payload.context.successful = true; sdk.respondToHook(payload); }); } function onBookingFailure(requestId) { sdk.getSavedData(requestId) .then(function(payload) { payload.context.successful = false; sdk.respondToHook(payload); }); }

sdk.getMessages

この関数は、ボットとユーザーの過去の会話のトランスクリプトを取得するために使用します。公開 API の会話履歴と同様に動作をします (会話履歴 API についてはこちらをご覧ください)
使い方
ボットとユーザーの間で交わされた会話メッセージを逆の時系列で取得します。この API は、改ページをサポートしています。オフセット/スキップや、一度に特定の数のメッセージを取得する制限を設けることができます。
構文:

sdk.getMessages(requestData, callback)

パラメータ:

• requestData — 以下のように記述します:

  requestData.baseUrl + '/getMessages?'+ "skip=" + offset + "&limit=" + limit + "&userId=" + userId+"&channelType"=channel-type

  位置?

  • stream_id ー Bot ビルダーの「設定」ページからアクセスできるボット ID
  • user_id ー 会話履歴にアクセスするユーザーの ID
  • skip ー スキップするメッセージの数。
  • limit ー 各ページに表示されるメッセージの数。
  • channelType ー オプションで、会話をホストするチャネルを指定します。
• callback ー イベント完了時に呼び出す関数で、メッセージの履歴をボット プラットフォームに送り返します。

サンプル

//this example is from the LiveChat.js //where the gethistory() function uses getMessage() to extract the messages var userId = req.query.userId; var data = userDataMap[userId]; if(data) { data.limit = 100; return sdk.getMessages(data, function(err, resp){ if(err){ res.status(400); return res.json(err); } var messages = resp.messages; res.status(200); return res.json(messages); });

sdk.clearAgentSession

この関数は、エージェントのセッションをクリアし、ボットとの会話を再構築するために使用されます。
使用方法
エージェント転送のシナリオでは、エージェントがユーザーとの会話を終了すると、サードパーティのプロバイダから chat_closed イベントがトリガーされます。このような状況で、ボットとの会話を再確立するために、この関数が呼び出されます
構文:

sdk.clearAgentSession(requestData, callback)

パラメータ:

• requestData — 以下のように記述します:

  requestData.baseUrl+ '/clearAgentSession/' + requestData.requestId

  位置?

  • requestId ー セッション ID
• callback ー イベント完了時に呼び出される関数です。

サンプル

//this example is from the LiveChat.js //where the function is invoked to clear agent session when the chat is closed by the user if (event.type==="chat_closed"){ console.log('chat_closed'); delete userResponseDataMap[visitorId]; delete _map[visitorId]; sdk.clearAgentSession(data); }

プラットフォームの Ver 8.0 のリリース後は、ユーザー、メッセージ、およびセッションのメタタグを追加できるようになりました。必要なペイロードの構文は以下のようになります:

metaTags":{ "userMetaTags":[ { "name":"<string>", "value":"<string>" } ], "sessionMetaTags":[ { "name":"<string>", "value":"<string>" } ], "messageMetaTags":[ { "name":"<string>", "value":"<string>" } ] }

sdk.startAgentSession

この関数は、エージェント セッションが開始されたことをプラットフォームに通知するために使用されます。
使用方法
この関数は、エージェント転送が開始され、エージェント転送が進行中であることをボットに表示したい場合に使用します。これに従うと、たとえば onMessages() で BotKit が受け取るデータ オブジェクトは、エージェント セッションが true になります。さらに、BotKit から sdk.clearAgentSession が呼び出されると、エージェント セッションが完了したことがプラットフォームに通知され、BotKit が受信したデータ オブジェクトのエージェント セッションが false に設定されます。
構文:

sdk.startAgentSession(requestData, callback)

パラメータ:

• requestData — 以下のように記述します:

  requestData.baseUrl + '/startAgentSession/' + requestData.requestId

  位置?

  • requestId ー セッション ID
• callback ー イベント完了時に呼び出される関数です。

サンプル

//The following function call is used in the LiveChat.js for connectToAgent() function //Invoking the startAgentSession before invoking the initChat function will ensure that // the Bot is aware of the Agent transfer in progress function connectToAgent(requestId, data, cb){ var formdata = {}; formdata.licence_id = config.liveagentlicense; formdata.welcome_message = ""; var visitorId = _.get(data, 'channel.channelInfos.from'); if(!visitorId){ visitorId = _.get(data, 'channel.from'); } userDataMap[visitorId] = data; data.message="An Agent will be assigned to you shortly!!!"; sdk.sendUserMessage(data, cb); sdk.startAgentSession(data, cb); formdata.welcome_message = "Link for user Chat history with bot: "+ config.app.url +"/history/index.html?visitorId=" + visitorId; return api.initChat(visitorId, formdata) .then(function(res){ _map[visitorId] = { secured_session_id: res.secured_session_id, visitorId: visitorId, last_message_id: 0 }; }); }

プラットフォームの Ver 8.0 のリリース後は、ユーザー、メッセージ、およびセッションのメタタグを追加できるようになりました。必要なペイロードの構文は以下のようになります:

metaTags":{ "userMetaTags":[ { "name":"<string>", "value":"<string>" } ], "sessionMetaTags":[ { "name":"<string>", "value":"<string>" } ], "messageMetaTags":[ { "name":"<string>", "value":"<string>" } ] }

sdk.resetBot

この関数は、コンテキストを消去して、現在のタスクを表示せずに破棄するために使用されます。
使用方法
実行時、ダイアログの実行中に、ユーザー入力が「ボットのリセット」コマンドを使用してボットを消去したい場合に使用します。コンテキストを消去して、タスクを破棄することができます。
構文:

sdk.resetBot(requestData, callback)

パラメータ:

• requestData — 以下のように記述します:

  requestData.resetBotUrl

• callback ー イベント完了時に呼び出される関数です。

サンプル

on_user_message : function(requestId, data, callback) { if (data.message==="reset bot"){ sdk.resetBot(data, callback); }

sdk.extendRequestId

この関数は、BotKit がプラットフォームにメッセージを送信するために割り当てられた時間を延長するために使用されます。
使用方法
この関数は、エージェント転送が開始され、しばらくするとプラットフォームがメッセージを受信できなくなる場合に使用します。これは、BotKit がプラットフォームにメッセージを送信するための時間を延長することで対応できます。
構文:

sdk.extendRequestId(requestData, callback)

サンプル

function onBotMessage(requestId, data, cb) { console.log("bot message",JSON.stringify(data)); var visitorId = _.get(data, 'channel.from'); event = schedular.scheduleJob("*/4 * * * *", function() { pub.get(visitorId+':data',function(err,reply){ if(err) throw err; sdk.extendRequestId(data, cb); })}); }

on_user_message: function(requestId, data, callback) { var visitorId = _.get(data, 'channel.from'); registerEvent(visitorId, data); if(event){ event.cancel(); }else{ console.log(new Date(),'event not found'); } event = schedular.schedular.scheduleJob("*/4 * * * *", function() { pub.get(visitorId+':data',function(err,reply){ if(err) throw err; sdk.extendRequestId(data,callback); })});

メモ: 15 分間アクティブな会話がない場合は、時間延長は有効ではありません。非アクティブなセッションでは、それとは無関係に agent_transfer モードがリセットされます。

sdk.skipBotMessage

この関数は、特定のビジネス ユース ケースにおいて、特定のメッセージをスキップするために使用されます。
使用方法
実行時、ダイアログの実行中に、システムは BotKit が進行メッセージを送信するのを待たずに次のステップに進みます。。

構文:

sdk.skipBotMessage(requestData, callback)

パラメータ:

• requestData ー データ
• callback ー イベント完了時に呼び出される関数です。

サンプル

if(data.message === "skipBotMessage"){ // condition for skipping a Bot message sdk.skipBotMessage(data, cb); }

プラットフォームの Ver 8.0 のリリース後は、ユーザー、メッセージ、およびセッションのメタタグを追加できるようになりました。必要なペイロードの構文は以下のようになります:

metaTags":{ "userMetaTags":[ { "name":"<string>", "value":"<string>" } ], "sessionMetaTags":[ { "name":"<string>", "value":"<string>" } ], "messageMetaTags":[ { "name":"<string>", "value":"<string>" } ] }

sdk.skipUserMessage

この関数は、特定のビジネス ユース ケースにおいて、特定のメッセージをスキップするために使用されます。
使用方法
実行時、ダイアログの実行中に、システムは BotKit が確認メッセージを送信するのを待たずに次のステップに進みます。
構文:

sdk.skipUserMessage(requestData, callback)

パラメータ:

• requestData ー データ
• callback ー イベント完了時に呼び出される関数です。

サンプル

if(data.message === "closeConversationSession"){ // condition for skipping a user message sdk.closeConversationSession(data, cb); }

プラットフォームの Ver 8.0 のリリース後は、ユーザー、メッセージ、およびセッションのメタタグを追加できるようになりました。必要なペイロードの構文は以下のようになります:

metaTags":{ "userMetaTags":[ { "name":"<string>", "value":"<string>" } ], "sessionMetaTags":[ { "name":"<string>", "value":"<string>" } ], "messageMetaTags":[ { "name":"<string>", "value":"<string>" } ] }

sdk.closeConversationSession

この関数は、会話セッションを閉じるために使用します。
使用方法
構文:

sdk.closeConversationSession(requestData, callback)

パラメータ:

• requestData ー データ
• callback ー イベント完了時に呼び出される関数です。

サンプル

if(data.message === "closeConversationSession"){ // condition for skipping a user message sdk.closeConversationSession(data, cb); }

プラットフォームの Ver8.0 のリリース後は、ユーザー、メッセージ、およびセッションのメタタグを追加できるようになりました。必要なペイロードの構文は以下のようになります:

metaTags":{ "userMetaTags":[ { "name":"<string>", "value":"<string>" } ], "sessionMetaTags":[ { "name":"<string>", "value":"<string>" } ], "messageMetaTags":[ { "name":"<string>", "value":"<string>" } ] }