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

В этом разделе описывается формат полезных данных JSON, когда Actions on Google вызывает ваше выполнение через Dialogflow v2.

Если вы используете Dialogflow для создания действий, ваше выполнение связывается с Dialogflow через собственный стандартный формат веб-перехватчика вместо формата веб-перехватчика для диалога Actions on Google. Формат веб-перехватчика Dialogflow содержит всю информацию о формате веб-перехватчика диалога , а также дополнительные данные, специфичные для Dialogflow, такие как информация о контекстах и ​​параметрах.

Чтобы увидеть больше примеров сообщений JSON для веб-хуков Dialogflow, вы можете обратиться к этому проекту GitHub .

Примечание. Для агентов Dialogflow, использующих API версии 2 с включенными бета-функциями , значения атрибутов session и outputContexts.name будут начинаться с projects/${PROJECTID}/agent/environments/${ENVID}/users/${USERID}/sessions/${SESSIONID} . (В Dialogflow V2 без включенной бета-функции это начинается с projects/${PROJECTID}/agent/sessions/${SESSIONID} .)

Тело запроса

Сообщение запроса от Dialogflow содержит данные в формате веб-перехватчика Dialogflow. Этот объект включает в себя действия над информацией, относящейся к Google, как описано ниже:

• Значение originalDetectIntentRequest.source — «google».
• originalDetectIntentRequest.version указывает версию Actions on Google для запроса.
• Файл originalDetectIntentRequest.payload содержит ключевые действия с информацией, специфичной для Google, включая JSON -запрос разговора от Ассистента.
• Поле Conversation.conversationToken не поддерживается запросами веб-перехватчика Dialogflow. Вместо этого ваше выполнение может использовать контекст Dialogflow для сохранения данных на протяжении всего разговора.

Простой пример запроса на вызов

Во фрагменте ниже показан пример запроса на вызов в формате веб-перехватчика Dialogflow.

{
  "responseId": "c4b863dd-aafe-41ad-a115-91736b665cb9",
  "queryResult": {
    "queryText": "GOOGLE_ASSISTANT_WELCOME",
    "action": "input.welcome",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "",
    "fulfillmentMessages": [],
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_welcome"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_voice"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/8b006880-0af7-4ec9-a4c3-1cc503ea8260",
      "displayName": "Default Welcome Intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": [
          {
            "name": "actions.capability.SCREEN_OUTPUT"
          },
          {
            "name": "actions.capability.AUDIO_OUTPUT"
          },
          {
            "name": "actions.capability.WEB_BROWSER"
          },
          {
            "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
          }
        ]
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "Talk to my test app",
              "inputType": "VOICE"
            }
          ],
          "intent": "actions.intent.MAIN"
        }
      ],
      "user": {
        "lastSeen": "2018-03-16T22:08:48Z",
        "permissions": [
          "UPDATE"
        ],
        "locale": "en-US",
        "userId": "ABwppHEvwoXs18xBNzumk18p5h02bhRDp_riW0kTZKYdxB6-LfP3BJRjgPjHf1xqy1lxqS2uL8Z36gT6JLXSrSCZ"
      },
      "conversation": {
        "conversationId": "${SESSIONID}",
        "type": "NEW"
      },
      "availableSurfaces": [
        {
          "capabilities": [
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            },
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            }
          ]
        }
      ]
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Пример простого запроса на разговор

В приведенном ниже фрагменте показан пример диалогового запроса в формате веб-перехватчика Dialogflow, где пользовательский ввод представляет собой текстовую строку.

