Formatos de webhook de Actions on Google (Dialogflow)
Organiza tus páginas con colecciones
Guarda y categoriza el contenido según tus preferencias.
En este documento, se describe el formato de webhook para la comunicación entre Actions on Google y un servicio de entrega que define una interfaz de usuario conversacional personalizada.
Es importante comprender cómo Actions on Google y tu entrega se comunican a través de los formatos de webhook de Actions on Google:
Para participar en conversaciones con Actions on Google, tu entrega implementa un webhook que puede responder a solicitudes HTTP de Actions on Google.
Cuando los usuarios invocan tu acción, la entrega recibe una HTTP POST con una carga útil de JSON que describe la solicitud del usuario.
A su vez, tu entrega es responsable de leer los parámetros de la carga útil de la solicitud, generar una respuesta adecuada con formato JSON y enviar una respuesta al Asistente con esta respuesta.
Tipos de solicitud
En esta tabla, se resumen los tipos de solicitudes que tu webhook puede recibir del Asistente:
Tipo
Descripción
Ejemplos de JSON
Solicitudes de invocación
Declaraciones de usuario que inician la conversación con tu entrega o activan acciones de vínculos directos (por ejemplo, "Hablar con Personal Chef para buscar recetas para la cena").
Si usas Dialogflow, estas solicitudes corresponden a los intents definidos en la sección Descubrimiento en la configuración de integración del Asistente de Google.
Si usas el SDK de Actions, estas solicitudes corresponden a los intents definidos en el paquete de acción.
Declaraciones de usuarios en la misma sesión una vez que haya comenzado la conversación con tu entrega. En el formato de webhook de conversación, estas son las respuestas de texto sin procesar del usuario que corresponden a los intents actions.intent.TEXT que tu entrega solicitó en el turno anterior.
Solicitudes enviadas por Asistente a tu entrega cuando el webhook solicitó un intent auxiliar en el turno anterior de la conversación para controlar partes de ella (por ejemplo, actions.intent.OPTION y actions.intent.PERMISSION).
En una situación típica de interacción de Actions on Google, los usuarios pronuncian una frase para invocar una acción. Para proporcionar una respuesta, Actions on Google encuentra la entrega que coincide con la acción que invocó el usuario y envía la solicitud allí.
Una vez que Actions on Google establece que tu entrega es una coincidencia adecuada para la invocación del usuario, inicia una sesión de conversación con el envío de una solicitud HTTP que contiene una carga útil de JSON con la información de la solicitud del usuario a tu extremo de entrega. Tu entrega analiza la solicitud y muestra una respuesta que contiene una carga útil de JSON. Luego, Actions on Google convierte la carga útil en salidas multimedia y de voz renderizadas para los usuarios.
Figura 1. Actions on Google invocan tu entrega a través del SDK de Actions.
Para obtener más información sobre el formato de la carga útil de JSON cuando Actions on Google invoca tu entrega a través del SDK de Actions, consulta Formato de webhook de conversación.
Solicitudes y respuestas de Dialogflow
Cuando creas acciones, tienes la opción de usar Dialogflow para simplificar la tarea de compilar interfaces conversacionales. En esta situación, Dialogflow actúa como un proxy entre Actions on Google y tu entrega. En lugar de enviar la solicitud HTTP/JSON directamente a tu extremo de entrega, Actions on Google la envía a Dialogflow.
Dialogflow une la carga útil JSON contenida en la solicitud original al formato de webhook de Dialogflow y reenvía la solicitud resultante a tu entrega de Dialogflow.
Por el contrario, cuando tu entrega envía una respuesta a Dialogflow, la carga útil JSON de la respuesta debe cumplir con el formato del webhook de Dialogflow. Tu entrega analiza los parámetros de la solicitud JSON de Dialogflow y genera una respuesta en el formato de webhook de Dialogflow. Luego, Dialogflow convierte la respuesta de tu entrega en un mensaje de respuesta que el Asistente comprende.
Figura 2: Actions on Google invocando tu entrega a través de Dialogflow.
Para obtener más información sobre el formato de la carga útil de JSON cuando Actions on Google invoca tu entrega a través de Dialogflow, consulta Formato de webhook de Dialogflow.
[[["Fácil de comprender","easyToUnderstand","thumb-up"],["Resolvió mi problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Falta la información que necesito","missingTheInformationINeed","thumb-down"],["Muy complicado o demasiados pasos","tooComplicatedTooManySteps","thumb-down"],["Desactualizado","outOfDate","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Problema con las muestras o los códigos","samplesCodeIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 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)."]]
