Formatos de webhook do Actions on Google (Dialogflow)

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.

Observação :se você tiver um servidor de back-end Node.js, recomendamos usar a biblioteca de cliente Node.js para Actions on Google para simplificar a criação do webhook. A biblioteca de cliente fornece um wrapper para o formato do webhook. Se você preferir implementar sua própria implementação de back-end sem usar a biblioteca de cliente, o back-end será responsável por consumir e processar as mensagens JSON enviadas pelo Actions on Google via HTTP POST.

É 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.

Termos-chave:

• Formato do webhook do Dialogflow:formato de payload JSON quando o Actions on Google invoca o fulfillment pelo Dialogflow.
• Formato do webhook da conversa:formato de payload JSON quando o Actions on Google invoca o fulfillment usando o SDK do Actions.

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.	Webhook do Dialogflow Webhook de conversa
Solicitações de conversa	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.	Webhook do Dialogflow Webhook de conversa
Resultados de ajuda	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).	Webhook do Dialogflow Webhook de conversa

Solicitações e respostas de conversa

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.