대화 웹훅 형식{:#conversation-webhook-format} (Dialogflow)

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

대화가 시작되면 고유한 conversationId로 식별됩니다. 어시스턴트에 대한 이후의 각 사용자 쿼리마다 처리는 웹훅이 처리하고 응답해야 하는 인텐트를 수신합니다. 이 conversationId는 대화가 끝날 때까지 모든 요청 및 응답 쌍에서 유지됩니다.

요청 본문

사용자가 초기 쿼리를 하거나 후속 입력을 제공하면 어시스턴트가 처리에 요청을 전송합니다. 어시스턴트의 대화 웹훅 요청에는 트리거된 인텐트, 사용자 입력의 원시 텍스트, 사용자 기기의 노출 영역 기능과 같은 데이터가 포함됩니다.

대화 웹훅 형식의 요청의 주요 필드는 다음과 같습니다.

필드 설명
isInSandbox 이 불리언 변수는 웹훅이 샌드박스 모드에서 이 요청을 처리해야 하는지 여부를 나타내는 트랜잭션 기능에 주로 사용됩니다. 샌드박스 모드에서는 웹훅이 사용자의 구매주문서를 청구하거나 처리해서는 안 됩니다. 기본적으로 'true'로 설정되어 있습니다.
surface 사용자가 상호작용하는 어시스턴트 노출 영역 및 기능에 관한 정보입니다.
Inputs 호출 요청에 관한 정보입니다. 트리거하는 호출의 경우 여기에는 작업에 매핑되는 인텐트가 포함됩니다. 대화의 후속 요청에서 이 객체에는 처리에 의해 지정된 예상 입력에 해당하는 인수도 포함될 수 있습니다.
User 요청을 시작한 사용자에 대한 정보입니다. 이 정보에는 사용자가 부여한 권한과 사용자의 언어가 포함됩니다.
Conversation 대화 ID, 유형(예: 이 요청이 새 대화를 시작하는지 여부), 대화 수명 동안 영구 데이터를 저장하는 대화 토큰 등 대화 컨텍스트에 대한 정보입니다.
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"
        }
      ]
    }
  ]
}

간단한 대화 요청 예

아래 스니펫은 대화 웹훅 형식의 대화 요청의 예를 보여주며, 여기서 사용자 입력이 텍스트 문자열 (예: "My Lucy number is 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"
        }
      ]
    }
  ]
}

응답 본문

처리 엔드포인트에서 어시스턴트로 보내는 HTTP 게시물 헤더의 Content-Typeapplication/json여야 합니다.

대화 웹훅 형식의 응답에는 사용자에게 표시하는 실제 UI (오디오 및 시각적 구성요소 포함)와 후속 요청에서 트리거할 수 있는 인텐트 (예상된 인텐트라고 함)와 같은 데이터가 포함됩니다. 예상 인텐트는 Intents 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"
            }
          ]
        }
      }
    }
  ]
}

대화 종료 예시

아래 스니펫은 대화 웹훅 응답 형식으로 대화 세션을 종료하는 간단한 응답의 예를 보여줍니다.

응답 메시지의 falseexpectedUserResponse 값은 더 이상 사용자 입력이 예상되지 않으며 현재 대화를 종료해야 한다고 어시스턴트에 알립니다. finalResponse 값은 대화가 끝나기 전에 어시스턴트가 사용자에게 표시하거나 출력해야 하는 내용을 나타냅니다.

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "simpleResponse": {
            "textToSpeech": "Good bye"
          }
        }
      ]
    }
  }
}

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