Формат веб-перехватчика беседы {:#conversation-webhook-format} (Dialogflow)

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

Чтобы узнать, как переопределить поведение по умолчанию, когда пользователи вызывают стандартную фразу для завершения разговора с Ассистентом, см. раздел Выход из разговора .