パラメータ

パラメータは、セッション中にエンドユーザーが指定した値を取得して参照するために使用されます。各パラメータには名前とエンティティ タイプがあります。未加工のエンドユーザー入力とは異なり、パラメータは、ロジックの実行やレスポンスの生成に簡単に使用できる構造化データです。

CX パラメータは、ES パラメータと似ていますが、ユーティリティとスコープが拡張され、パラメータを参照する構文が異なります。

パラメータの定義、参照、設定、取得

パラメータを使用する一般的な方法は 4 つあります。

  • 設計時の定義: 設計時に、コンソールまたは API を使用してパラメータを定義します。たとえば、インテント パラメータを定義してトレーニング フレーズで使用し、抽出するエンドユーザー入力を指定できます。
  • 設計時の参照: パラメータ参照は、実行時に抽出されるパラメータ値を保持する変数です。設計時には、コンソールまたは API を使用してさまざまなデータ型のパラメータを参照できます。たとえば、ルートの静的フルフィルメント レスポンスでセッション パラメータを参照できます。
  • 実行時の設定: パラメータ値を、Dialogflow サービス、API を呼び出すサービス、Webhook サービスのすべてでランタイムに設定できます。たとえば、Dialogflow サービスは、エンドユーザー入力がインテントと一致し、入力にパラメータ データが含まれている場合に、インテント パラメータの値を設定します。
  • 実行時に取得: 実行時に、パラメータ参照には設定されたパラメータ値が含まれます。このパラメータ値は、API または Webhook を使用して取得できます。たとえば、インテントが一致し、Webhook が呼び出されると、Webhook サービスはインテントのパラメータ値を受け取ります。

パラメータの命名

パラメータの命名には次のルールが適用されます。

  • 使用する文字は [A-Z][a-z][0-9].-_ です。
  • パラメータ名では、大文字と小文字は区別されません。つまり、Dialogflow では Appleapple は同じパラメータとして扱われます。Webhook と API クライアント コードでも、大文字と小文字は区別されません。これは、Dialogflow から返されるパラメータ名に大文字と小文字の区別がないためです。

インテント パラメータ

インテントは、パラメータを使用して、インテントが一致したときにエンドユーザーから提供されたデータを抽出します。インテント パラメータを定義するには、次のデータを使用します。

  • NameID または Display Name とも呼ばれます): パラメータを識別する名前。
  • Entity Type: パラメータに関連付けられたエンティティ タイプ
  • Is List: true の場合、パラメータは値のリストとして扱われます。
  • Redact in log: true の場合、エンドユーザーが指定したパラメータ データが秘匿化されます。

インテント パラメータを定義する

インテント パラメータは、インテント データを作成する、またはトレーニング フレーズにアノテーションを付ける場合に、設計時に定義されます。

参照インテント パラメータ

インテント パラメータ参照は、インテント ルートの静的フルフィルメント レスポンス メッセージで使用できます。

実行時にテキストが特定のエンティティに一致すると、処理に便利な値に変換されることがよくあります。たとえば、エンドユーザーの入力に含まれる単語「apples」は、果物のエンティティについては「apple」として抽出されることがあります。エンドユーザーが書いた(または話した)original 値、あるいはエンティティによって抽出された resolved 値を参照できます。

現在一致しているインテントのパラメータを参照するには、次のいずれかの形式を使用します。

$intent.params.parameter-id.original
$intent.params.parameter-id.resolved

たとえば、パラメータ ID が date の場合は、解決された値を $intent.params.date.resolved として参照できます。

インテント パラメータを設定する

エンドユーザー入力が実行時にインテントと一致すると、関連付けられたトレーニング フレーズのアノテーションによって使用されるパラメータが Dialogflow によって設定されます。

インテント ルートのフルフィルメントでは、フルフィルメント パラメータ プリセットを使用して、実行時にインテント パラメータ値を設定できます。

インテント パラメータを取得する

インテントが一致する会話のターンでは、コードでインテント パラメータ値にアクセスできます。

API を操作すると、インテント パラメータ値が返されます。Session 型に対する detectIntent メソッドの queryResult.parameters レスポンス フィールドをご覧ください。

