- 印刷する
- PDF
アクションメソッド
- 印刷する
- PDF
Classic/VPC環境で利用できます。
アクションメソッド(ActionMethod)を用いてチャットボットと外部システムのデータを連携させることができます。アクションメソッドを用いると、APIを呼び出したり、APIの呼び出し時にユーザーとの会話で分析された内容を伝達したり、APIで返された結果を受け取って返答するのに活用することができます。例えば、価格情報、ユーザー情報、天気情報などの可変的なデータをデータベースからリアルタイムで取得し、返答として提供できます。
作成したアクションメソッドは${ActionMethodName}形式に定義して使用します。会話の返答の登録時に使用するアクションメソッドを{ActionMethodName}形式で入力すると、その返答が返される際にアクションメソッドを呼び出すことができます。
サポートするアクションメソッドは以下のとおりです。
- アクションメソッドV1.0
- アクションメソッドV2.0
- LINE PAY
- Naver Pay
- CEK Requestの転送
- ビルトインアクションメソッド
- アクションメソッドを有効に活用するには、REST API呼び出しなど開発に関する予備知識が必要です。チャットボットサービスと連携する顧客のBackend System環境がすべて異なるため、チャットボットのアクションメソッドの呼び出しに応答できるBackend System環境を準備する必要があります。
- CLOVA ChatbotサービスはアクションメソッドGET/POSTスペックを提供していますが、これと連携するようにBackendサーバを実装するのはお客様の開発領域であり、CLOVA Chatbotサービスの提供範囲には含まれません。
- 開発の利便性を強化するため、アクションメソッドがどんな形式でBackend ServerにGET/POSTを送るのか、アクションメソッドRequestを確認できる方法(エコー)を提供します。
アクションメソッドの呼び出しTimeoutのデフォルト値は200msです。呼び出しtimeoutの値は直接変更できません。変更をご希望の場合はサポートセンターまでお問い合わせください。
アクションメソッドのパラメータ
アクションメソッドを用いてBackend Systemに情報を送るには、定義されたパラメータ形式が必要です。このとき、「エンティティ」が用いられます。事前に定義されたエンティティはユーザーのデータとマッピングするkeyです。また、アクションメソッドを使用するには、エンティティが一緒に定義されて動作する必要があります。事前に定義されたエンティティはアクションメソッドでも使用できます。
アクションメソッドのバージョン別スペック
項目 | 説明 | 例 |
---|---|---|
アクションメソッドv1.0 | - 1回の呼び出しで1つの値だけ取得できる - GET/POST方式を提供 | 「現在、亭子洞の気温は${weather}度です。」 |
アクションメソッドv2.0 | - 1回の呼び出しで複数の値を取得できる - POST方式を提供 - ユーザー変数の値を取得できる | 「 |
アクションメソッドV1.0
アクションメソッドを作成する前に、アクションメソッドで活用するドメインエンティティを作成してください。作成されたアクションメソッドを返答フィールドに入力すると、返答を返す際にそのアクションメソッドを呼び出します。
例えば、返答を「現在、亭子洞の気温は
GET方式によるアクションメソッド作成
GET方式でアクションメソッドを作成する方法は以下のとおりです。
- NAVERクラウドプラットフォームコンソールでServices > CLOVA Chatbot > Domainメニューを順にクリックします。
- 希望するドメインの [ビルダーを実行する] ボタンをクリックしてチャットボットビルダーを実行します。
- チャットボットビルダーで アクションメソッドメニューをクリックします。
- タイプでアクションメソッドV1.0、GETを選択し、名前フィールドにアクションメソッドの名前を入力します。
- URLフィールドに、呼び出すURLを入力します。
- $を入力すると登録されているエンティティリストが表示され、エンティティリストからエンティティを選択して追加できる
- [エコーの呼び出し] ボタンをクリックすると、テストAPIが自動で入力される。このアクションメソッドを呼び出すとチャットボットエンジンから外部APIサーバに伝達されるRequestがそのまま表示されるため、どんな方式でRequestされるのか確認できる
- 値の転送オプションを選択します。
- CLOVA認証Access Token:CLOVA Extensionで認証されたユーザーアカウントのAccess Tokenを受け取り、ユーザーリクエストを伝達できる
- Session Attributes:UTF-8にエンコードされた特定の文字列をX-KAA-SESSION-ATTRIBUTESヘッダに持たせて伝達できる
- [保存] ボタンをクリックします。
- 作成したアクションメソッドは、返答の入力時に${アクションメソッド名}の方式で活用できる
応答形式
HttpMethod: GET
Http Headers: {
X-KAA-USERENTITY=test_date%3dsaturday%26test_time%3d3o%27clock%26test_num%3d2people,
X-KAA-USERKEY=4d4cf7425f5b4769807fb4cba66bd987,
X-KAA-USERMSG=%E3%85%87,
X-KAA-USERID=9ff4-b49e74ea22e4
}
body ={}
項目 | 説明 |
---|---|
X-KAA-USERKEY | ハッシュされたユーザーキーの値を伝達 |
X-KAA-USERENTITY | タスクが終了したか、スロットが進行中のときに登場したエンティティ情報が入っている エンティティキー=エンティティ値&エンティティキー=エンティティ値&...といった形式になっており、UTF-8にエンコードされている |
X-KAA-USERMSG | ユーザーの発話が含まれている 記入型フォームが登場したとき、ユーザーが入力した場合にのみ動作し、UTF-8にエンコードされている |
X-KAA-USERID | ユーザーのoriginal userIdが含まれている |
X-KAA-CLOVA-OAUTH-ACCESS-TOKEN | CLOVAプラットフォームにリクエストが入るとき、そのドメインが外部認証を使用している場合は、認証トークンがCLOVAへのリクエストに含まれて渡される。その値を有効に設定したアクションメソッドを呼び出すと、このヘッダを介してトークンを渡す |
X-KAA-CLOVA-OAUTH-ACCESS-TOKEN | CLOVAプラットフォームにリクエストが入るとき、そのドメインが外部認証を使用している場合は、認証トークンがCLOVAへのリクエストに含まれて渡される。その値を有効に設定したアクションメソッドを呼び出すと、このヘッダを介してトークンを渡す |
X-KAA-SESSION-ATTRIBUTES | アクションメソッドの応答値で、この値をキーとしているヘッダがある場合、エンジンはしばらくこの値を記憶しておいて、この値を渡してほしいというフラグがONになっているアクションメソッドが呼び出された際に、この値をそのままヘッダに持たせて渡す |
JSON(POST)方式によるアクションメソッド作成
JSON(POST)方式はGET方式と同じですが、URLの呼び出しにデータを含めて送ることができます。データはJSON形式で送ります。エンティティデータ以外にも特定の値を一緒に転送することができます。
POST方式でアクションメソッドを作成する方法は以下のとおりです。
- NAVERクラウドプラットフォームのコンソールでServices > CLOVA Chatbot > Domainメニューを順にクリックします。
- 希望するドメインの [ビルダーを実行する] ボタンをクリックしてチャットボットビルダーを実行します。
- チャットボットビルダーで アクションメソッドメニュー をクリックします。
- タイプでアクションメソッドV1.0、POSTを選択します。
- 名前フィールドにアクションメソッドの名前を入力します。
- URLフィールドに、呼び出すURLを入力します。
- $を入力すると登録されているエンティティリストが表示され、エンティティリストからエンティティを選択して追加できる
- [エコーの呼び出し] ボタンをクリックすると、テストAPIが自動で入力される。このアクションメソッドを呼び出すとチャットボットエンジンから外部APIサーバに伝達されるRequestがそのまま表示されるため、どんな方式でRequestされるのか確認できる
- データフィールドに、JSON形式にしてマッピングするエンティティ名を入力します。
- 値の転送オプションを選択します。
- CLOVA認証Access Token:CLOVA Extensionで認証されたユーザーアカウントのAccess Tokenを受け取り、ユーザーリクエストを伝達できる
- Session Attributes:X-KAA-SESSION-ATTRIBUTESヘッダに文字列をエンコードして持たせると、アクションメソッドの呼び出し時にX-KAA-SESSION-ATTRIBUTESにある値をチャットボットエンジンがキャッシュしておく。Session Attributesオプションが有効になっているアクションメソッドを呼び出す場合、キャッシュしておいたX-KAA-SESSION-ATTRIBUTESに保存された文字列を一緒に渡す
- [保存] ボタンをクリックします。
- 作成したアクションメソッドは、返答の入力時に${アクションメソッド名}の方式で活用できる
リクエスト形式
HttpMethod: POST
Http Headers: {
X-KAA-USERENTITY=test_date%3dsaturday%26test_time%3d3o%27clock%26test_num%3d2people,
X-KAA-USERKEY=4d4cf7425f5b4769807fb4cba66bd987,
X-KAA-USERMSG=%E3%85%87,
X-KAA-USERID=9ff4-b49e74ea22e4
}
body ={"state": "korea", "country": "seoul"}
項目 | 説明 |
---|---|
X-KAA-USERKEY | ハッシュされたユーザーキーの値を伝達 |
X-KAA-USERENTITY | タスクが終了したか、スロットが進行中のときに登場したエンティティ情報が入っている エンティティキー=エンティティ値&エンティティキー=エンティティ値&...といった形式になっており、UTF-8にエンコードされる |
X-KAA-USERMSG | ユーザーの発話が含まれている。記入型フォームが登場したときに、ユーザーが入力した場合にのみ動作。UTF-8にエンコードされる |
X-KAA-USERID | ユーザーのoriginal userIdが含まれている |
X-KAA-CLOVA-OAUTH-ACCESS-TOKEN | CLOVAプラットフォームにリクエストが入るとき、そのドメインが外部認証を使用している場合は、認証トークンがCLOVAへのリクエストに含まれて渡される。その値を有効に設定したアクションメソッドを呼び出すと、このヘッダを介してトークンを渡す |
X-KAA-SESSION-ATTRIBUTES | アクションメソッドの応答値で、この値をキーとしているヘッダがある場合、エンジンはしばらくこの値を記憶しておいて、この値を渡してほしいというフラグがONになっているアクションメソッドが呼び出された際に、この値をそのままヘッダに持たせて渡す |
アクションメソッドV2.0
アクションメソッドV2.0は、1回の呼び出しで複数の値を取得できるという点でアクションメソッドV1.0とは異なります。
例えば、返答フィールドに「
- アクションメソッドV2.0は、JSON(POST)方式のみサポートします。
- 返答にアクションメソッドV2.0を入力する際は、$2{アクションメソッド2名}または$2{アクションメソッド2名.変数名}の形式で入力します。
POST方式でアクションメソッドV2.0を作成する方法は以下のとおりです。
- NAVERクラウドプラットフォームのコンソールでServices > CLOVA Chatbot > Domainメニューを順にクリックします。
- 希望するドメインの [ビルダーを実行する] ボタンをクリックしてチャットボットビルダーを実行します。
- チャットボットビルダーで アクションメソッド メニューをクリックします。
- タイプでアクションメソッドV2.0、POSTを選択します。
- 名前フィールドにアクションメソッドの名前を入力します。
- URLフィールドに、呼び出すURLを入力します。
- $を入力すると登録されているエンティティリストが表示され、エンティティを選択して追加することができます。
- [エコーの呼び出し] ボタンをクリックすると、アクションメソッドV2.0のテストが行える
- $2{アクションメソッド名.method}を入力すると、methodをエコーする(POSTが返される)
- $2{アクションメソッド名.body}を入力すると、bodyをエコーする
- [保存] ボタンをクリックします。
- 作成したアクションメソッドは、返答の入力時に$2{アクションメソッド2名}または$2{アクションメソッド2名.変数名}の形式で入力して活用できる
リクエスト形式
{
"actionMethod": {
"name": "アクションメソッドの名前です。",
"methods": [
{
"args": [
"arg1",
"age2"
],
"variableName": "返答に含まれた変数名です1"
},
{
"variableName": "返答に含まれた変数名です2"
}
]
},
"userInfo": {
"id": "メッセンジャーから取得したユーザーのIDが入っています",
"key": "サービスエンジン内部で使用するユーザーの固有キーをハッシュした値です",
"query": "ユーザー今回のターンに入力した発話です",
"entities": {
"エンティティコード1": "ユーザーが入力したエンティティ1",
"エンティティコード2": "ユーザーが入力したエンティティ2"
},
"taskEntities": {
"エンティティ名1": "タスクのスロットを埋めたエンティティ1",
"エンティティ名2": "タスクのスロットを埋めたエンティティ2"
},
"userVariables": {
"ユーザー変数名": {
"value": "ユーザー変数に入っている値",
"type": "ユーザー変数タイプ(TEXT、NUMBER、JSONが可能)"
}
}
}
}
値 | タイプ | 必須 | 説明 |
---|---|---|---|
actionMethod | Object | Y | アクションメソッドの情報 |
actionMethod.name | String | Y | 現在リクエストするアクションメソッド名 |
actionMethod.methods | Array[Object] | N | メソッド情報 返答に含まれていた同じ名前のアクションメソッド情報をまとめて一度にリクエスト |
actionMethod.methods.args | Array[String] | N | 任意のアーギュメントを入れておくことができる。存在する場合、そのアーギュメントを持たせて送る。 <例> $2{name(arg1, arg2).variableName} |
actionMethod.methods.variableName | String | N | アクションメソッドの変数名。アクションメソッドの.の後ろに続く部分を意味。 |
userInfo | Object | Y | ユーザー情報が入っている |
userInfo.id | String | Y | ユーザーのIDが入っている。各メッセンジャーから取得した値 |
userInfo.key | String | Y | サービスエンジン内部で使用するユーザーの固有キーをハッシュした値 |
userInfo.query | String | Y | ユーザーが今回のターンに入力した発話 |
userInfo.entities | Map[String, String] | N | ユーザーの発話で分析されたエンティティ情報が含まれている - Map(entity code -> user input) |
userInfo.taskEntities | Map[String, String] | N | - タスクが完了した場合、そのタスクで埋められたスロットの値が含まれる - Map(entity name -> user input or representative)スロット設定に応じて、ユーザーの入力か代表語がvalueとして入る |
userVariables | Map[String, (String, String)] | N | ユーザー変数情報が入っている値 |
userVariables.value | String or Long | Y | ユーザー変数に入っている値(テキスト、数字) |
userVariables.type | String | Y | ユーザー変数のタイプ(TEXT、NUMBER、JSON) |
応答形式
{
"data": [
{
"variableName": "変数名です",
"value": "variableNameに該当する変数をどんな値に置換するかを決めます"
}
],
"userVariable": [
{
"name": "ユーザー変数名です",
"value": "ユーザー変数に保存する値です",
"type": "ユーザー変数のタイプです",
"action": "動作を指定します",
"valueType": "保存する値のタイプです"
},
{
"name": "text",
"value": "olive",
"type": "TEXT",
"action": "EQ",
"valueType": "TEXT"
},
{
"name": "number",
"value": 10,
"type": "NUMBER",
"action": "ADD",
"valueType": "NUMBER"
},
{
"name": "date.year",
"value": 2020,
"type": "JSON",
"action": "EQ",
"valueType": "NUMBER"
},
{
"name": "date.month",
"value": 6,
"type": "JSON",
"action": "EQ",
"valueType": "NUMBER"
}
]
}
値 | タイプ | 必須 | 説明 |
---|---|---|---|
data | Array[Object] | N | アクションメソッド情報。 |
data.variableName | String | Y | 返答に含まれているアクションメソッドのうち、name.variableNameと一致する値をdata.valueにある値に変更する <例> $2{name(arg1, arg2).variableName} |
data.value | String | Y | variableNameに該当する変数をどんな値に変えるかを決める |
userVariable | Array[Object] | N | ユーザー変数を変更するために使用できる |
userVariable.name | String | Y | ユーザー変数名。JSONの場合、値を一つひとつ修正する必要がある .を区切り文字にしてJSONのフィールドを指定。 |
userVariable.value | String or Long | Y | 変更後の値。テキストか数字。 |
userVariable.type | String | Y | 変更後のユーザー変数のタイプを明示。 テキストの場合はTEXT、数字の場合はNUMBER、JSONの場合はJSONと入力 |
userVariable.action | String | Y | 動作を指定。数字の場合にのみEQ、ADD、SUBと入力でき、その他の場合はEQのみ入力できる - EQ:既存ユーザー変数の値の代わりにvalueを入力。 - ADD:既存ユーザー変数の値 + value演算を行ってから保存。 - SUB:既存ユーザー変数の値 - value演算を行ってから保存。 |
userVariable.valueType | String | Y | userVariable.valueのタイプを明示(TEXTかNUMBER) |
LINE PayとNAVER Pay
LINE PayとNAVER Payアクションメソッドを用いると、チャットボットでLINE PayやNAVER Payで決済するシナリオを構成できます。このガイドでは、LINE Payを基準に説明します。
LINE PayとNAVER Payの決済方式は2種類あります。
- 価格入力型:入力された価格でLINE PayとNAVER Payの決済を行います。価格変動のない商品を決済するする際に活用することをお勧めします。
- API連携型:入力された外部URLを呼び出して確認された価格で、 LINE PayやNAVER Pay決済を行います。価格が固定されていないか、ユーザーが選択したスロット情報に応じて価格が変動する場合に使用することをお勧めします。
LINE Pay、NAVER Payサービスと連携させてから使用してください。
価格入力型による決済
価格入力型で決済するアクションメソッドを作成する方法は以下のとおりです。
- NAVERクラウドプラットフォームコンソールでServices > CLOVA Chatbot > Domainメニューを順にクリックします。
- 希望するドメインの [ビルダーを実行する] ボタンをクリックしてチャットボットビルダーを実行します。
- チャットボットビルダーで アクションメソッド > [アクションメソッド作成] ボタンをクリックします。
- タイプでLINE Payを選択します。
- 名前を確認します。
- 価格入力型の場合、アクションメソッドの名前を直接入力せずに価格情報と商品名を入力すると、アクションメソッドの名前が自動補完される
- 価格情報フィールドに、決済する価格を入力します。
- LINE Payの基準通貨は円(¥)
- NAVER Payの基準通貨はウォン(₩)
- 商品名フィールドに、決済する商品の名前を入力します。
API連携型による決済
API連携型で決済するアクションメソッドを作成する方法は以下のとおりです。
- NAVERクラウドプラットフォームコンソールでServices > CLOVA Chatbot > Domainメニューを順にクリックします。
- 希望するドメインの [ビルダーを実行する] ボタンをクリックしてチャットボットビルダーを実行します。
- チャットボットビルダーで アクションメソッド > [アクションメソッド作成] ボタンをクリックします。
- タイプでLINE Payを選択します。
- アクションメソッド名を入力します。
- 価格情報を確認できる外部URLを入力し、[保存] ボタンをクリックします。
例えば、ユーザーがコンビネーションピザSサイズ2枚を注文すると、以下のスロット情報を外部URLに伝達します。Responseとして返される値が「49900」であれば、チャットボットは49,900ウォンをLINE Payで決済します。
@ピザ:コンビネーションピザ
@ピザのサイズ:Sサイズ
@ピザの枚数:2枚
API連携型の場合、連携するAPIで以下のフォームを伝達する必要があります。
{
"productName": "製品名",
"amount": 0,
"currency": "JPY"
}
<例>
CEK Requestの伝達
CEK Requestを特定のURLに伝達するアクションメソッドです。CEK Request伝達アクションメソッドは、JSON(POST)方式のみサポートします。
- NAVERクラウドプラットフォームのコンソールでServices > CLOVA Chatbot > Domainメニューを順にクリックします。
- 希望するドメインの [ビルダーを実行する] ボタンをクリックしてチャットボットビルダーを実行します。
- チャットボットビルダーで アクションメソッド > [アクションメソッド作成] ボタンをクリックします。
- タイプはCEK Requestを選択します。
- 名を入力します。
- CEK Requestを伝達するURLを入力します。
- CEKから伝達されたRequest bodyを伝達します。
- メッセンジャーがCLOVAの場合にのみ動作します。チャットボットビルダーの手動テストや自動テストでは動作しません。
ビルトインアクションメソッド
ビルトインアクションメソッドは、CLOVA Chatbotで独自に提供するアクションメソッドで、チャットボットの以前の発話やコンテキストを活用できます。
- このアクションメソッドは、チャットボット設定 > [ドメイン情報] タブで「会話ログの一時保存」が有効になっている場合にのみ使用できます。会話ログの一時保存が有効になっている状態であれば、アクションメソッドリストに自動的に表示されます。
- メッセンジャー設定がCLOVAである場合か、AiCallドメインでのみ返答に適用できるアクションメソッドです。
以下の画面はビルトインアクションメソッドが有効になっている状態です。各アクションメソッドの [修正] ボタンをクリックすると、そのアクションメソッドの実行が不可能な場合に送信するメッセージを設定できます。(デフォルト値:正しく理解できませんでした。わかりやすく説明していただければ、もう少し正確に回答できると思います。)
${`previousChatbotAnswer}
- マーカーが付いた返答の中から、直近に応答したチャットボットの返答を呼び出して応答することができます。
- 以前の会話のコンテキストではなく、現在の会話のコンテキスト設定に従います。
${`previousChatbotConPtext}
- マーカーが付いた以前の会話のコンテキスト設定に従います。
- 現在の会話のコンテキストには従いません。
${`previousChatbotAnswerContext}
- マーカーが付いた以前の会話のチャットボット返答とコンテキストを読み込むことができます。
- 現在の会話のコンテキストには従いません。