В этом разделе описывается формат полезных данных JSON, когда Actions on Google вызывает ваше выполнение через Actions SDK .
Как только разговор начинается, он идентифицируется уникальным идентификатором conversationId . Для каждого последующего запроса пользователя к Ассистенту ваше выполнение получает намерение , которое ваш вебхук должен обработать и на него ответить. Этот conversationId сохраняется в каждой паре запрос-ответ до тех пор, пока разговор не завершится.
Тело запроса
Когда пользователи делают первоначальный запрос или вводят какие-либо последующие данные, Ассистент отправляет запрос на ваше выполнение. Запросы веб-перехватчика беседы от Ассистента содержат такие данные, как инициированное намерение, необработанный текст ввода пользователя и поверхностные возможности устройства пользователя.
Ключевые поля для запроса в формате веб-перехватчика беседы кратко описаны ниже:
| Поле | Описание |
|---|---|
isInSandbox | Эта логическая переменная в основном используется для функции транзакций , чтобы указать, должен ли ваш веб-перехватчик обрабатывать этот запрос в режиме песочницы. В режиме песочницы ваш вебхук не должен взимать плату или выполнять заказы пользователей на покупку. По умолчанию установлено значение « true ». |
surface | Информация о поверхности Ассистента, с которой взаимодействует пользователь, и ее возможностях. |
Inputs | Информация о запросе на вызов. Для запускающего вызова это включает в себя намерение , которое соответствует действию. Для последующих запросов в диалоге этот объект также может включать аргументы, соответствующие ожидаемым входным данным, указанным в вашем выполнении. |
User | Информация о пользователе, инициировавшем запрос. Эта информация включает разрешения, предоставленные пользователем, и языковой стандарт пользователя. |
Conversation | Информация о контексте диалога, включая идентификатор диалога, тип (например, инициирует ли этот запрос новый диалог) и токен диалога для хранения постоянных данных на протяжении всего жизненного цикла диалога. |
availableSurfaces | Эта информация используется для разговоров с несколькими поверхностями . |
Простой пример запроса на вызов
В приведенном ниже фрагменте показан пример запроса на вызов в формате веб-перехватчика беседы.
{ "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" } ] } ] }
Пример простого запроса на разговор
Во фрагменте ниже показан пример диалогового запроса в формате веб-перехватчика диалога, где пользовательский ввод представляет собой текстовую строку (например, «Мой счастливый номер — 88» ).
{ "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" } ] } ] }
Тело ответа
Content-Type сообщений от вашей конечной точки выполнения до Ассистента должен быть application/json .
Ответ в формате веб-перехватчика диалога содержит такие данные, как фактический пользовательский интерфейс, отображаемый пользователю (включая аудио- и визуальные компоненты), а также намерение, которое может быть вызвано в последующем запросе (называемое ожидаемым намерением ). Ожидаемым намерением может быть любое из намерений, которые понимает Помощник, как описано в справочнике по API намерений .
Чтобы узнать больше о форматировании пользовательского интерфейса для ваших ответов, когда они отображаются в Ассистенте, см. документацию по ответам .
Простой пример ответа
В приведенном ниже фрагменте показан пример простого ответа в формате веб-перехватчика беседы.
{ "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?" } } ] } } } ] }
Вспомогательный пример
Во фрагменте ниже показан пример использования вспомогательного намерения в формате веб-перехватчика беседы. В этом примере вебхук использует вспомогательное намерение 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" } ] } } } ] }
Пример завершения разговора
В приведенном ниже фрагменте показан пример простого ответа на завершение сеанса беседы в формате ответа веб-перехватчика беседы.
Значение false expectedUserResponse » в ответном сообщении сигнализирует помощнику, что дальнейших действий пользователя не ожидается и что текущий разговор следует завершить. Значение finalResponse указывает, что Ассистент должен отобразить или вывести пользователю перед завершением разговора.
{ "expectUserResponse": false, "finalResponse": { "richResponse": { "items": [ { "simpleResponse": { "textToSpeech": "Good bye" } } ] } } }
Чтобы узнать, как переопределить поведение по умолчанию, когда пользователи вызывают стандартную фразу для завершения разговора с Ассистентом, см. раздел Выход из разговора .