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

Esta seção descreve 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 usuário subsequente consulta ao Assistente, o fulfillment recebe uma intent que o webhook precisa processar e responder. Essa conversationId é mantida em todas as solicitações e par de respostas até que a conversa termine.

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

Corpo da solicitação

Quando o usuário faz uma consulta inicial ou fornece alguma entrada subsequente, o Assistente envia uma solicitação até o fulfillment. Solicitações de webhook de conversa do Google Assistente contêm dados como a intent que foi acionada e o texto bruto do usuário. entrada e os recursos de superfície do dispositivo do usuário.

Confira abaixo os principais campos de uma solicitação no formato webhook de conversa:

Campo	Descrição
isInSandbox	Essa variável booleana é usada principalmente para o transações para indicar se o webhook deve processar essa solicitação no sandbox modo No modo sandbox, o webhook não deve cobrar nem concluir as ordens de compra dos usuários. Por padrão, ela é definida 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 de acionamento, isso inclui um intent que mapeia para uma ação. Para os próximos solicitações em uma conversa, esse objeto também pode incluir argumentos correspondentes ao entradas esperadas especificadas pelo fulfillment.
User	Informações sobre o usuário que iniciou a solicitação. Essas informações incluem permissões concedidas pelo usuário e a localidade dele.
Conversation	Informações sobre o contexto da conversa, incluindo o ID e o tipo (por exemplo, se a solicitação está iniciando uma nova conversa) e um token de conversa para armazenar dados persistentes durante toda a vida útil da 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 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 solicitação de conversa no formato webhook de conversa. em que a entrada do usuário é uma string de texto (por exemplo, "My sorty number is 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 de postagens HTTP do endpoint de fulfillment para o Google Assistente precisa ser application/json.

Uma resposta na O formato webhook de conversa contém dados, como a interface real, para mostrar usuário (incluindo componentes de áudio e vídeo) e a intenção que pode ser acionada na solicitação seguinte (chamada de intent esperada). O resultado esperado pode ser qualquer uma das intents que o Google Assistente entender, conforme descrito na referência da API Intents.

Observação :nas suas respostas do webhook, normalmente você especifica actions.intent.TEXT. como a intent esperada. Essa intent representa uma resposta de texto bruto 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 das suas respostas ao eles são exibidos no Google Assistente, consulte Responses.

Exemplo de resposta simples

O snippet abaixo mostra um exemplo de resposta simples na conversa webhook.

{
  "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 na conversa webhook. Neste exemplo, o webhook está usando A intent auxiliar actions.intent.OPTIONS para instruir o Assistente a receber uma seleção do usuário entre várias opções.

Para saber mais sobre o uso de intents auxiliares, consulte 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 conversa no formato de resposta do webhook de conversa.

O expectedUserResponse false na mensagem de resposta sinaliza ao Google Assistente que nenhuma outra é esperada e deve encerrar a conversa atual. O finalResponse valor indica o que o Google Assistente precisa mostrar ou enviar para o usuário antes a conversa termina.

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "simpleResponse": {
            "textToSpeech": "Good bye"
          }
        }
      ]
    }
  }
}

Para saber como modificar o comportamento padrão quando os usuários invocam uma solicitação para encerrar uma conversa com o Assistente, consulte Saídas de conversas.