{
  "responseId": "68efa569-4ba1-4b7f-9b1b-ac2865deb539",
  "queryResult": {
    "queryText": "query from the user",
    "action": "action.name.of.matched.dialogflow.intent",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_keyboard"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1f4e5bd9-a670-4161-a22e-2c97b077f29f",
      "displayName": "Name of Dialogflow Intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": [
          {
            "name": "actions.capability.SCREEN_OUTPUT"
          },
          {
            "name": "actions.capability.AUDIO_OUTPUT"
          },
          {
            "name": "actions.capability.WEB_BROWSER"
          },
          {
            "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
          }
        ]
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "query from the user",
              "inputType": "KEYBOARD"
            }
          ],
          "arguments": [
            {
              "rawText": "query from the user",
              "textValue": "query from the user",
              "name": "text"
            }
          ],
          "intent": "actions.intent.TEXT"
        }
      ],
      "user": {
        "lastSeen": "2017-10-06T01:06:56Z",
        "locale": "en-US",
        "userId": "AI_yXq-AtrRh3mJX5D-G0MsVhqun"
      },
      "conversation": {
        "conversationId": "1522951193000",
        "type": "ACTIVE",
        "conversationToken": "[]"
      },
      "availableSurfaces": [
        {
          "capabilities": [
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            },
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            }
          ]
        }
      ]
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Пример результата помощника

Во фрагменте ниже показан пример вспомогательного результата в формате веб-перехватчика Dialogflow. В этом примере показан ответ пользователя после того, как веб-перехватчик указывает Помощнику, что ему необходимо получить подтверждение пользователя.

{
  "responseId": "cb6f5ec2-c26e-4349-b561-a9ddd6a0e495",
  "queryResult": {
    "queryText": "actions_intent_CONFIRMATION",
    "action": "Dialogflow action name of matched intent",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_confirmation",
        "parameters": {
          "CONFIRMATION": true
        }
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
      "displayName": "Dialogflow action name of matched intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {},
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "yes",
              "inputType": "VOICE"
            }
          ],
          "arguments": [
            {
              "name": "CONFIRMATION",
              "boolValue": true
            }
          ],
          "intent": "actions.intent.CONFIRMATION"
        }
      ],
      "user": {},
      "conversation": {},
      "availableSurfaces": []
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Тело ответа

Content-Type сообщений от вашей конечной точки выполнения до Ассистента должен быть application/json .

Ответное сообщение, которое ваше выполнение отправляет в Dialogflow, должно быть в формате веб-перехватчика Dialogflow .

При общении с Ассистентом ваш ответ обычно содержит объект payload , инкапсулирующий объект « google ». Объект полезных данных " google " включает в себя действия над информацией, специфичной для Google. Он должен содержать как минимум поле expectUserResponse и поле richResponse или systemIntent .

Ключевые поля объекта полезных данных " google " приведены ниже:

Поле	Описание
expectUserResponse	Указывает, ожидает ли ваше выполнение ответа пользователя. Установите значение true , чтобы продолжить разговор, и false , чтобы завершить разговор.
userStorage	Хранит постоянные данные, привязанные к конкретному пользователю. Общий объем хранилища составляет 10 000 байт.
richResponse	Это поле содержит аудио, текст, карточки, предложения или структурированные данные для обработки Помощником. Дополнительную информацию об использовании расширенных ответов для Actions on Google см. в разделе Расширенные ответы.
systemIntent	Это поле имеет ту же структуру, что и ExpectedInput.possibleIntents . Ваш ответ обычно содержит systemIntent , если при выполнении используется вспомогательное намерение . Поле possibleIntents в systemIntent должно быть установлено в объект ExpectedIntent , а имя поля inputValueData должно быть изменено на data .

Внутри объекта ExpectedIntent вы указываете следующие значения:

• намерение : имя намерения для помощника, которое указывает тип информации, которую вы хотите предоставить пользователю, и
• data : спецификация значения, представляющая собой строку, описывающую данные, необходимые помощнику для выполнения помощника.

Например, если вы запрашиваете разрешение пользователя, установите intent actions.intent.PERMISSSION , а data для спецификации значения — "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" , вместе с полями для этого типа.

В следующем списке приведены строки спецификации значений для вспомогательных функций, которые можно установить в systemIntent для ответа веб-перехватчика Dialogflow. Полный список намерений Actions on Google для диалогового управления см. в справочнике по намерениям .

