В этом разделе описывается формат полезных данных 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"
}
}
]
}
}
}
Чтобы узнать, как переопределить поведение по умолчанию, когда пользователи вызывают стандартную фразу для завершения разговора с Ассистентом, см. раздел Выход из разговора .