Kể từ ngày 13 tháng 6 năm 2023, Hành động trò chuyện không còn được dùng nữa. Để biết thêm thông tin, hãy xem phần Hành động trò chuyện ngừng hoạt động.
Các định dạng webhook của Actions on Google (Dialogflow)
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Tài liệu này mô tả định dạng webhook để giao tiếp giữa Actions on Google và dịch vụ thực hiện đơn hàng giúp xác định giao diện người dùng trò chuyện tuỳ chỉnh.
Bạn cần phải hiểu cách Actions on Google và phương thức thực hiện của bạn giao tiếp thông qua các định dạng webhook của Actions on Google:
Để tham gia vào các cuộc trò chuyện bằng Actions on Google, phương thức thực hiện của bạn sẽ triển khai một webhook có thể phản hồi các yêu cầu HTTP từ Actions on Google.
Khi người dùng gọi Hành động của bạn, phương thức thực hiện của bạn sẽ nhận được một HTTP POST có tải trọng JSON mô tả yêu cầu của người dùng.
Đổi lại, phương thức thực hiện của bạn chịu trách nhiệm đọc các tham số từ tải trọng yêu cầu, tạo phản hồi thích hợp ở định dạng JSON và gửi phản hồi này cho Trợ lý.
Loại yêu cầu
Bảng này tóm tắt các loại yêu cầu mà webhook của bạn có thể nhận được từ Trợ lý:
Loại
Nội dung mô tả
Ví dụ về JSON
Yêu cầu gọi
Câu nói của người dùng bắt đầu cuộc trò chuyện với phương thức thực hiện của bạn hoặc kích hoạt Hành động liên kết sâu (ví dụ: "Trò chuyện với Đầu bếp cá nhân để tìm công thức nấu bữa tối").
Nếu bạn sử dụng Dialogflow, các yêu cầu này tương ứng với ý định đã xác định trong mục Khám phá của chế độ cài đặt tích hợp Trợ lý Google.
Nếu bạn sử dụng SDK Hành động, các yêu cầu này tương ứng với các ý định đã xác định trong Gói hành động.
Các lệnh của người dùng trong cùng một phiên hoạt động sau khi cuộc trò chuyện với phương thức thực hiện của bạn bắt đầu. Ở định dạng webhook đối với cuộc trò chuyện, đây là các phản hồi dạng văn bản thô của người dùng tương ứng với ý định actions.intent.TEXT mà phương thức thực hiện của bạn đã yêu cầu ở lượt trước.
Các yêu cầu do Trợ lý gửi tới phương thức thực hiện của bạn khi webhook của bạn đã
yêu cầu một ý định trợ giúp
trong lượt trước đó của cuộc trò chuyện để xử lý các phần của
cuộc trò chuyện (ví dụ: actions.intent.OPTION và
actions.intent.PERMISSION).
Trong một tình huống tương tác thông thường trên Actions on Google, người dùng sẽ nói một cụm từ để gọi ra một Hành động. Để cung cấp phản hồi, Actions on Google sẽ tìm phương thức thực hiện khớp với Hành động do người dùng gọi và gửi yêu cầu tới đó.
Sau khi Actions on Google xác minh rằng phương thức thực hiện của bạn phù hợp với lệnh gọi của người dùng, hành động đó sẽ bắt đầu phiên trò chuyện bằng cách gửi một yêu cầu HTTP chứa trọng tải JSON chứa thông tin yêu cầu của người dùng đến điểm cuối của phương thức thực hiện. Phương thức thực hiện của bạn sẽ phân tích cú pháp yêu cầu và trả về một phản hồi chứa tải trọng JSON. Sau đó, Actions on Google sẽ chuyển đổi tải trọng thành giọng nói và đầu ra đa phương tiện được kết xuất cho người dùng.
Hình 1. Actions on Google gọi phương thức thực hiện của bạn thông qua SDK Actions.
Để tìm hiểu thêm về định dạng của tải trọng JSON khi Actions on Google gọi phương thức thực hiện của bạn thông qua SDK Actions, hãy xem phần Định dạng webhook trò chuyện.
Yêu cầu và phản hồi Dialogflow
Khi tạo Hành động, bạn có thể tuỳ ý sử dụng Dialogflow để đơn giản hoá nhiệm vụ tạo giao diện trò chuyện. Trong trường hợp này, Dialogflow hoạt động như một proxy giữa Actions on Google và phương thức thực hiện của bạn. Thay vì trực tiếp gửi yêu cầu HTTP/JSON đến điểm cuối của phương thức thực hiện, Actions on Google sẽ gửi yêu cầu đó đếnDialogflow.
Dialogflow gói tải trọng JSON có trong yêu cầu ban đầu thành định dạng webhookDialogflow và chuyển tiếp yêu cầu nhận được đến phương thức thực hiện Dialogflow của bạn.
Ngược lại, khi phương thức thực hiện của bạn gửi phản hồi cho Dialogflow, tải trọng JSON của phản hồi phải tuân thủ định dạng webhook của Dialogflow. Phương thức thực hiện của bạn sẽ phân tích cú pháp các tham số trong yêu cầu JSON cho Dialogflow và tạo một phản hồi ở định dạng webhook của Dialogflow. Sau đó, Dialogflow chuyển đổi phản hồi từ phương thức thực hiện của bạn thành tin nhắn phản hồi mà Trợ lý hiểu được.
Hình 2. Actions on Google gọi phương thức thực hiện của bạn thông qua
Dialogflow.
Để tìm hiểu thêm về định dạng của tải trọng JSON khi Actions on Google gọi phương thức thực hiện của bạn thông qua Dialogflow, hãy xem định dạng webhook củaDialogflow.
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 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)."]]
