Dialogflow 웹훅 형식{:#dialogflow-webhook-format} (Dialogflow)

이 섹션에서는 Actions on Google이 Dialogflow v2를 통해 처리를 호출할 때의 JSON 페이로드 형식을 설명합니다.

Dialogflow를 사용하여 작업을 만드는 경우 fulfillment가 Dialogflow에 전달하는 대신 자체 표준 웹훅 형식을 통해 Actions on Google 대화 웹훅 형식입니다. Dialogflow 웹훅 형식에는 모든 정보를 대화 웹훅 형식 Dialogflow 관련 추가 데이터(예: 매개변수를 제공합니다

Dialogflow 웹훅의 JSON 메시지 예시를 더 보려면 다음을 참조하세요. 이 GitHub 프로젝트에 추가합니다.

요청 본문

요청자의 request 메시지는 Dialogflow에는 Dialogflow 웹훅 형식의 데이터가 포함됩니다. 이 객체에는 Google 관련 작업 관련 정보(아래에 요약됨)

  • originalDetectIntentRequest.source 값은 'google'입니다.
  • originalDetectIntentRequest.version는 Actions on Google을 나타냅니다. 버전이 생성됩니다.
  • originalDetectIntentRequest.payload에는 Google 관련 주요 Actions on 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}"
}

응답 본문

처리 엔드포인트의 HTTP 게시물 헤더에 있는 Content-Type application/json여야 합니다.

처리에서 Dialogflow로 전송하는 응답 메시지는 Dialogflow 웹훅 형식을 참고하세요.

어시스턴트와 통신할 때 응답은 일반적으로 payload를 포함합니다. 'google'를 캡슐화하는 객체 객체를 지정합니다. ‘google’ 페이로드 객체에는 Actions on Google 관련 정보 최소한 expectUserResponse 필드 및 richResponse 또는 systemIntent 필드 중 하나를 선택합니다.

'google' 페이로드 객체의 주요 필드는 다음과 같이 요약됩니다.

필드 설명
expectUserResponse 처리에서 사용자 응답을 예상하는지를 나타냅니다. 값을 대화를 계속 이어갈 시간 true, 대화를 종료할 때 false 대화입니다.
userStorage 특정 사용자와 연결된 영구 데이터를 저장합니다. 총 스토리지 10,000바이트입니다
richResponse 이 필드에는 오디오, 텍스트, 카드, 추천 또는 구조화된 데이터가 포함됩니다. 해야 합니다. 리치 응답 사용에 대해 자세히 알아보려면 Actions on Google의 경우 리치 응답
systemIntent 이 필드의 구조는 다음과 같습니다. ExpectedInput.possibleIntents 일반적으로 응답에 포함된 systemIntent(처리에서 사용 중인 경우) 도우미 인텐트. 이 possibleIntents systemIntent의 필드는 <ph type="x-smartling-placeholder">ExpectedIntent</ph> 객체가 됩니다. inputValueData 필드 이름이 data로 변경되었습니다.

ExpectedIntent 내 객체에 다음 값을 지정합니다.

  • intent: 인텐트의 유형을 나타내는 도우미의 인텐트 이름입니다. 사용자가 제공하기를 원하는 정보
  • data: 어시스턴트가 도우미를 실행하는 데 필요한 데이터를 설명하는 문자열인 값 사양입니다.

예를 들어 사용자의 권한을 요청하는 경우 intent을 다음과 같이 설정합니다. actions.intent.PERMISSSIONdata"@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" 및 다음 있습니다.

다음 목록에는 Dialogflow 웹훅 응답의 systemIntent에 설정할 수 있는 도우미의 값 사양 문자열이 요약되어 있습니다. Actions on Google 인텐트의 전체 목록 보기 자세히 알아보려면 Intents 참조를 확인하세요.

인텐트 이름 Dialogflow 이벤트 이름 값 사양 설명
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" 목록 또는 캐러셀 UI에서 선택한 항목을 가져옵니다.
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 웹훅 요청의 fulfillment로 다시 보냅니다.

아래 스니펫은 사용자 선택이 포함된 도우미 결과의 예를 보여줍니다.

{
  "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}"
}

대화 종료 예시

아래 스니펫은 대화를 종료하는 간단한 응답의 예를 보여줍니다. 세션으로 구성됩니다. 이 expectUserResponse 드림 어시스턴트에 보내는 응답 메시지의 false 값 추가 사용자 입력이 예상되지 않으며 현재 진행 중인 있습니다.

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

사용자가 표준 구문으로 시작하는 경우 어시스턴트의 대화 종료 가이드를 참조하세요.