セッション リファレンスのプロトコルとバージョンを選択:

プロトコル V3 V3beta1
REST セッション リソース セッション リソース
RPC セッション インターフェース セッション インターフェース
C# 提供なし 利用できません
Go 提供なし 利用できません
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP 提供なし 利用できません
Python SessionsClient SessionsClient
Ruby 提供なし 利用できません

Webhook の受信インテント パラメータの値。Webhook リクエストintentInfo.parameters フィールドをご覧ください。

フォーム パラメータ

ページごとにフォームを定義できます。これは、ページのエンドユーザーから収集する必要があるパラメータのリストです。エージェントは、必要なすべてのフォーム パラメータ(ページ パラメータとも呼ばれます)を収集するまで、複数の会話ターンでエンドユーザーとやり取りします。フォーム パラメータごとに、エージェントがエンドユーザーからの情報をリクエストするために使用するプロンプトも表示します。このプロセスをフォーム入力と呼びます。

たとえば、Collect Customer Info ページのエンドユーザーの名前と電話番号を収集するフォームを作成できます。

CX フォームの入力は、ES スロットの入力に似ています。

フォーム パラメータを定義するには、次のデータを使用します。

  • NameID または Display Name とも呼ばれます): パラメータを識別する名前。
  • Entity Type: パラメータに関連付けられたエンティティ タイプ
  • Is List: true の場合、パラメータは値のリストとして扱われます。
  • Redact in log: true の場合、エンドユーザーが指定したパラメータ データが秘匿化されます。
  • Required: パラメータが必須かどうかを示します。オプションのパラメータはプロンプトをトリガーしません。ただし、ユーザーが指定した場合には入力されます。フォーム入力が完了する前に、必須パラメータを入力する必要があります。
  • Default Value:オプション パラメータのデフォルト値。パラメータが必須の場合、デフォルト値は無視されます。
  • Initial Prompt Fulfillment: エージェントが最初にエンドユーザーにパラメータの入力を促す必要があるときに使用されるフルフィルメントで構成されます。
  • Reprompt Handlers: 一度失敗した後にエージェントがエンドユーザーに再びパラメータの入力を促す必要がある場合に使用します。フォーム入力のリプロンプト ハンドラをご覧ください。

フォーム パラメータを定義する

フォーム パラメータは、ページを作成する場合に設計時に定義されます。

参照フォーム パラメータ

フォーム パラメータのリファレンスは直接使用されません。個々のフォーム パラメータまたはフォーム全体の入力ステータスのみを確認できます。フォーム ステータスのリファレンスは、条件ルート条件要件で使用できます。

現在のページのすべてのフォームが入力されているかどうかを確認するには、次の条件を使用します。

$page.params.status = "FINAL"

最後のターンで特定のフォーム パラメータが入力されたかどうかを確認するには、次の条件を使用します。

$page.params.parameter-id.status = "UPDATED"

フォーム パラメータを設定する

ルート、イベント ハンドラ、フォーム リプロンプトのフルフィルメントでは、フルフィルメント パラメータ プリセットを使用して、実行時にフォーム パラメータ値を設定できます。

Webhook では、実行時にフォーム パラメータの値を設定できます。Webhook レスポンスpageInfo.formInfo.parameterInfo フィールドをご覧ください。

フォーム パラメータを取得する

API を操作すると、フォーム パラメータの値が返されます。Session 型に対する detectIntent メソッドの queryResult.parameters レスポンス フィールドをご覧ください。

セッション リファレンスのプロトコルとバージョンを選択:

プロトコル V3 V3beta1
REST セッション リソース セッション リソース
RPC セッション インターフェース セッション インターフェース
C# 提供なし 利用できません
Go 提供なし 利用できません
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP 提供なし 利用できません
Python SessionsClient SessionsClient
Ruby 提供なし 利用できません

Webhook の受信フォーム パラメータの値。Webhook リクエストpageInfo.formInfo.parameterInfo フィールドをご覧ください。

フォーム入力のリプロンプト ハンドラ

