Formats de webhooks Actions on Google (Dialogflow)
Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
Ce document décrit le format du webhook pour la communication entre Actions on Google et un service de fulfillment qui définit une interface utilisateur conversationnelle personnalisée.
Il est important de comprendre comment Actions on Google et votre traitement communiquent via les formats de webhooks Actions on Google:
Pour participer à des conversations avec Actions on Google, votre traitement implémente un webhook qui peut répondre aux requêtes HTTP d'Actions on Google.
Lorsque des utilisateurs appellent votre action, votre traitement reçoit un objet HTTP POST avec une charge utile JSON décrivant la requête de l'utilisateur.
À son tour, votre traitement est chargé de lire les paramètres de la charge utile de la requête, de générer une réponse au format JSON appropriée et d'envoyer une réponse à l'Assistant avec cette réponse.
Types de requêtes
Ce tableau récapitule les types de requêtes que votre webhook peut recevoir de l'Assistant:
Type
Description
Exemples JSON
Requêtes d'appel
Les énoncés de l'utilisateur qui lancent la conversation avec votre traitement ou déclenchent des actions de lien profond (par exemple, Parler à Personal Chef pour trouver des recettes pour le dîner).
Si vous utilisez Dialogflow, ces requêtes correspondent aux intents définis dans la section Discovery des paramètres d'intégration de l'Assistant Google.
Si vous utilisez le SDK Actions, ces requêtes correspondent aux intents définis dans votre package d'actions.
Énoncés par les utilisateurs dans la même session une fois que la conversation avec votre traitement a commencé. Au format webhook de conversation, il s'agit des réponses en texte brut de l'utilisateur correspondant aux intents actions.intent.TEXT demandés par votre traitement au tour précédent.
Requêtes envoyées par l'Assistant à votre traitement lorsque le webhook a demandé un intent d'aide au tour précédent de la conversation pour gérer des parties de la conversation (par exemple, actions.intent.OPTION et actions.intent.PERMISSION).
Dans un scénario d'interaction Actions on Google classique, les utilisateurs énoncent une expression pour appeler une action. Pour fournir une réponse, Actions on Google recherche le traitement correspondant à l'action appelée par l'utilisateur, puis y envoie la requête.
Une fois qu'Actions on Google établit que votre traitement correspond à l'appel de l'utilisateur, elle démarre une session de conversation en envoyant une requête HTTP contenant une charge utile JSON avec les informations de requête de l'utilisateur à votre point de terminaison de traitement. Le traitement analyse la requête et renvoie une réponse contenant une charge utile JSON. Actions on Google convertit ensuite la charge utile en contenu vocal et en sortie multimédia pour les utilisateurs.
Figure 1 : Actions on Google qui appelle votre traitement via le SDK Actions
Pour en savoir plus sur le format de la charge utile JSON lorsqu'Actions on Google appelle votre traitement via le SDK Actions, consultez Format du webhook de conversation.
Requêtes et réponses Dialogflow
Lorsque vous créez des actions, vous pouvez éventuellement utiliser Dialogflow pour simplifier la création d'interfaces de conversation. Dans ce scénario, Dialogflow sert de proxy entre Actions on Google et votre traitement. Au lieu d'envoyer la requête HTTP/JSON directement à votre point de terminaison de fulfillment, Actions on Google l'envoie à Dialogflow.
Dialogflow encapsule la charge utile JSON contenue dans la requête d'origine au format de webhook Dialogflow et transfère la requête obtenue à votre traitement Dialogflow.
À l'inverse, lorsque le fulfillment envoie une réponse à Dialogflow, la charge utile JSON de la réponse doit être conforme au format du webhook Dialogflow. Le traitement analyse les paramètres de la requête JSON Dialogflow et génère une réponse au format webhook Dialogflow. Dialogflow convertit ensuite la réponse de votre traitement en un message de réponse compris par l'Assistant.
Figure 2. Actions on Google qui appelle votre traitement via Dialogflow
Pour en savoir plus sur le format de la charge utile JSON lorsque Actions on Google appelle votre traitement via Dialogflow, consultez Format du webhook Dialogflow.
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/07/28 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Il n'y a pas l'information dont j'ai besoin","missingTheInformationINeed","thumb-down"],["Trop compliqué/Trop d'étapes","tooComplicatedTooManySteps","thumb-down"],["Obsolète","outOfDate","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Mauvais exemple/Erreur de code","samplesCodeIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 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)."]]
