Formatos de webhook do Actions on Google (Dialogflow)
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Neste documento, descrevemos o formato do webhook para a comunicação entre o Actions on Google
e um serviço de fulfillment que define uma interface do usuário conversacional personalizada.
É importante entender como o Actions on Google e o fulfillment se comunicam
pelos formatos de webhook da Actions on Google:
Para participar de conversas com o Actions on Google, o fulfillment implementa
um webhook que pode responder a solicitações HTTP do Actions on Google.
Quando os usuários invocam sua ação, seu fulfillment recebe um
HTTP POST com um payload JSON que descreve a solicitação
do usuário.
O fulfillment, por sua vez, é responsável por ler os parâmetros do
payload da solicitação, gerar uma resposta JSON apropriada e
enviar uma resposta ao Google Assistente com essa resposta.
Tipos de solicitação
Esta tabela resume os tipos de solicitações que o webhook pode receber
do Assistente:
Tipo
Descrição
Exemplos de JSON
Solicitações de invocação
Enunciados do usuário que iniciam a conversa com o fulfillment ou
acionam ações de link direto (por exemplo, "Talk to Personal Chef to find
personal Chef to find
jantar receitas").
Se você estiver usando o Dialogflow, essas solicitações corresponderão às intents definidas na seção Descoberta das configurações de integração do Google Assistente.
Se você estiver usando o SDK do Actions, essas solicitações corresponderão às intents
definidas no seu pacote de ações.
Enunciados por usuários na mesma sessão assim que a conversa com o
fulfillment começou. No formato de webhook de conversa, essas são as
respostas de texto bruta do usuário correspondentes às intents actions.intent.TEXT
solicitadas pelo fulfillment na conversão anterior.
Solicitações enviadas pelo Assistente ao fulfillment quando o webhook solicita uma intent de auxiliar na conversão anterior para processar partes da conversa (por exemplo, actions.intent.OPTION e actions.intent.PERMISSION).
Em um cenário típico de interação no Actions on Google, os usuários enunciam uma frase para invocar uma
ação. Para fornecer uma resposta, o Actions on Google encontra o fulfillment que corresponde à
ação invocada pelo usuário, depois envia a solicitação para ele.
Depois que o Actions on Google estabelece que seu fulfillment é uma correspondência adequada para a
invocação do usuário, ele inicia uma sessão de conversa enviando uma solicitação HTTP
que contém um payload JSON com as informações da solicitação do usuário para o
endpoint de fulfillment. O fulfillment analisa a solicitação e retorna uma resposta
que contém um payload JSON. O Actions on Google converte o payload em voz
renderizada e saída multimídia para os usuários.
Figura 1. Actions on Google invocando o fulfillment usando o SDK do Actions.
Para saber mais sobre o formato do payload JSON quando o Actions on Google invocar o
fulfillment usando o SDK do Actions, consulte Formato do webhook da conversa.
Solicitações e respostas do Dialogflow
Ao criar ações, é possível usar o Dialogflow para simplificar a tarefa de criar interfaces de conversa. Nesse cenário, o Dialogflow atua como
um proxy entre o Actions on Google e o fulfillment. Em vez de enviar a solicitação HTTP/JSON diretamente para o endpoint de fulfillment, o Actions on Google a envia para o Dialogflow.
O Dialogflow encapsula o payload JSON da solicitação original no formato de webhook do Dialogflow e encaminha a solicitação resultante para o fulfillment do Dialogflow.
Por outro lado, quando o fulfillment envia uma resposta ao Dialogflow, o payload JSON da resposta precisa estar em conformidade com o formato do webhook do Dialogflow. O fulfillment analisa os parâmetros da solicitação JSON do Dialogflow e gera uma resposta no formato do webhook do Dialogflow. O Dialogflow converte a resposta do fulfillment em uma mensagem de resposta que o Google Assistente entende.
Figura 2. Actions on Google invocando o fulfillment com o
Dialogflow.
Para saber mais sobre o formato do payload JSON quando o Actions on Google invoca seu
fulfillment por meio do Dialogflow, consulte Formato do webhook do Dialogflow.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Não contém as informações de que eu preciso","missingTheInformationINeed","thumb-down"],["Muito complicado / etapas demais","tooComplicatedTooManySteps","thumb-down"],["Desatualizado","outOfDate","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Problema com as amostras / o código","samplesCodeIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 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)."]]
