با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
این سند قالب webhook را برای برقراری ارتباط بین Actions on Google و یک سرویس تکمیلی که یک رابط کاربری مکالمه سفارشی را تعریف می‌کند، توصیف می‌کند.
درک نحوه ارتباط Actions on Google و اجرای شما از طریق قالب‌های Actions on Google webhook بسیار مهم است:
برای شرکت در مکالمات با Actions on Google، اجرای شما یک وبکهوک را پیاده‌سازی می‌کند که می‌تواند به درخواست‌های HTTP از Actions on Google پاسخ دهد.
وقتی کاربران Action شما را فراخوانی می‌کنند، انجام شما یک HTTP POST با بار JSON دریافت می‌کند که درخواست کاربر را توضیح می‌دهد.
به نوبه خود، انجام شما مسئول خواندن پارامترها از بار درخواست، ایجاد یک پاسخ با فرمت JSON مناسب و ارسال پاسخ به دستیار با این پاسخ است.
انواع درخواست
این جدول انواع درخواست هایی را که وب هوک شما ممکن است از دستیار دریافت کند، خلاصه می کند:
تایپ کنید
شرح
نمونه های JSON
درخواست های فراخوانی
اظهارات کاربر که مکالمه را با رضایت شما آغاز می کند یا اقدامات پیوند عمیق را آغاز می کند (به عنوان مثال، "برای یافتن دستور العمل های شام با سرآشپز شخصی صحبت کنید" ).
اگر از Dialogflow استفاده می کنید، این درخواست ها با اهداف تعریف شده در بخش Discovery تنظیمات یکپارچه سازی دستیار Google مطابقت دارد.
اگر از Actions SDK استفاده می کنید، این درخواست ها با اهداف تعریف شده در بسته Action شما مطابقت دارند.
اظهارات کاربران در همان جلسه پس از شروع گفتگو با شما. در قالب مکالمه webhook، اینها پاسخ‌های متن خام کاربر مربوط به مقاصد actions.intent.TEXT هستند که اجرای شما در نوبت قبلی درخواست کرده بود.
درخواست‌هایی که «دستیار» برای انجام شما ارسال می‌کند، زمانی که وب‌هوک شما در نوبت قبلی مکالمه یک هدف کمکی برای مدیریت بخش‌هایی از مکالمه درخواست کرده است (مثلا actions.intent.OPTION و actions.intent.PERMISSION ).
در یک سناریوی معمولی تعامل Actions on Google، کاربران عبارتی را برای فراخوانی یک Action بیان می‌کنند. برای ارائه پاسخ، Actions on Google انجام شده را پیدا می‌کند که با Action درخواست شده توسط کاربر مطابقت دارد و درخواست را به آنجا ارسال می‌کند.
هنگامی که Actions on Google مشخص کرد که انجام شما با فراخوانی کاربر مطابقت دارد، یک جلسه مکالمه را با ارسال یک درخواست HTTP که حاوی یک بار JSON با اطلاعات درخواست کاربر به نقطه پایانی شما است، شروع می‌کند. انجام شما درخواست را تجزیه می کند و پاسخی را برمی گرداند که حاوی بار JSON است. Actions on Google سپس بار را به گفتار رندر شده و خروجی چندرسانه ای برای کاربران تبدیل می کند.
شکل 1. اقداماتی که در Google انجام می شود از طریق Actions SDK فراخوانی می کند.
برای کسب اطلاعات بیشتر در مورد قالب بار JSON هنگامی که Actions on Google اجرای شما را از طریق Actions SDK فراخوانی می کند، به قالب گفتگوی وب هوک مراجعه کنید.
درخواست ها و پاسخ های جریان گفتگو
هنگامی که Actions را ایجاد می کنید، می توانید به صورت اختیاری از Dialogflow برای ساده سازی کار ساخت رابط های مکالمه استفاده کنید. در این سناریو، Dialogflow به عنوان یک پروکسی بین Actions on Google و انجام شما عمل می کند. به جای ارسال درخواست HTTP/JSON مستقیماً به نقطه پایانی شما، Actions on Google آن را به Dialogflow ارسال می‌کند.
Dialogflow محموله JSON موجود در درخواست اصلی را در قالب webhook Dialogflow قرار می دهد و درخواست حاصل را به انجام Dialogflow شما ارسال می کند.
برعکس، وقتی تکمیل شما پاسخی را به Dialogflow ارسال می‌کند، بار JSON پاسخ باید با قالب webhook Dialogflow مطابقت داشته باشد. تکمیل شما پارامترهای درخواست Dialogflow JSON را تجزیه می کند و پاسخی را در قالب webhook Dialogflow ایجاد می کند. سپس Dialogflow پاسخ از انجام شما را به پیام پاسخی تبدیل می کند که دستیار آن را درک می کند.
شکل 2. اقداماتی که در Google انجام می شود از طریق Dialogflow فراخوانی می کند.
برای کسب اطلاعات بیشتر در مورد فرمت بار JSON هنگامی که Actions on Google اجرای شما را از طریق Dialogflow فراخوانی می‌کند، به قالب webhook Dialogflow مراجعه کنید.
تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی."],[[["\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)."]]
