ここでは、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 などのデータを ユーザー（音声コンポーネントやビジュアル コンポーネントを含む）のほか、 （これを「想定されたインテント」と呼びます）。想定される動作 インテントには、前述したように、アシスタントが理解するインテントのいずれかを指定できます。 Intents 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
value は、変更前にアシスタントがユーザーに表示または出力する内容を示します。
会話が終了します。
{ "expectUserResponse": false, "finalResponse": { "richResponse": { "items": [ { "simpleResponse": { "textToSpeech": "Good bye" } } ] } } }
ユーザーが標準の アシスタントとの会話を終了するには 会話の終了。