Nesta seção, descrevemos o formato do payload JSON quando o Actions on Google invoca seu fulfillment usando o SDK do Actions.
Quando uma conversa é iniciada, ela é identificada por um conversationId
exclusivo. Para cada consulta de usuário
posterior ao Google Assistente, o fulfillment recebe uma intent que
o webhook precisa processar e responder. Esse conversationId
é mantido em cada par de solicitação e
resposta até que a conversa termine.
Corpo da solicitação
Quando os usuários fazem uma consulta inicial ou fornecem alguma entrada subsequente, o Google Assistente envia uma solicitação para o fulfillment. As solicitações de webhook de conversa do Google Assistente contêm dados como a intent acionada, o texto bruto da entrada do usuário e os recursos de superfície do dispositivo do usuário.
Veja abaixo um resumo dos principais campos de uma solicitação no formato de webhook de conversa:
Campo | Descrição |
---|---|
isInSandbox |
Essa variável booleana é usada principalmente no recurso
transações para indicar se o webhook precisa processar essa solicitação no modo
sandbox. No modo sandbox, seu webhook não pode cobrar nem atender a ordens de compra dos usuários.
Por padrão, ele é definido como "true ". |
surface |
Informações sobre a plataforma do Google Assistente com que o usuário está interagindo e os recursos dela. |
Inputs |
Informações sobre a solicitação de invocação. Para a invocação do acionador, isso inclui uma intent que é mapeada para uma ação. Para solicitações subsequentes em uma conversa, esse objeto também pode incluir argumentos correspondentes às entradas esperadas especificadas pelo fulfillment. |
User |
Informações sobre o usuário que iniciou a solicitação. Essas informações incluem as permissões concedidas pelo usuário e a localidade dele. |
Conversation |
Informações sobre o contexto da conversa, incluindo o ID, o tipo (por exemplo, se a solicitação está iniciando uma nova conversa) e um token para armazenar dados persistentes durante a conversa. |
availableSurfaces |
Essas informações são usadas para conversas em várias plataformas. |
Exemplo de solicitação de invocação simples
O snippet abaixo mostra um exemplo de solicitação de invocação no formato do webhook de conversa.
{ "user": { "userId": "ABwppHEF...", "locale": "en-US", "lastSeen": "2018-03-21T17:59:52Z", "userStorage": "{\"data\":{}}" }, "device": {}, "surface": { "capabilities": [ { "name": "actions.capability.SCREEN_OUTPUT" }, { "name": "actions.capability.AUDIO_OUTPUT" }, { "name": "actions.capability.MEDIA_RESPONSE_AUDIO" }, { "name": "actions.capability.WEB_BROWSER" } ] }, "conversation": { "conversationId": "1521784527171", "type": "NEW" }, "inputs": [ { "intent": "actions.intent.MAIN", "rawInputs": [ { "inputType": "VOICE", "query": "Talk to my test app" } ] } ], "availableSurfaces": [ { "capabilities": [ { "name": "actions.capability.SCREEN_OUTPUT" }, { "name": "actions.capability.AUDIO_OUTPUT" }, { "name": "actions.capability.MEDIA_RESPONSE_AUDIO" }, { "name": "actions.capability.WEB_BROWSER" } ] } ] }
Exemplo de solicitação de conversa simples
O snippet abaixo mostra um exemplo de uma solicitação de conversa no formato de webhook de conversa, em que a entrada do usuário é uma string de texto (por exemplo, "Meu número da sorte é 88"):
{ "user": { "userId": "ABwppHEF...", "locale": "en-US", "lastSeen": "2018-03-21T17:59:52Z", "userStorage": "{\"data\":{}}" }, "device": {}, "surface": { "capabilities": [ { "name": "actions.capability.SCREEN_OUTPUT" }, { "name": "actions.capability.AUDIO_OUTPUT" }, { "name": "actions.capability.MEDIA_RESPONSE_AUDIO" }, { "name": "actions.capability.WEB_BROWSER" } ] }, "conversation": { "conversationId": "1521784527171", "type": "NEW" }, "inputs": [ { "intent": "actions.intent.TEXT", "rawInputs": [ { "inputType": "VOICE", "query": "My lucky number is 88." } ] } ], "availableSurfaces": [ { "capabilities": [ { "name": "actions.capability.SCREEN_OUTPUT" }, { "name": "actions.capability.AUDIO_OUTPUT" }, { "name": "actions.capability.MEDIA_RESPONSE_AUDIO" }, { "name": "actions.capability.WEB_BROWSER" } ] } ] }
Corpo da resposta
O Content-Type
no cabeçalho das postagens HTTP do endpoint de fulfillment
para o Google Assistente precisa ser application/json
.
Uma resposta no formato de webhook de conversa contém dados como a IU real para mostrar ao usuário (incluindo componentes visuais e de áudio) e a intent que pode ser acionada na solicitação seguinte (chamada de intent esperada). A intent esperada pode ser qualquer uma das intents compreendidas pelo Google Assistente, conforme descrito na referência da API Intents.
Para saber mais sobre como formatar a interface do usuário para suas respostas quando elas são mostradas no Google Assistente, consulte a documentação Respostas.
Exemplo de resposta simples
O snippet abaixo mostra um exemplo de resposta simples no formato de webhook de conversa.
{ "expectUserResponse": true, "expectedInputs": [ { "possibleIntents": [ { "intent": "actions.intent.TEXT" } ], "inputPrompt": { "richInitialPrompt": { "items": [ { "simpleResponse": { "textToSpeech": "You are using the Actions SDK. Do you want to hear more about it?" } } ] } } } ] }
Exemplo de ajuda
O snippet abaixo mostra um exemplo de como usar uma intent auxiliar no formato de webhook de conversa. Neste exemplo, o webhook está usando a
intent auxiliar actions.intent.OPTIONS
para instruir o Google Assistente a acessar uma
seleção de usuário entre várias opções.
Para saber mais sobre o uso de intents auxiliares, consulte o guia Assistentes.
{ "expectUserResponse": true, "expectedInputs": [ { "possibleIntents": [ { "intent": "actions.intent.OPTION", "inputValueData": { "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec", "carouselSelect": { "items": [ { "optionInfo": { "key": "one", "synonyms": [ "synonym of KEY_ONE 1", "synonym of KEY_ONE 2" ] }, "description": "Description of number one", "title": "Number one" }, { "optionInfo": { "key": "two", "synonyms": [ "synonym of KEY_TWO 1", "synonym of KEY_TWO 2" ] }, "description": "Description of number two", "title": "Number two" } ] } } } ], "inputPrompt": { "richInitialPrompt": { "items": [ { "simpleResponse": { "textToSpeech": "this shows an example of a carousel" } } ], "suggestions": [ { "title": "1" }, { "title": "2" } ] } } } ] }
Exemplo de encerramento de conversa
O snippet abaixo mostra um exemplo de resposta simples para encerrar uma sessão de conversa no formato de resposta do webhook de conversa.
O valor expectedUserResponse
de false
na mensagem de resposta sinaliza ao Google Assistente que nenhuma outra entrada
do usuário é esperada e que a conversa atual precisa ser encerrada. O valor
finalResponse
indica o que o Google Assistente precisa mostrar ou enviar para o usuário antes
do fim da conversa.
{ "expectUserResponse": false, "finalResponse": { "richResponse": { "items": [ { "simpleResponse": { "textToSpeech": "Good bye" } } ] } } }
Para saber como substituir o comportamento padrão quando os usuários invocam uma frase padrão para encerrar uma conversa com o Google Assistente, consulte Saídas de conversas.