会話 Webhook 形式

ここでは、Actions on Google が Actions SDK を通じてフルフィルメントを呼び出すときの JSON ペイロードの形式について説明します。

会話が開始されると、固有の conversationId によって識別されます。それ以降のアシスタントへの各ユーザークエリに対して、フルフィルメントは、Webhook が処理して応答する必要のあるインテントを受け取ります。この conversationId は、会話が終了するまで、すべてのリクエストとレスポンスのペアに保持されます。

リクエストの本文

ユーザーが最初のクエリを行うか、その後なんらかの入力を行うと、アシスタントはフルフィルメントにリクエストを送信します。アシスタントからの会話 Webhook リクエストには、トリガーされたインテント、ユーザー入力の生テキスト、ユーザーのデバイスのサーフェス機能などのデータが含まれています。

会話 Webhook 形式のリクエストのキーフィールドは以下のとおりです。

フィールド 説明
isInSandbox このブール変数は主にトランザクション機能のために使用され、Webhook がサンドボックス モードでこのリクエストを処理するかどうかを示します。サンドボックス モードでは、Webhook はユーザーからの注文の実行や課金を行ってはいけません。デフォルトでは「true」に設定されています。
surface ユーザーが対話しているアシスタント サーフェスとその機能に関する情報。
Inputs 呼び出しリクエストに関する情報。トリガー呼び出しの場合、これにはアクションにマッピングされるインテントが含まれます。会話内の後続のリクエストの場合、このオブジェクトには、フルフィルメントで指定された期待される入力に対応する引数も含まれる可能性があります。
User リクエストを開始したユーザーに関する情報。この情報には、ユーザーによって付与された権限と、ユーザーの言語 / 地域が含まれます。
Conversation 会話 ID、タイプ(このリクエストが新しい会話を開始しているかどうかなど)、会話の存続期間にわたって永続データを格納するための会話トークンなど、会話コンテキストに関する情報。
availableSurfaces この情報はマルチサーフェス会話に使用されます。

単純な呼び出しリクエストの例

以下のスニペットは、会話 Webhook 形式の呼び出しリクエストの例を示しています。

{
  "user": {
    "userId": "ABwppHEF...",
    "locale": "en-US",
    "lastSeen": "2018-03-21T17:59:52Z",
    "userStorage": "{\"data\":{}}"
  },
  "device": {},
  "surface": {
    "capabilities": [
      {
        "name": "actions.capability.SCREEN_OUTPUT"
      },
      {
        "name": "actions.capability.AUDIO_OUTPUT"
      },
      {
        "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
      },
      {
        "name": "actions.capability.WEB_BROWSER"
      }
    ]
  },
  "conversation": {
    "conversationId": "1521784527171",
    "type": "NEW"
  },
  "inputs": [
    {
      "intent": "actions.intent.MAIN",
      "rawInputs": [
        {
          "inputType": "VOICE",
          "query": "Talk to my test app"
        }
      ]
    }
  ],
  "availableSurfaces": [
    {
      "capabilities": [
        {
          "name": "actions.capability.SCREEN_OUTPUT"
        },
        {
          "name": "actions.capability.AUDIO_OUTPUT"
        },
        {
          "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
        },
        {
          "name": "actions.capability.WEB_BROWSER"
        }
      ]
    }
  ]
}

単純な会話リクエストの例

以下のスニペットは、ユーザー入力がテキスト文字列(「My lucky number is 88」)である会話 Webhook 形式の会話リクエストの例を示しています。

{
  "user": {
    "userId": "ABwppHEF...",
    "locale": "en-US",
    "lastSeen": "2018-03-21T17:59:52Z",
    "userStorage": "{\"data\":{}}"
  },
  "device": {},
  "surface": {
    "capabilities": [
      {
        "name": "actions.capability.SCREEN_OUTPUT"
      },
      {
        "name": "actions.capability.AUDIO_OUTPUT"
      },
      {
        "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
      },
      {
        "name": "actions.capability.WEB_BROWSER"
      }
    ]
  },
  "conversation": {
    "conversationId": "1521784527171",
    "type": "NEW"
  },
  "inputs": [
    {
      "intent": "actions.intent.TEXT",
      "rawInputs": [
        {
          "inputType": "VOICE",
          "query": "My lucky number is 88."
        }
      ]
    }
  ],
  "availableSurfaces": [
    {
      "capabilities": [
        {
          "name": "actions.capability.SCREEN_OUTPUT"
        },
        {
          "name": "actions.capability.AUDIO_OUTPUT"
        },
        {
          "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
        },
        {
          "name": "actions.capability.WEB_BROWSER"
        }
      ]
    }
  ]
}

レスポンスの本文

フルフィルメント エンドポイントからアシスタントへの HTTP POST のヘッダーの Content-Type は、application/json にする必要があります。

会話 Webhook 形式のレスポンスには、ユーザーに表示する実際の UI(オーディオやビジュアル コンポーネントを含む)や、その後のリクエストで発生する可能性があるインテント(「期待されるインテント」と呼ばれます)などのデータが含まれます。インテント API リファレンスに記載されているように、期待されるインテントには、アシスタントが理解するインテントのいずれかを指定できます。

レスポンスがアシスタントに表示されるときに、ユーザー インターフェースを自分のレスポンス用にフォーマットする方法の詳細については、レスポンスのドキュメントをご覧ください。

単純なレスポンス例

以下のスニペットは、会話 Webhook 形式の単純なレスポンスの例を示しています。

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "You are using the Actions SDK. Do you want to hear more about it?"
              }
            }
          ]
        }
      }
    }
  ]
}

ヘルパーの例

以下のスニペットは、会話 Webhook 形式でヘルパー インテントを使用する例を示しています。この例では、Webhook は actions.intent.OPTIONS ヘルパー インテントを使用して、複数のオプションからユーザー選択を取得するようにアシスタントに指示しています。

ヘルパー インテントの使い方の詳細については、ヘルパーガイドをご覧ください。

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.OPTION",
          "inputValueData": {
            "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
            "carouselSelect": {
              "items": [
                {
                  "optionInfo": {
                    "key": "one",
                    "synonyms": [
                      "synonym of KEY_ONE 1",
                      "synonym of KEY_ONE 2"
                    ]
                  },
                  "description": "Description of number one",
                  "title": "Number one"
                },
                {
                  "optionInfo": {
                    "key": "two",
                    "synonyms": [
                      "synonym of KEY_TWO 1",
                      "synonym of KEY_TWO 2"
                    ]
                  },
                  "description": "Description of number two",
                  "title": "Number two"
                }
              ]
            }
          }
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "this shows an example of a carousel"
              }
            }
          ],
          "suggestions": [
            {
              "title": "1"
            },
            {
              "title": "2"
            }
          ]
        }
      }
    }
  ]
}

会話の終了の例

以下のスニペットは、会話 Webhook のレスポンス形式で会話セッションを終了する単純なレスポンスの例を示しています。

レスポンス メッセージ内の expectedUserResponse 値が false の場合、それ以上のユーザー入力は期待されておらず、現在の会話を終了する必要があることをアシスタントに通知します。finalResponse 値は、会話が終了する前にアシスタントがユーザーに表示または出力する内容を示します。

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "simpleResponse": {
            "textToSpeech": "Good bye"
          }
        }
      ]
    }
  }
}

ユーザーが標準フレーズを呼び出してアシスタントとの会話を終了したときにデフォルトの動作をオーバーライドする方法については、アプリ終了ガイドをご覧ください。