일반적인 Actions on Google 상호작용 시나리오에서 사용자는 작업을 호출하는 문구를 말합니다. 응답을 제공하기 위해 Actions on Google은 사용자가 호출한 작업과 일치하는 처리를 찾아 요청을 전송합니다.
Actions on Google은 처리가 사용자의 호출에 적합하다고 판단하면 사용자의 요청 정보와 함께 JSON 페이로드가 포함된 HTTP 요청을 처리 엔드포인트로 전송하여 대화 세션을 시작합니다. 처리는 요청을 파싱하고 JSON 페이로드가 포함된 응답을 반환합니다. 그러면 Actions on Google이 사용자를 위해 페이로드를 렌더링된 음성 및 멀티미디어 출력으로 변환합니다.
그림 1. Actions SDK를 통해 처리를 호출하는 Actions on Google
Actions on Google에서 Actions SDK를 통해 처리를 호출할 때 JSON 페이로드 형식에 대한 자세한 내용은 대화 웹훅 형식을 참조하세요.
Dialogflow 요청 및 응답
작업을 만들 때 선택적으로 Dialogflow를 사용하여 대화 인터페이스 빌드 작업을 간소화할 수 있습니다. 이 시나리오에서 Dialogflow는 Actions on Google과 처리 간의 프록시 역할을 합니다. Actions on Google은 HTTP/JSON 요청을 처리 엔드포인트로 직접 전송하는 대신 Dialogflow로 전송합니다.
Dialogflow는 원래 요청에 포함된 JSON 페이로드를 Dialogflow 웹훅 형식으로 래핑하고 결과 요청을 Dialogflow 처리로 전달합니다.
반대로, fulfillment가 Dialogflow에 응답을 전송할 때 응답의 JSON 페이로드는 Dialogflow 웹훅 형식을 준수해야 합니다. 처리는 Dialogflow JSON 요청에서 매개변수를 파싱하고 Dialogflow 웹훅 형식으로 응답을 생성합니다. 그러면 Dialogflow는 처리의 응답을 어시스턴트가 이해할 수 있는 응답 메시지로 변환합니다.
그림 2. Dialogflow를 통해 처리를 호출하는 Actions on Google
Actions on Google에서 Dialogflow를 통해 처리를 호출할 때 JSON 페이로드 형식에 대한 자세한 내용은 Dialogflow 웹훅 형식을 참조하세요.
[null,null,["최종 업데이트: 2025-07-28(UTC)"],[[["\u003cp\u003eActions on Google communicates with your fulfillment service through webhooks, sending JSON payloads that describe user requests.\u003c/p\u003e\n"],["\u003cp\u003eYour fulfillment service needs to process these requests, generate appropriate JSON responses, and send them back to the Assistant.\u003c/p\u003e\n"],["\u003cp\u003eThere are two main webhook formats: Dialogflow webhook format and Conversation webhook format, depending on whether you use Dialogflow or Actions SDK.\u003c/p\u003e\n"],["\u003cp\u003eWebhooks can handle different request types like invocation requests, conversation requests, and helper results, each with specific JSON structures.\u003c/p\u003e\n"],["\u003cp\u003eDialogflow can act as a proxy between Actions on Google and your fulfillment, handling the communication and format conversions.\u003c/p\u003e\n"]]],["Actions on Google uses webhooks to communicate with fulfillment services, sending HTTP POST requests with JSON payloads. Fulfillment services must parse these requests and respond with appropriately formatted JSON. There are two main webhook formats: Dialogflow and Conversation, corresponding to whether Dialogflow acts as a proxy. Webhook requests can be invocations, conversation turns, or helper results. The fulfillment reads parameters from the request payload and sends a reply back to the Assistant.\n"],null,["# Actions on Google webhook formats (Dialogflow)\n\nThis document describes the webhook format for communicating between Actions on Google\nand a fulfillment service that defines a custom [conversational user interface](/assistant/df-asdk/design).\n| **Note:** If you have a Node.js backend server, we strongly encourage you to use the [Actions on Google Node.js client library](/assistant/df-asdk/reference/nodejsv2/overview) to simplify creating your webhook. The client library provides a wrapper for the webhook format. If you prefer to roll your own backend implementation without using the client library, your backend is responsible for consuming and processing the JSON messages sent by Actions on Google via HTTP POST.\n\nIt's important to understand how Actions on Google and your fulfillment communicate\nthrough the Actions on Google webhook formats:\n\n- To participate in conversations with Actions on Google, your fulfillment implements a [webhook](https://en.wikipedia.org/wiki/Webhook) that can respond to HTTP requests from Actions on Google.\n- When users invoke your Action, your fulfillment receives an [`HTTP POST`](https://en.wikipedia.org/wiki/POST_(HTTP)) with a JSON payload that describes the user's request.\n- In turn, your fulfillment is responsible for reading the parameters from the request payload, generating an appropriate JSON formatted response, and sending a reply to the Assistant with this response.\n\n| **Key Terms:**\n|\n| - **Dialogflow webhook format:** JSON payload format when Actions on Google invokes your fulfillment through [Dialogflow](//dialogflow.com/).\n| - **Conversation webhook format:** JSON payload format when Actions on Google invokes your fulfillment through the [Actions SDK](/assistant/df-asdk/actions-sdk).\n\nRequest types\n-------------\n\nThis table summarizes the types of requests that your webhook might receive\nfrom the Assistant:\n\n| Type | Description | JSON Examples |\n|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Invocation requests | User utterances that initiate the conversation with your fulfillment or trigger deep-link Actions (for example, *\"Talk to Personal Chef to find dinner recipes\"* ). - If using Dialogflow, these requests correspond to the intents defined in the **Discovery** section of the **Google Assistant** integration settings. - If using the Actions SDK, these requests correspond to the intents defined in your [Action package](/assistant/df-asdk/reference/action-package/rest/Shared.Types/ActionPackage). | - [Dialogflow webhook](/assistant/df-asdk/reference/dialogflow-webhook-json#simple-invocation-request-example-df) - [Conversation webhook](/assistant/df-asdk/reference/conversation-webhook-json#simple-invocation-request-example-conv) |\n| Conversation requests | Utterances by users in the same session once the conversation with your fulfillment has started. In the conversation webhook format, these are the raw text responses from the user corresponding to `actions.intent.TEXT` intents that your fulfillment requested in the previous turn. | - [Dialogflow webhook](/assistant/df-asdk/reference/dialogflow-webhook-json#simple-conversation-request-example-df) - [Conversation webhook](/assistant/df-asdk/reference/conversation-webhook-json#simple-conversation-request-example-conv) |\n| Helper results | Requests sent by the Assistant to your fulfillment when your webhook has requested a [helper intent](/assistant/df-asdk/helpers) in the previous turn of the conversation to handle parts of the conversation (for example, `actions.intent.OPTION` and `actions.intent.PERMISSION`). | - [Dialogflow webhook](/assistant/df-asdk/reference/dialogflow-webhook-json#helper-result-example-df) - [Conversation webhook](/assistant/df-asdk/reference/conversation-webhook-json#helper-example-conv) |\n\nConversation requests and responses\n-----------------------------------\n\nIn a typical Actions on Google interaction scenario, users utter a phrase to invoke an\nAction. To provide a response, Actions on Google finds the fulfillment that matches the\nAction invoked by the user and sends the request there.\n\nOnce Actions on Google establishes that your fulfillment is a suitable match for the\nuser's invocation, it starts a conversation session by sending an HTTP request\nthat contains a JSON payload with the user's request information to your\nfulfillment endpoint. Your fulfillment parses the request and returns a response\nthat contains a JSON payload. Actions on Google then converts the payload into rendered\nspeech and multimedia output for users.\n**Figure 1.** Actions on Google invoking your fulfillment through the Actions SDK.\n\nTo learn more about the format of the JSON payload when Actions on Google invokes your\nfulfillment through the Actions SDK, see [Conversation webhook format](/assistant/df-asdk/reference/conversation-webhook-json).\n\nDialogflow requests and responses\n---------------------------------\n\nWhen you create Actions, you can optionally use Dialogflow to simplify the\ntask of building conversational interfaces. In this scenario, Dialogflow acts as\na proxy between Actions on Google and your fulfillment. Instead of sending the HTTP/JSON\nrequest directly to your fulfillment endpoint, Actions on Google sends it to\nDialogflow.\n\nDialogflow wraps the JSON payload contained in the original request into the\nDialogflow webhook format, and forwards the resulting request to your Dialogflow\nfulfillment.\n\nConversely, when your fulfillment sends a response to Dialogflow, the JSON\npayload of the response must comply with the Dialogflow webhook format. Your\nfulfillment parses the parameters from the Dialogflow JSON request, and\ngenerates a response in the Dialogflow webhook format. Dialogflow then converts\nthe response from your fulfillment into a response message that the Assistant\nunderstands.\n**Figure 2.** Actions on Google invoking your fulfillment through Dialogflow.\n\nTo learn more about the format of the JSON payload when Actions on Google invokes your\nfulfillment through Dialogflow, see [Dialogflow webhook format](/assistant/df-asdk/reference/dialogflow-webhook-json)."]]
