アクションメソッド

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

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

サポートするアクションメソッドは以下のとおりです。

• アクションメソッドV1.0
• アクションメソッドV2.0
• LINE PAY
• Naver Pay
• CEK Requestの転送
• ビルトインアクションメソッド

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

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

アクションメソッドのバージョン別スペック

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

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

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

GET方式でアクションメソッドを作成する方法は以下のとおりです。

1. NAVERクラウドプラットフォームコンソールでServices > CLOVA Chatbot > Domainメニューを順にクリックします。
2. 希望するドメインの [ビルダーを実行する] ボタンをクリックしてチャットボットビルダーを実行します。
3. チャットボットビルダーで アクションメソッドメニューをクリックします。
4. タイプでアクションメソッドV1.0、GETを選択し、名前フィールドにアクションメソッドの名前を入力します。
5. URLフィールドに、呼び出すURLを入力します。
   • $を入力すると登録されているエンティティリストが表示され、エンティティリストからエンティティを選択して追加できる
   • [エコーの呼び出し] ボタンをクリックすると、テスト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 > CLOVA Chatbot > Domainメニューを順にクリックします。
2. 希望するドメインの [ビルダーを実行する] ボタンをクリックしてチャットボットビルダーを実行します。
3. チャットボットビルダーで アクションメソッドメニュー をクリックします。
4. タイプでアクションメソッドV1.0、POSTを選択します。
5. 名前フィールドにアクションメソッドの名前を入力します。
6. URLフィールドに、呼び出すURLを入力します。
   • $を入力すると登録されているエンティティリストが表示され、エンティティリストからエンティティを選択して追加できる
   • [エコーの呼び出し] ボタンをクリックすると、テスト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.point}ポイントです。」と定義した場合、{membership.point}の値は定義したURLを呼び出してResponseで返されるvariableNameのvalueです。nameのvlaueが佐藤一郎、pointのvalueが1,000だったとしたら、チャットボットは「佐藤一郎様のポイント残高は1,000ポイントです。」と返答します。

POST方式でアクションメソッドV2.0を作成する方法は以下のとおりです。

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

API連携型による決済

API連携型で決済するアクションメソッドを作成する方法は以下のとおりです。

1. NAVERクラウドプラットフォームコンソールで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を特定のURLに伝達するアクションメソッドです。CEK Request伝達アクションメソッドは、JSON(POST)方式のみサポートします。

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

ビルトインアクションメソッド

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

以下の画面はビルトインアクションメソッドが有効になっている状態です。各アクションメソッドの [修正] ボタンをクリックすると、そのアクションメソッドの実行が不可能な場合に送信するメッセージを設定できます。(デフォルト値：正しく理解できませんでした。わかりやすく説明していただければ、もう少し正確に回答できると思います。)

${`previousChatbotAnswer}

• マーカーが付いた返答の中から、直近に応答したチャットボットの返答を呼び出して応答することができます。
• 以前の会話のコンテキストではなく、現在の会話のコンテキスト設定に従います。

${`previousChatbotConPtext}

• マーカーが付いた以前の会話のコンテキスト設定に従います。
• 現在の会話のコンテキストには従いません。

${`previousChatbotAnswerContext}

• マーカーが付いた以前の会話のチャットボット返答とコンテキストを読み込むことができます。
• 現在の会話のコンテキストには従いません。