Formato de webhook de conversación {:#conversation-webhook-format} (Dialogflow)

En esta sección, se describe el formato de la carga útil de JSON cuando Actions on Google invoca tu entregas a través del SDK de Actions.

Cuando se inicia una conversación, se identifica con un conversationId único. Para cada usuario posterior al Asistente, tu entrega recibe un intent que el webhook debe procesar y responder. Este conversationId se conserva en todas las solicitudes y par de respuestas hasta que finalice la conversación.

Nota: Tu respuesta debe ocurrir dentro de 10 segundos; de lo contrario, el Asistente supone que se agotó el tiempo de espera de la entrega y finaliza la conversación.

Cuerpo de la solicitud

Cuando los usuarios hacen una consulta inicial o proporcionan alguna entrada posterior, Asistente envía una solicitud a tu entrega. Solicitudes de webhook de conversación del Asistente contienen datos como el intent que se activó, el texto sin procesar del usuario y las capacidades de superficie del dispositivo del usuario.

A continuación, se resumen los campos clave para una solicitud en el formato de webhook de conversación:

Campo	Descripción
isInSandbox	Esta variable booleana se utiliza principalmente para el atributo de transacciones para indicar si tu webhook debe controlar esta solicitud en la zona de pruebas. . En el modo de zona de pruebas, tu webhook no debe cobrar ni completar las órdenes de compra de los usuarios. De forma predeterminada, se establece en "true".
surface	Información sobre la superficie de Asistente con la que el usuario está interactuando y sus capacidades.
Inputs	Información sobre la solicitud de invocación. Para la invocación de activación, esto incluye un intent que se asigna a una acción. Para versiones posteriores solicitudes en una conversación, este objeto también puede incluir argumentos correspondientes al las entradas esperadas que especifique tu entrega.
User	Información sobre el usuario que inició la solicitud. Esta información incluye permisos que otorga el usuario y la configuración regional del usuario.
Conversation	Información sobre el contexto de la conversación, incluido su ID y el tipo (por ejemplo, si esta solicitud inicia una nueva conversación) y un token de conversación para almacenar datos persistentes a lo largo de toda la conversación.
availableSurfaces	Esta información se usa para conversaciones de superficies múltiples.

Ejemplo de solicitud de invocación simple

En el siguiente fragmento, se muestra un ejemplo de una solicitud de invocación en formato de webhook de conversación.

{
  "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"
        }
      ]
    }
  ]
}

Ejemplo de solicitud de conversación simple

El siguiente fragmento muestra un ejemplo de una solicitud de conversación en el formato de webhook de conversación. donde la entrada del usuario es una cadena de texto (por ejemplo, "Mi número de la suerte es 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"
        }
      ]
    }
  ]
}

Cuerpo de la respuesta

El Content-Type en el encabezado de las publicaciones HTTP desde tu extremo de entrega al Asistente debe ser application/json.

Una respuesta en la de webhook de conversación contiene datos como la IU real para mostrar el usuario (incluidos los componentes visuales y de audio), y la intención que se puede se activa en la solicitud posterior (denominado un intent esperado). Lo que se espera intent puede ser cualquiera de los intents que el Asistente comprenda, como se describe en la referencia de la API de Intents.

Nota: En las respuestas de webhook, por lo general, debes especificar actions.intent.TEXT que el intent esperado. Este intent representa una respuesta de texto sin procesar del usuario. La función genérica ask() de la biblioteca cliente espera este intent.

Para obtener más información sobre cómo dar formato a la interfaz de usuario en tus respuestas cuando se muestran en el Asistente, consulta la Respuestas.

Ejemplo de respuesta simple

El siguiente fragmento muestra un ejemplo de una respuesta simple en la conversación en formato de 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?"
              }
            }
          ]
        }
      }
    }
  ]
}

Ejemplo de ayuda

El siguiente fragmento muestra un ejemplo de uso de un intent auxiliar en la conversación en formato de webhook. En este ejemplo, el webhook usa El intent auxiliar actions.intent.OPTIONS para indicarle a Asistente que obtenga un la selección del usuario entre varias opciones.

Para obtener más información sobre el uso de intents auxiliares, consulta la Ayudante.

{
  "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"
            }
          ]
        }
      }
    }
  ]
}

Ejemplo de finalización de conversación

El siguiente fragmento muestra un ejemplo de una respuesta simple para finalizar una conversación en el formato de respuesta de webhook de conversación.

El expectedUserResponse de false en el mensaje de respuesta le indica al Asistente que ya no se espera una entrada y que esta finalice la conversación actual. El finalResponse valor indica qué debería mostrar el Asistente o enviar al usuario antes la conversación termina.

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

Para aprender a anular el comportamiento predeterminado cuando los usuarios invocan un frase para finalizar una conversación con el Asistente, consulta Salidas de la conversación.