Имя намерения	Имя события диалогового потока	Спецификация значения	Описание
actions.intent.CONFIRMATION	actions_intent_CONFIRMATION	"@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec"	Получает подтверждение от пользователя (например, ответ на вопрос «да» или «нет»).
actions.intent.DATETIME	actions_intent_DATETIME	"@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec"	Получает введенные пользователем дату и время.
actions.intent.DELIVERY_ADDRESS	actions_intent_DELIVERY_ADDRESS	"@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec"	Получает ввод адреса доставки от пользователя.
actions.intent.LINK	actions_intent_LINK	"@type": "type.googleapis.com/google.actions.v2.LinkValueSpec"	Запрашивает поток глубоких ссылок в приложение Android.
actions.intent.OPTION	actions_intent_OPTION	"@type": "type.googleapis.com/google.actions.v2.OptionValueSpec"	Получает выбранный элемент из списка или пользовательского интерфейса карусели.
actions.intent.PERMISSION	actions_intent_PERMISSION	"@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec"	Получает информацию о пользователе, включая полное имя, приблизительное или точное местоположение.
actions.intent.SIGN_IN	actions_intent_SIGN_IN	"@type": "type.googleapis.com/google.actions.v2.SignInValueSpec"	Запрашивает поток привязки учетной записи для привязки учетной записи пользователя.

Простой пример ответа

В приведенном ниже фрагменте показан пример простого ответа в формате веб-перехватчика Dialogflow.

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "this is a simple response"
            }
          }
        ]
      }
    }
  }
}

Вспомогательный пример

Во фрагменте ниже показан пример использования вспомогательного намерения в формате веб-перехватчика Dialogflow. В этом примере ваш вебхук использует вспомогательное намерение actions.intent.OPTIONS , чтобы дать помощнику указание получить выбор пользователя между двумя вариантами.

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Choose a item"
            }
          }
        ]
      },
      "systemIntent": {
        "intent": "actions.intent.OPTION",
        "data": {
          "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
          "listSelect": {
            "title": "Hello",
            "items": [
              {
                "optionInfo": {
                  "key": "first title key"
                },
                "description": "first description",
                "image": {
                  "url": "/assistant/images/badges/XPM_BADGING_GoogleAssistant_VER.png",
                  "accessibilityText": "first alt"
                },
                "title": "first title"
              },
              {
                "optionInfo": {
                  "key": "second"
                },
                "description": "second description",
                "image": {
                  "url": "https://lh3.googleusercontent.com/Nu3a6F80WfixUqf_ec_vgXy_c0-0r4VLJRXjVFF_X_CIilEu8B9fT35qyTEj_PEsKw",
                  "accessibilityText": "second alt"
                },
                "title": "second title"
              }
            ]
          }
        }
      }
    }
  }
}

При получении сообщения из предыдущего примера Ассистент временно берет на себя разговор и предлагает пользователю сделать выбор на основе заданных параметров. Собрав все необходимые пользовательские данные, Ассистент отправляет этот вспомогательный результат обратно к вам в запросе веб-перехватчика Dialogflow.

Во фрагменте ниже показан пример вспомогательного результата с выбором пользователя.

{
  "responseId": "ea166558-615a-48f3-ae5b-7f55d895784b",
  "queryResult": {
    "queryText": "actions_intent_OPTION",
    "action": "",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "",
    "fulfillmentMessages": [],
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_option",
        "parameters": {
          "OPTION": "key of selected item"
        }
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
      "displayName": "Dialogflow intent name of matched intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": []
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "Title of selected item",
              "inputType": "TOUCH"
            }
          ],
          "arguments": [
            {
              "textValue": "Key of selected item",
              "name": "OPTION"
            }
          ],
          "intent": "actions.intent.OPTION"
        }
      ],
      "user": {},
      "conversation": {},
      "availableSurfaces": []
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Пример завершения разговора

В приведенном ниже фрагменте показан пример простого ответа на завершение сеанса беседы в формате веб-перехватчика Dialogflow. Значение false expectUserResponse в ответном сообщении сигнализирует помощнику о том, что дальнейших действий пользователя не ожидается и что текущий разговор следует завершить.

{
  "payload": {
    "google": {
      "expectUserResponse": false,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Goodbye!"
            }
          }
        ]
      }
    }
  }
}

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