---
title: "フック"
url: https://docs.catalyst.zoho.com/ja/convokraft/sdk/js/hooks/
description: "Catalystアプリケーションに強力なチャットBotアシスタントを統合する機能を持つCatalyst ConvoKraftサービスが提供するJS SDKパッケージについて学びます。"
last_updated: 2026-03-30T08:10:30Z
service: ConvoKraft
type: general
---
# 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の元の応答をレンダリングできます。
**構文**
```javascript
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()`を呼び出さないことをお勧めします。 |
**サンプルコード**
```javascript
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を通じてレンダリングされたカスタム応答を表示します。
**構文**
```javascript
convokraft.handleMissed = function(element, responseHandled, fromHistory, fromPagination)
{
//convokraftのレスポンスとしてレンダリングされる要素のロジックを入力する
}
```
以下の表は、構文の各要素とその説明を示しています：
| 要素 |
説明 |
| `element` |
チャットウィンドウに表示されるConvoKraftのカスタム返信要素を保持します。 |
| `responseHandled` |
DOM操作が完了し、チャットdivを上部にスクロールできることをBotに知らせるための必須コールバック関数です。 |
| `fromHistory` |
現在構築中のメッセージが現在のセッションのものか過去のセッションのものかを表すboolean値を含むキーです。 |
| `fromPagination` |
現在構築中のメッセージがページネーション呼び出し後のメッセージかどうかを表すboolean値を含むキーです。`true`の場合、メッセージが最下部までスクロールされないように、`responseHandled()`を呼び出さないことをお勧めします。 |
**サンプルコード**
```javascript
convokraft.handleMissed= function(element,responseHandled,fromHistory){
element.innerHTML = "Sorry! Not found!
| 要素 |
説明 |
| `element` |
チャットウィンドウに表示されるConvoKraftのカスタム返信要素を保持します。 |
| `responseHandled` |
DOM操作が完了し、チャットdivを上部にスクロールできることをBotに知らせるための必須コールバック関数です。 |
| `fromHistory` |
現在構築中のメッセージが現在のセッションのものか過去のセッションのものかを表すboolean値を含むキーです。 |
| `fromPagination` |
現在構築中のメッセージがページネーション呼び出し後のメッセージかどうかを表すboolean値を含むキーです。`true `の場合、メッセージが最下部までスクロールされないように、`responseHandled()`を呼び出さないことをお勧めします。 |
**サンプルコード**
```javascript
convokraft.handleError= function(element,responseHandled){
if(typeof data !== "undefined"){
messageString = data.data.code;
}
else{
messageString = "Api Error!";
}
element.innerHTML = "Sorry! "+messageString+"
| 要素 |
説明 |
| `element` |
カスタマイズが必要なHTML要素を保持します。 |
| `sentences` |
その特定のactionのSample Sentencesを保持します。 |
| `placeholders` |
onboarding screenに表示される文のさまざまなパラメータを保持するために使用できる文字列の配列です。 |
**サンプルコード**
```javascript
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を使用して、プレースホルダーにさまざまな値を設定して返すことができます。
```javascript
[
{
"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?"
}
]
//オンボーディング画面に表示される文を絞り込みまたは修正する
```
**構文**
```javascript
convokraft.setOnBoardingSentences=function(sentences)
{
//必要に応じてHTMLとスタイルを定義し、要素に追加する
}
```
**サンプルコード**
```javascript
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アプリケーションのグローバルスコープで定義してください。
**構文**
```javascript
convokraft.setClientSessionData=function()
{
//JSONオブジェクトを返す
}
```
**サンプルコード**
```javascript
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`コールバック引数にそれぞれのメッセージを設定できます。
**構文**
```javascript
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` |
アップロード失敗の理由を示すメッセージ文字列を入力として受け取る必須コールバックです。 |
**サンプルコード**
```javascript
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関数を使用してください。
**構文**
```javascript
convokraft.handleWelcome = function(config){
//convokraftのレスポンスとしてレンダリングされる要素に対して自由に処理する
}
```
**サンプルコード**
```javascript
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>`;
}
```