Formato do webhook da conversa {:#conversation-webhook-format} (Dialogflow)

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.

Observação: sua resposta precisa ocorrer em até 10 segundos. Caso contrário, o Google Assistente vai presumir que o fulfillment expirou e encerrar a conversa.

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.

Observação: nas respostas do webhook, normalmente você especificará actions.intent.TEXT como a intent esperada. Essa intent representa uma resposta de texto bruta do usuário. A função ask() genérica na biblioteca de cliente espera essa intent.

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.