フォームの入力中に、エージェントは、エンドユーザーにパラメータ値を指定するよう求めます。エンドユーザーが予期しない入力で応答すると、sys.no-match-* イベントまたは sys.no-input-* イベントが呼び出されます。リプロンプト ハンドラ(パラメータ レベル イベント ハンドラとも呼ばれます)を定義して、エンドユーザーにパラメータ値の再入力を求めることができます。

他のイベント ハンドラと同様に、リプロンプト ハンドラは次のいずれかまたは両方で構成できるタイプのステート ハンドラです。

  • エンドユーザーのリプロンプト メッセージやパラメータ プリセットを指定するためのフルフィルメント。
  • 現在のページを変更するための遷移ターゲット。

セッション パラメータ

実行時に任意のタイプのパラメータが設定されると、パラメータがセッションに書き込まれ、セッション パラメータになります。これらのパラメータは、設計時には明示的に定義されません。これらのセッション パラメータを、セッション中の任意の時点で参照できます。

参照セッション パラメータ

セッション パラメータ参照は、次のタイプのフルフィルメントの静的レスポンス メッセージで使用できます。

  • ページ エントリのフルフィルメント
  • ルートのフルフィルメント
  • イベント ハンドラのフルフィルメント
  • フォーム プロンプトのフルフィルメント
  • フォーム リプロンプトのフルフィルメント

セッション パラメータを参照するには、次の形式を使用します。

スカラー

スカラー エンティティ型のパラメータにアクセスするには、次のコマンドを実行します。

$session.params.parameter-id

たとえば、パラメータ ID が date の場合は、その値を $session.params.date として参照できます。

複合

複合エンティティ タイプのパラメータ メンバーにアクセスするには、次のコマンドを実行します。

$session.params.parameter-id.member-name

たとえば、パラメータ ID が location の場合は、その zip-code メンバー値を $session.params.location.zip-code として参照できます。

定価

  • 要素の完全なリストにアクセスするには次のコマンドを実行します。

    $session.params.parameter-id

    たとえば、リスト パラメータ ID が colors で、ユーザークエリから抽出した値が ["red", "blue", "yellow"] の場合、すべての値を $session.params.colors として参照できます。

  • リスト パラメータの ith 要素にアクセスするには次のコマンドを実行します。

    $session.params.parameter-id[i]

    たとえば、リスト パラメータ ID が colors の場合、最初の値を $session.params.colors[0] として参照できます。

セッション パラメータを設定する

フォームの入力が完了すると、入力したパラメータが Dialogflow によってセッションに書き込まれます。

ルート、イベント ハンドラ、フォーム リプロンプトのフルフィルメントでは、フルフィルメント パラメータ プリセットを使用して、実行時にセッション パラメータ値を設定できます。

Webhook では、実行時にセッション パラメータの値を設定できます。Webhook レスポンスsessionInfo.parameters フィールドをご覧ください。

API を操作すると、セッション パラメータ値を設定できます。Session 型に対する detectIntent メソッドの queryParams.parameters リクエスト フィールドをご覧ください。

セッション リファレンスのプロトコルとバージョンを選択:

プロトコル V3 V3beta1
REST セッション リソース セッション リソース
RPC セッション インターフェース セッション インターフェース
C# 提供なし 利用できません
Go 提供なし 利用できません
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP 提供なし 利用できません
Python SessionsClient SessionsClient
Ruby 提供なし 利用できません

セッション パラメータを取得する

API を操作すると、セッション パラメータ値が返されます。Session 型に対する detectIntent メソッドの queryResult.parameters レスポンス フィールドをご覧ください。

セッション リファレンスのプロトコルとバージョンを選択:

プロトコル V3 V3beta1
REST セッション リソース セッション リソース
RPC セッション インターフェース セッション インターフェース
C# 提供なし 利用できません
Go 提供なし 利用できません
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP 提供なし 利用できません
Python SessionsClient SessionsClient
Ruby 提供なし 利用できません

Webhook の受信セッション パラメータの値。Webhook リクエストsessionInfo.parameters フィールドをご覧ください。

パラメータの伝播

