アクションメソッド

Classic/VPC環境で利用できます。

アクションメソッド(ActionMethod)を用いてチャットボットと外部システムのデータを連携できます。アクションメソッドを用いると、APIを呼び出したり、APIの呼び出し時にユーザーとの会話で分析された内容を転送したり、APIから返された結果を受け取って回答するのに活用できます。例えば、価格情報、ユーザー情報、天気情報などの可変的なデータをデータベースからリアルタイムで取得し、回答として提供できます。
作成したアクションメソッドは ${ActionMethodName}形式に定義して使用します。会話の回答登録時に使用するアクションメソッドを{ActionMethodName}形式で入力すると、その回答が返される際にアクションメソッドを呼び出すことができます。

サポートするアクションメソッドは次の通りです。

• アクションメソッド V1.0
• アクションメソッド V2.0
• LINE Pay
• NAVER Pay
• CEK Request転送
• Built inアクションメソッド

アクションメソッドのパラメータ

アクションメソッドを用いて Backend Systemに情報を送るには、定義されたパラメータ形式が必要です。このとき、「エンティティ」が用いられます。事前に定義されたエンティティはユーザーのデータとマッピングする keyです。また、アクションメソッドを使用するには、エンティティが一緒に定義されて動作する必要があります。事前に定義されたエンティティはアクションメソッドでも使用できます。

アクションメソッドのバージョン別仕様

アクションメソッド V1.0

アクションメソッドを作成する前に、アクションメソッドで活用するドメインエンティティを作成します。作成されたアクションメソッドを回答フィールドに入力すると、レスポンスを返す際にそのアクションメソッドを呼び出します。
例えば、回答を「現在、亭子洞の天気は${weather}度です。」と定義した場合、${weather}の値はアクションメソッドで定義した URLを呼び出し、Responseとして返ってくる情報です。その値が「24」の場合、チャットボットは「現在、亭子洞の気温は24度です。」と回答します。ただし、アクションメソッド V1.0は、1つの回答につき最大2つまで入力できます。

GET方式によるアクションメソッド作成

GET方式でアクションメソッドを作成する方法は、次の通りです。

1. NAVERクラウドプラットフォームコンソールで、 > Services > AI Services > CLOVA Chatbot > Domainメニューを順にクリックします。
2. 希望するドメインの [ビルダを実行する] ボタンをクリックしてチャットボットビルダを実行します。
3. チャットボットビルダでアクションメソッドメニューをクリックします。
4. タイプでアクションメソッド V1.0、GETを選択し、名前フィールドにアクションメソッドの名前を入力します。
5. URLフィールドに、呼び出す URLを入力します。
   • $を入力すると登録されているエンティティリストが表示され、エンティティリストからエンティティを選択して追加可能
   • [echo呼び出し] ボタンをクリックすると、テスト APIを自動で入力。このアクションメソッドを呼び出すとチャットボットエンジンから外部 APIサーバに転送される Requestがそのまま表示されるため、どんな方式で Requestされるか確認可能
     
6. 値の転送オプションを選択します。
   • CLOVA認証 Access Token: CLOVA Extensionで認証されたユーザーアカウントの Access Tokenを取得し、ユーザーリクエストを転送可能
   • Session Attributes: UTF-8でエンコードされた特定の文字列を X-KAA-SESSION-ATTRIBUTESヘッダに含めて送信可能
7. [保存] ボタンをクリックします。
   • 作成したアクションメソッドは、回答の入力時に{$アクションメソッド名}の方式で活用可能

レスポンス形式

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 ={}

JSON(POST)方式によるアクションメソッド作成

JSON(POST)方式は GET方式と同じですが、URLの呼び出しにデータを含めて送信できます。データは JSON形式で送ります。エンティティデータ以外にも特定の値を一緒に転送することができます。
POST方式でアクションメソッドを作成する方法は、次の通りです。

1. NAVERクラウドプラットフォームコンソールで、 > Services > AI Services > CLOVA Chatbot > Domainメニューを順にクリックします。
2. 希望するドメインの [ビルダを実行する] ボタンをクリックしてチャットボットビルダを実行します。
3. チャットボットビルダでアクションメソッドメニューをクリックします。
4. タイプをアクションメソッド V1.0、POSTとして選択します。
5. 名前フィールドにアクションメソッドの名前を入力します。
6. URLフィールドに、呼び出す URLを入力します。
   • $を入力すると登録されているエンティティリストが表示され、エンティティリストからエンティティを選択して追加可能
   • [echo呼び出し] ボタンをクリックすると、テスト APIを自動で入力。このアクションメソッドを呼び出すとチャットボットエンジンから外部 APIサーバに転送される Requestがそのまま表示されるため、どんな方式で Requestされるか確認可能
7. データフィールドに、JSON形式にしてマッピングするエンティティ名を入力します。
   
8. 値の転送オプションを選択します。
   • CLOVA認証 Access Token: CLOVA Extensionで認証されたユーザーアカウントの Access Tokenを取得し、ユーザーリクエストを転送可能
   • Session Attributes: X-KAA-SESSION-ATTRIBUTESヘッダに文字列をエンコードして格納すると、アクションメソッド呼び出し時に X-KAA-SESSION-ATTRIBUTESの値がチャットボットエンジンによってキャッシュされる。Session Attributesオプションが有効になっているアクションメソッドを呼び出す場合、キャッシュしておいた X-KAA-SESSION-ATTRIBUTESに保存された文字列を一緒に渡す
9. [保存] ボタンをクリックします。
   • 作成したアクションメソッドは、回答の入力時に{$アクションメソッド名}の方式で活用可能

リクエスト形式

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"} 

アクションメソッド V2.0

