Hooks
ConvoKraft hooksは、Catalyst WebアプリケーションのグローバルスコープでConvoKraftオブジェクトを使用してアクセスできるように、開発者が設定できる関数です。ConvoKraft JS SDKは以下のhooksを提供しています:
- handleResponse
- handleMissed
- handleError
- minimizeChat
- didConnect
- setOnBoarding
- setOnBoardingSentences
- setClientSessionData
- handleUpload
- handleWelcome
handleResponse
任意のactionに対してConvoKraftが提供する応答に基づいて、データを処理し、特定の要件に応じて応答のビジュアル表現をカスタマイズできます。
送信された元の応答は、WebアプリケーションからのDeluge関数のdataキーで送信されます。応答をカスタマイズするには、以下のhookにデータ値とHTML要素を渡す必要があります。HTML要素内でWebアプリケーションがConvoKraftの元の応答をレンダリングできます。
構文
convokraft.handleResponse=function(actionName,data,element,responseHandled,fromHistory,fromPagination)
{
//ロジックをここに入力する
return true;
}
以下の表は、関数の各要素の詳細を示しています:
| 要素 | 説明 |
|---|---|
| actionName | 呼び出されたactionのnamespaceです。 |
| data | Delugeからhookに送信されるカスタムデータを保持します。 |
| element | チャットウィンドウに表示されるConvoKraftのカスタム返信要素を保持します。 |
| responseHandled | DOM操作が完了し、チャットdivを上部にスクロールできることをBotに知らせるための必須コールバック関数です。 |
| fromHistory | 現在構築中のメッセージが現在のセッションのものか過去のセッションのものかを表すBoolean値を含むキーです。 |
| fromPagination | 現在構築中のメッセージがページネーション呼び出し後のメッセージかどうかを表すBoolean値を含むキーです。trueの場合、メッセージが最下部までスクロールされないように、responseHandled()を呼び出さないことをお勧めします。 |
サンプルコード
convokraft.handleResponse = function(actionName,data,element,responseHandled,fromHistory,fromPagination)
{
if(actionName=="schedule_event")
{
element.innerHTML="This is a test function from "+data.name;
element.style.padding="10px";
responseHandled();
return false; //上記で構築したレスポンスを返す
}
return true; //元のConvoKraftレスポンスを返す
}
handleMissed
ユーザーのメッセージがBotの設定済みActionsのいずれとも一致しない場合、Webアプリケーションのグローバルスコープでconvokraft.handleMissed() hookを定義していれば、ConvoKraftはこのhookを通じてレンダリングされたカスタム応答を表示します。
構文
convokraft.handleMissed = function(element, responseHandled, fromHistory, fromPagination)
{
//convokraftのレスポンスとしてレンダリングされる要素のロジックを入力する
}
以下の表は、構文の各要素とその説明を示しています:
| 要素 | 説明 |
|---|---|
| element | チャットウィンドウに表示されるConvoKraftのカスタム返信要素を保持します。 |
| responseHandled | DOM操作が完了し、チャットdivを上部にスクロールできることをBotに知らせるための必須コールバック関数です。 |
| fromHistory | 現在構築中のメッセージが現在のセッションのものか過去のセッションのものかを表すboolean値を含むキーです。 |
| fromPagination | 現在構築中のメッセージがページネーション呼び出し後のメッセージかどうかを表すboolean値を含むキーです。trueの場合、メッセージが最下部までスクロールされないように、responseHandled()を呼び出さないことをお勧めします。 |
サンプルコード
convokraft.handleMissed= function(element,responseHandled,fromHistory){
element.innerHTML = "Sorry! Not found!
";
responseHandled();
return false;
}
handleError
Actionの実行中にAPIエラーが発生した場合、Catalyst Webアプリケーションのグローバルスコープでconvokraft.handleErrorを定義することで、このhookを使用してカスタムエラー応答を表示できます。
構文
convokraft.handleError = function(element, responseHandled, fromHistory, fromPagination)
{
//エラーメッセージをカスタマイズするロジックを入力する
}
以下の表は、構文の各要素とその説明を示しています:
| 要素 | 説明 |
|---|---|
| element | チャットウィンドウに表示されるConvoKraftのカスタム返信要素を保持します。 |
| responseHandled | DOM操作が完了し、チャットdivを上部にスクロールできることをBotに知らせるための必須コールバック関数です。 |
| fromHistory | 現在構築中のメッセージが現在のセッションのものか過去のセッションのものかを表すboolean値を含むキーです。 |
| fromPagination | 現在構築中のメッセージがページネーション呼び出し後のメッセージかどうかを表すboolean値を含むキーです。trueの場合、メッセージが最下部までスクロールされないように、responseHandled()を呼び出さないことをお勧めします。 |
サンプルコード
convokraft.handleError= function(element,responseHandled){
if(typeof data !== "undefined"){
messageString = data.data.code;
}
else{
messageString = "Api Error!";
}
element.innerHTML = "Sorry! "+messageString+"
";
responseHandled();
}
minimizeChat
このhookを使用すると、チャットウィンドウのヘッダーをクリックしたときにチャットウィンドウを最小化または最大化できます。
構文
convokraft.minimizeChat=function()
{
//チャットdivを取得し、必要に応じて最小化アニメーションとスタイルを適用する
}
サンプルコード
convokraft.minimizeChat=function()
{
if(document.getElementById("zdivid").style.marginBottom=="-400px"||document.getElementById("zdivid").style.marginBottom=="")
{
document.getElementById("zdivid").style.marginBottom="-0px";
}
else
{
document.getElementById("zdivid").style.marginBottom="-400px";
}
}
didConnect
このhookは、チャットが完全に読み込まれたことをCatalyst Webアプリケーションに通知するために使用されます。
構文
convokraft.didConnect=function()
{
//ロジックをここに入力する
}
サンプルコード
convokraft.didConnect=function()
{
var loadingDiv=document.getElementById("loadingDiv");
if(loadingDiv)
{
loadingDiv.style.display='none';
}
}
setOnBoarding
チャット履歴がない場合、onboarding screenがデフォルトで表示されます。このhookは、要件に応じてConvoKraft Botのonboarding screenをカスタマイズするために、Webアプリケーションのグローバルスコープで定義できます。
構文
convokraft.setOnBoarding=function(element,sentences,placeholders)
{
//必要に応じてHTMLとスタイルを構築し、要素に追加する
}
以下の表は、構文の各要素とその説明を示しています:
| 要素 | 説明 |
|---|---|
| element | カスタマイズが必要なHTML要素を保持します。 |
| sentences | その特定のactionのSample Sentencesを保持します。 |
| placeholders | onboarding screenに表示される文のさまざまなパラメータを保持するために使用できる文字列の配列です。 |
サンプルコード
convokraft.setOnBoarding=function(element,sentences,placeholders)
{
var html="This is a custom onboarding screen by client app and here are the list of sentences:
";
sentences.forEach(function(item)
{
html+="- "+item+"
";
})
html+="
";
element.innerHTML=html;
element.style.padding="10px";
}
setOnBoardingSentences
このhookは、ConvoKraftチャットウィンドウを開いたときに表示されるonboarding sentencesまたはaction suggestionsをカスタマイズするために使用されます。デフォルトでは、チャットウィンドウはConvoKraft ActionsのSample Sentencesの設定に基づいて提案を表示します。以下に示すように、JSON形式のオブジェクトの配列をこのhookの引数として渡すことができます。また、JSONのsentencesを使用して、プレースホルダーにさまざまな値を設定して返すことができます。
[
{
"id": "1",
"sentence": "Apply leave for {{fromdate}} and {{todate}}",
"actual_sentence": "Apply leave for today and tomorrow"
},
{
"id": "2",
"sentence": "What is the {{property}} of {{country}}?",
"actual_sentence": "What is the capital of India?"
}
]
//オンボーディング画面に表示される文を絞り込みまたは修正する
構文
convokraft.setOnBoardingSentences=function(sentences)
{
//必要に応じてHTMLとスタイルを定義し、要素に追加する
}
サンプルコード
convokraft.setOnBoardingSentences=function(sentences)
{
sentences.splice(0,8);
return sentences;
}
- このhookはsetOnBoarding hookが適用されていない場合にのみ考慮されます。
- setOnBoarding hookでカスタムsentencesが必要な場合は、setOnBoarding hook内のsentencesに同じ処理を適用してください。
setClientSessionData
このhookは、Catalyst Webアプリケーションのカスタムクライアントセッションデータを取得するために使用されます。ConvoKraftがアクセスできるように、Catalyst Webアプリケーションのグローバルスコープで定義してください。
構文
convokraft.setClientSessionData=function()
{
//JSONオブジェクトを返す
}
サンプルコード
convokraft.setClientSessionData=function()
{
return
{
portal_name: "zylker",
ui_version: "2.0"
}
}
- セッションデータはJSONオブジェクトとして返すようにしてください。
- Deluge関数を使用する場合、このハンドルから返されるJSONデータはsessionData.set(“client_data”).を使用して取得できます。
handleUpload
このhookは、ファイルアップロード後に実行する操作を定義するために使用されます。選択した開発プラットフォームがDelugeまたはFunctionの場合、ファイルはCatalystクラウド環境にアップロードされます。Webhooksの場合は、file属性で独自のファイルパスを定義する必要があります。特定の要件に基づいて、onSuccesおよびonFailureコールバック引数にそれぞれのメッセージを設定できます。
構文
convokraft.handleUpload = function(input){
//convokraftのレスポンスとしてレンダリングされる要素に対して自由に処理する
}
このhookでは以下の属性がサポートされています:
| 属性名 | 用途 |
|---|---|
| sessionId | 現在のトランスクリプトセッションのIDです。 |
| param | param名、タイプ、プロンプトメッセージなどの現在のプロンプトのparam情報です。 |
| file | ユーザーが提供したファイルオブジェクトです。 |
| action | 現在の会話のaction namespaceです。 |
| bot | 現在の会話のbot namespaceです。 |
| onSuccess | ファイルIDを入力として受け取る必須コールバックです。 |
| onProgressChange | 計算されたアップロードパーセンテージをパラメータとして受け取る必須コールバックです。アップロードパーセンテージが変化するたびに呼び出す必要があります。アップロードが完了した場合は、パーセンテージを100に設定し、成功状態を示すメッセージ(例:onProgressChange(100,“File upload completed”);)を表示してください。 |
| onFailure | アップロード失敗の理由を示すメッセージ文字列を入力として受け取る必須コールバックです。 |
サンプルコード
convokraft.handleUpload=function(uploadObject){
let percentage = 20;
let onSuccess = uploadObject.onSuccess;
let onFailure = uploadObject.onFailure;
var percentageInterval = setInterval(function() {
if(percentage === 100){
clearInterval(percerntageInterval);
uploadObject.updateProgress(100,"Your file is being processed. Please wait...");
setTimeout(function() {
if(zia.fileUploadCount > 1){
onSuccess((Date.now()).toString());
}
else{
onFailure("Your file is over 2MB. Please upload a file of less size.");
}
}, 5000);
return;
}
percentage+=20;
uploadObject.onProgressChange(percentage);
}, 500);
}
handleWelcome
このhookは、ウェルカムメッセージ(チャットセッションで最初に表示されるメッセージ)を変更するために使用されます。UIのカスタマイズのみが必要な場合にこのhookを使用できます。ウェルカムメッセージの表示にバックエンドロジックの実行が必要な場合は、welcome message handler関数を使用してください。
構文
convokraft.handleWelcome = function(config){
//convokraftのレスポンスとしてレンダリングされる要素に対して自由に処理する
}
サンプルコード
convokraft.handleWelcome = function(config) {
config.element.innerHTML = `Hello Guest! Here are few things I can do for you. <div class='suggestion'>Raise a ticket</div> <div class='suggestion'>List my inventory and assets</div>`;
}
最終更新日 2026-03-30 13:40:30 +0530 IST
Yes
No
Send your feedback to us