エンドユーザーがパラメータ値を入力すると、パラメータは他のレベルに伝播されます。

  • インテント マッチによってインテント パラメータが設定されると、アクティブなページの類似の名前のフォーム パラメータが同じ値に設定されます。パラメータのエンティティ タイプはインテント パラメータ定義によって規定されます。
  • インテント マッチによってインテント パラメータが設定されている場合や、フォームへの入力中にフォーム パラメータが設定されている場合、パラメータはセッション パラメータになります。

テレフォニー パートナー統合の DTMF

パラメータに対して DTMF(デュアルトーン マルチ周波数信号)を有効にして構成できます。有効にすると、テレフォニー パートナー 統合を使用するエージェントのエンドユーザーは、電話キーパッドを使用してパラメータ値を指定できます。

あいまいさを軽減するために、DTMF 入力は、通常の形式と DTMF 固有の形式(推奨)の両方で解釈できます。

  • 通常の形式は、エンドユーザーが入力したキーパッド値にすぎません。例:123#
  • DTMF 固有の形式は、入力を dtmf_digits_[digits] に変換します。ここで、[digits] は元の DTMF ディジットの *star に置き換え、#pound に置き換えたものです。たとえば、123#dtmf_digits_123pound として解釈されます。

パラメータのエンティティ タイプを一致させる場合、Dialogflow は通常の形式と DTMF 固有の形式の両方を一致させようとします。DTMF 入力にエンティティ タイプを使用する場合、NLU マッチングを改善するために dtmf_digits_123 などの類義語を定義することをおすすめします。

DTMF 入力が終了条件を満たしていない場合(最大の桁数に到達していない、または終了ディジットによって終了していない)、Dialogflow エージェントは追加入力の待機を継続します。この待機の期間中に、音声なしタイムアウトがトリガーされた場合、エージェントは no-input イベントを代わりに呼び出します。発話が検出された場合、エージェントは音声文字起こしと照合を行います。どちらの場合も、既存の DTMF 入力は削除されます。

パラメータに対して DTMF を有効にしてカスタマイズするには:

コンソール

  1. エージェントの音声と IVR の設定で [Advanced settings] が有効になっていない場合は、有効にします。
  2. ページ パラメータを作成します。
  3. パラメータ ペインで、[Max digits] をオンにします。
  4. [Max digits] に、エンドユーザーがこのパラメータに入力できる最大数を設定します。
  5. [Finishdigit] を、パラメータの DTMF 入力を終了するキーパッド値に設定します。通常、この設定には # を使用します。 終了ディジットはエージェントの Dialogflow クエリには追加されません。つまり、終了ディジットが # で、入力が 123# の場合、実際のクエリ入力は「123」になります。

パラメータの秘匿化

インテント パラメータまたはフォーム パラメータの場合、パラメータの秘匿化を有効にできます。これにより、ログと Dialogflow の内部ストレージからエンドユーザーのランタイム パラメータ データが秘匿化されます。秘匿化されたパラメータは、ログで $parameter-name_redacted として表示されます。

たとえば、エンドユーザーが「My address is 1600 Amphitheatre Parkway」と入力した場合、「1600 Amphitheatre Parkway」に address パラメータが送信されることになります。ログテキストは「My address is $address_redacted」になります。

パラメータの秘匿化を有効にするには:

コンソール

パラメータの作成時または更新時に [Redact in log] チェックボックスをオンにします。

API

Intent タイプで parameters[].redact フィールドを true に設定します。

インテント リファレンスのプロトコルとバージョンを選択:

プロトコル V3 V3beta1
REST インテント リソース インテント リソース
RPC インテント インターフェース インテント インターフェース
C# 提供なし 利用できません
Go 提供なし 利用できません
Java IntentsClient IntentsClient
Node.js IntentsClient IntentsClient
PHP 提供なし 利用できません
Python IntentsClient IntentsClient
Ruby 提供なし 利用できません

Page タイプで form.parameters[].redact フィールドを true に設定します。

ページ リファレンスのプロトコルとバージョンを選択:

プロトコル V3 V3beta1
REST ページリソース ページリソース
RPC ページ インターフェース ページ インターフェース
C# 提供なし 利用できません
Go 提供なし 利用できません
Java PagesClient PagesClient
Node.js PagesClient PagesClient
PHP 提供なし 利用できません
Python PagesClient PagesClient
Ruby 提供なし 利用できません