アクションメソッド V2.0は、1回の呼び出しで複数の値を取得できるという点でアクションメソッド V1.0とは異なります。
例えば、回答フィールドに「${membership.name} 様の残りのポイントは${membership.point}ポイントです。」と定義した場合、${membership.name} と${membership.point}の値は、定義した URLを呼び出して Responseとして返ってくる variableNameの valueです。nameの valueが佐藤一郎、pointの valueが 1000の場合、チャットボットは「佐藤一郎様の残りのポイントは1000ポイントです。」と回答します。

POST方式でアクションメソッド V2.0を作成する方法は、次の通りです。

1. NAVERクラウドプラットフォームコンソールで、 > Services > AI Services > CLOVA Chatbot > Domainメニューを順にクリックします。
2. 希望するドメインの [ビルダを実行する] ボタンをクリックしてチャットボットビルダを実行します。
3. チャットボットビルダでアクションメソッドメニューをクリックします。
4. タイプをアクションメソッド 2.0、POSTとして選択します。
5. 名前フィールドにアクションメソッドの名前を入力します。
6. URLフィールドに、呼び出す URLを入力します。
   • $を入力すると登録されているエンティティリストが表示され、エンティティを選択して追加できます。
   • [echo呼び出し] ボタンをクリックすると、アクションメソッド V2.0をテスト可能
     • $2{アクションメソッド名.method}を入力すると、methodをエコーする(POSTが返される)
     • $2{アクションメソッド名.body}を入力すると、bodyをエコーする
       
7. [保存] ボタンをクリックします。
   • 作成したアクションメソッドは、回答の入力時に$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が指定可能です)"
      }
    }
  }
}

レスポンス形式

{
  "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"
  }
  ]
}

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決済を行います。価格が固定されていないか、ユーザーが選択したスロット情報に応じて価格が変動する場合に使用することをお勧めします。

価格入力型による決済

価格入力型で決済するアクションメソッドを作成する方法は、次の通りです。

1. NAVERクラウドプラットフォームコンソールで、 > Services > AI Services > CLOVA Chatbot > Domainメニューを順にクリックします。
2. 希望するドメインの [ビルダを実行する] ボタンをクリックしてチャットボットビルダを実行します。
3. チャットボットビルダでアクションメソッド > [アクションメソッド作成] ボタンをクリックします。
4. タイプを LINE Payとして選択します。
5. 名前を確認します。
   • 価格入力型の場合、アクションメソッドの名前を直接入力せずに価格情報と商品名を入力すると、アクションメソッドの名前が自動補完される
6. 価格情報フィールドに、決済する価格を入力します。
   • LINE Payの基準通貨は円(¥)
   • NAVER Payの基準通貨はウォン(₩)
7. 商品名フィールドに、決済する商品の名前を入力します。
   

API連携型による決済

API連携型で決済するアクションメソッドを作成する方法は、次の通りです。

1. NAVERクラウドプラットフォームコンソールで、 > Services > AI Services > CLOVA Chatbot > Domainメニューを順にクリックします。
2. 希望するドメインの [ビルダを実行する] ボタンをクリックしてチャットボットビルダを実行します。
3. チャットボットビルダでアクションメソッド > [アクションメソッド作成] ボタンをクリックします。
4. タイプを LINE Payとして選択します。
5. アクションメソッド名を入力します。
6. 価格情報を確認できる外部 URLを入力し、 [保存] ボタンをクリックします。

例えば、ユーザーがコンビネーションピザ Sサイズ2枚を注文すると、以下のスロット情報を外部 URLに転送します。Responseとして返される値が「49900」の場合、チャットボットは49,900ウォンを LINE Payで決済します。

@ピザ: コンビネーションピザ
@ピザのサイズ: Sサイズ
@ピザの数量: 2枚

API連携型の場合、連携する APIで以下のフォームを転送する必要があります。

{
  "productName": "製品名",
  "amount": 0,
  "currency": "JPY"
}

例)

CEK Request転送

CEK Requestをすべて bypassするアクションメソッドです。CEK Request転送アクションメソッドは、JSON(POST)方式のみサポートします。

1. NAVERクラウドプラットフォームコンソールで、 > Services > AI Services > CLOVA Chatbot > Domainメニューを順にクリックします。
2. 希望するドメインの [ビルダを実行する] ボタンをクリックしてチャットボットビルダを実行します。
3. チャットボットビルダでアクションメソッド > [アクションメソッド作成] ボタンをクリックします。
4. タイプを CEK Requestとして選択します。
5. 名前を入力します。
6. CEK Requestを転送する URLを入力します。
   • CEKから転送された Request bodyを転送します。
   • メッセンジャーが CLOVAの場合にのみ動作します。チャットボットビルダの手動テストや自動テストでは動作しません。

Built inアクションメソッド

ビルトインアクションメソッドは、CLOVA Chatbotで独自に提供するアクションメソッドで、チャットボットの以前の発話やコンテキストを活用できます。

以下の画面は Built inアクションメソッドが有効になっている状態です。各アクションメソッドの [変更] ボタンをクリックすると、そのアクションメソッドの実行が不可能な場合に送信するメッセージを設定できます。(デフォルト値: よく理解できませんでした。分かりやすく説明していただければ、より良い答えができます)。

• ${`previousChatbotAnswer}
  • マーカーが付いた回答のうち、直近にレスポンスしたチャットボットの回答を呼び出してレスポンスできます。
  • 以前の会話のコンテキストではなく、現在の会話のコンテキスト設定に従います。
• ${`previousChatbotConPtext}
  • マーカーが付いた以前の会話のコンテキスト設定に従います。
  • 現在の会話のコンテキストには従いません。
• ${`previousChatbotAnswerContext}
  • マーカーが付いた以前の会話のチャットボット回答とコンテキストを読み込むことができます。
  • 現在の会話のコンテキストには従いません。