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

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

Dialogflow를 사용하여 작업을 만드는 경우 처리는 Actions on Google 대화 웹훅 형식이 아닌 자체 표준 웹훅 형식을 통해 Dialogflow와 통신합니다. Dialogflow 웹훅 형식에는 대화 웹훅 형식의 모든 정보와 컨텍스트 및 매개변수에 대한 정보와 같은 추가 Dialogflow 관련 데이터가 포함됩니다.

Dialogflow 웹훅의 JSON 메시지의 예를 더 보려면 이 GitHub 프로젝트를 참조하세요.

요청 본문

Dialogflow의 요청 메시지에는 Dialogflow 웹훅 형식의 데이터가 포함됩니다. 이 객체에는 아래에 요약된 Actions on Google 관련 정보가 포함됩니다.

  • originalDetectIntentRequest.source 값은 'google'입니다.
  • originalDetectIntentRequest.version는 요청에 대한 Actions on Google 버전을 나타냅니다.
  • originalDetectIntentRequest.payload에는 어시스턴트의 대화 요청 JSON 등 주요 Actions on Google 관련 정보가 포함됩니다.
  • 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-Typeapplication/json여야 합니다.

Fulfillment에서 Dialogflow로 전송하는 응답 메시지는 Dialogflow 웹훅 형식이어야 합니다.

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

"google" 페이로드 객체의 주요 필드는 다음과 같습니다.

필드 설명
expectUserResponse 처리에 사용자 응답이 필요한지 여부를 나타냅니다. 대화를 계속하려면 값을 true로 설정하고 대화를 종료하려면 false로 설정합니다.
userStorage 특정 사용자와 연결된 영구 데이터를 저장합니다. 총 스토리지는 10,000바이트입니다.
richResponse 이 필드에는 어시스턴트가 렌더링할 오디오, 텍스트, 카드, 추천 또는 구조화된 데이터가 포함됩니다. Actions on Google에 리치 응답을 사용하는 방법에 관한 자세한 내용은 리치 응답을 참조하세요.
systemIntent 이 필드는 ExpectedInput.possibleIntents와 구조가 동일합니다. 처리에서 도우미 인텐트를 사용하는 경우 일반적으로 응답에 systemIntent가 포함됩니다. systemIntentpossibleIntents 필드는 ExpectedIntent 객체로 설정되어야 하며 inputValueData 필드 이름은 data로 변경되어야 합니다.

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

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

예를 들어 사용자의 권한을 요청하는 경우 intentactions.intent.PERMISSSION로, data를 값 사양으로 "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec"와 해당 유형의 필드와 함께 설정합니다.

다음 목록에는 Dialogflow 웹훅 응답의 systemIntent에서 설정할 수 있는 도우미의 값 사양 문자열이 요약되어 있습니다. 대화형 제어를 위한 Actions on Google 인텐트의 전체 목록은 인텐트 참조에서 확인하세요.

인텐트 이름 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 웹훅 요청으로 처리에 다시 전송합니다.

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

{
  "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 웹훅 형식으로 대화 세션을 종료하는 간단한 응답의 예를 보여줍니다. 응답 메시지에서 falseexpectUserResponse 값은 더 이상 사용자 입력이 예상되지 않으며 현재 대화를 종료해야 한다고 어시스턴트에 알립니다.

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

사용자가 어시스턴트와의 대화를 종료하기 위해 표준 문구를 호출할 때 기본 동작을 재정의하는 방법을 알아보려면 대화 종료 가이드를 참고하세요.