Formato de webhook de Dialogflow {:#dialogflow-webhook-format} (Dialogflow)

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

Si usas Dialogflow para crear acciones, tu entrega se comunica con Dialogflow a través de su propio formato de webhook estándar en lugar del Formato de webhooks de conversaciones de Actions on Google. El formato de webhook de Dialogflow contiene toda la información del formato de webhook de conversación junto con datos adicionales específicos de Dialogflow, como información sobre contextos y parámetros.

Si quieres ver más ejemplos de mensajes JSON para webhooks de Dialogflow, puedes consultar a este proyecto de GitHub.

Cuerpo de la solicitud

El mensaje request de Dialogflow contiene datos en el formato de webhook de Dialogflow. Este objeto incluye información específica de Acciones en Google, como se resume a continuación:

  • El valor de originalDetectIntentRequest.source es "google".
  • originalDetectIntentRequest.version indica la versión de Actions on Google para la solicitud.
  • El elemento originalDetectIntentRequest.payload contiene acciones clave específicas de Actions on Google información, incluida la conversación solicitud JSON desde el Asistente.
  • Las solicitudes de webhook de Dialogflow no admiten el campo Conversation.conversationToken. En su lugar, tu entrega puede usar un bucket context para conservar datos en todo de conversación.

Ejemplo de solicitud de invocación simple

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

{
  "responseId": "c4b863dd-aafe-41ad-a115-91736b665cb9",
  "queryResult": {
    "queryText": "GOOGLE_ASSISTANT_WELCOME",
    "action": "input.welcome",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "",
    "fulfillmentMessages": [],
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_welcome"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_voice"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/8b006880-0af7-4ec9-a4c3-1cc503ea8260",
      "displayName": "Default Welcome Intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": [
          {
            "name": "actions.capability.SCREEN_OUTPUT"
          },
          {
            "name": "actions.capability.AUDIO_OUTPUT"
          },
          {
            "name": "actions.capability.WEB_BROWSER"
          },
          {
            "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
          }
        ]
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "Talk to my test app",
              "inputType": "VOICE"
            }
          ],
          "intent": "actions.intent.MAIN"
        }
      ],
      "user": {
        "lastSeen": "2018-03-16T22:08:48Z",
        "permissions": [
          "UPDATE"
        ],
        "locale": "en-US",
        "userId": "ABwppHEvwoXs18xBNzumk18p5h02bhRDp_riW0kTZKYdxB6-LfP3BJRjgPjHf1xqy1lxqS2uL8Z36gT6JLXSrSCZ"
      },
      "conversation": {
        "conversationId": "${SESSIONID}",
        "type": "NEW"
      },
      "availableSurfaces": [
        {
          "capabilities": [
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            },
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            }
          ]
        }
      ]
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Ejemplo de solicitud de conversación simple

El siguiente fragmento muestra un ejemplo de una solicitud de conversación en Dialogflow webhook, en el que la entrada del usuario es una cadena de texto.

{
  "responseId": "68efa569-4ba1-4b7f-9b1b-ac2865deb539",
  "queryResult": {
    "queryText": "query from the user",
    "action": "action.name.of.matched.dialogflow.intent",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_keyboard"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1f4e5bd9-a670-4161-a22e-2c97b077f29f",
      "displayName": "Name of Dialogflow Intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": [
          {
            "name": "actions.capability.SCREEN_OUTPUT"
          },
          {
            "name": "actions.capability.AUDIO_OUTPUT"
          },
          {
            "name": "actions.capability.WEB_BROWSER"
          },
          {
            "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
          }
        ]
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "query from the user",
              "inputType": "KEYBOARD"
            }
          ],
          "arguments": [
            {
              "rawText": "query from the user",
              "textValue": "query from the user",
              "name": "text"
            }
          ],
          "intent": "actions.intent.TEXT"
        }
      ],
      "user": {
        "lastSeen": "2017-10-06T01:06:56Z",
        "locale": "en-US",
        "userId": "AI_yXq-AtrRh3mJX5D-G0MsVhqun"
      },
      "conversation": {
        "conversationId": "1522951193000",
        "type": "ACTIVE",
        "conversationToken": "[]"
      },
      "availableSurfaces": [
        {
          "capabilities": [
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            },
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            }
          ]
        }
      ]
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Ejemplo de resultado de ayuda

El siguiente fragmento muestra un ejemplo de un resultado auxiliar en el formato de webhook de Dialogflow. En este ejemplo, se muestra la respuesta del usuario después de que el webhook le indica al Asistente que debe obtener la confirmación del usuario.

{
  "responseId": "cb6f5ec2-c26e-4349-b561-a9ddd6a0e495",
  "queryResult": {
    "queryText": "actions_intent_CONFIRMATION",
    "action": "Dialogflow action name of matched intent",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_confirmation",
        "parameters": {
          "CONFIRMATION": true
        }
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
      "displayName": "Dialogflow action name of matched intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {},
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "yes",
              "inputType": "VOICE"
            }
          ],
          "arguments": [
            {
              "name": "CONFIRMATION",
              "boolValue": true
            }
          ],
          "intent": "actions.intent.CONFIRMATION"
        }
      ],
      "user": {},
      "conversation": {},
      "availableSurfaces": []
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

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.

El mensaje de respuesta que tu entrega envía a Dialogflow debe estar en el formato de webhook de Dialogflow.

Cuando te comunicas con Asistente, tu respuesta suele contener un payload objeto que encapsula un "google" . "google" el objeto de carga útil incluye Información específica de Actions on Google Debe contener, como mínimo, un expectUserResponse y un campo richResponse o systemIntent.

Los campos clave para “google” de carga útil se resumen a continuación:

Campo Descripción
expectUserResponse Indica si tu entrega espera una respuesta del usuario. Establece el valor en true cuándo continuar la conversación y false para finalizar la conversación.
userStorage Almacena datos persistentes vinculados a un usuario específico. El almacenamiento total es de 10,000 bytes.
richResponse Este campo contiene audio, texto, tarjetas, sugerencias o datos estructurados para que el Asistente la renderice. Si deseas obtener más información sobre el uso de respuestas enriquecidas para Actions on Google, consulta Respuestas enriquecidas
systemIntent Este campo tiene la misma estructura que ExpectedInput.possibleIntents Tu respuesta suele contener un systemIntent si tu entrega usa un intent auxiliar. El possibleIntents de systemIntent se debe establecer en una ExpectedIntent objeto, con el nombre del campo inputValueData cambiado a data.

En ExpectedIntent debes especificar estos valores:

  • intent: un nombre de intent para el asistente que indica el tipo de información que deseas que el usuario proporcione y
  • data: una especificación de valor, que es una cadena que describe los datos necesarias para que Asistente realice la tarea de ayuda.

Por ejemplo, si solicitas el permiso del usuario, configura intent como actions.intent.PERMISSSION y el data a la especificación de valor para "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec", junto con los campos para de ese tipo.

La siguiente lista resume las cadenas de especificación de valor para los asistentes que puedes configurar en un systemIntent para una respuesta de webhook de Dialogflow. Para obtener una lista completa de los intents de Actions on Google para el control conversacional, consulta la Referencia de los intents

Nombre del intent Nombre del evento de Dialogflow Especificación del valor Descripción
actions.intent.CONFIRMATION actions_intent_CONFIRMATION "@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec" Permite obtener una confirmación del usuario (por ejemplo, una respuesta a una pregunta de sí o no).
actions.intent.DATETIME actions_intent_DATETIME "@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec" Obtiene una entrada de fecha y hora del usuario.
actions.intent.DELIVERY_ADDRESS actions_intent_DELIVERY_ADDRESS "@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec" Obtiene una entrada de dirección de entrega del usuario.
actions.intent.LINK actions_intent_LINK "@type": "type.googleapis.com/google.actions.v2.LinkValueSpec" Solicita un flujo de vínculo directo a una app para Android.
actions.intent.OPTION actions_intent_OPTION "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec" Obtiene el elemento seleccionado de una IU de lista o carrusel.
actions.intent.PERMISSION actions_intent_PERMISSION "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" Obtiene la información del usuario, incluido el nombre completo, la ubicación aproximada o la ubicación precisa.
actions.intent.SIGN_IN actions_intent_SIGN_IN "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec" Solicita un flujo de vinculación de cuentas para vincular la cuenta de un usuario.

Ejemplo de respuesta simple

El siguiente fragmento muestra un ejemplo de una respuesta simple en el código en formato de webhook.

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "this is a simple response"
            }
          }
        ]
      }
    }
  }
}

Ejemplo de ayuda

El fragmento que aparece a continuación muestra un ejemplo del uso de un intent de ayuda en Dialogflow en formato de webhook. En este ejemplo, tu webhook usa El intent auxiliar actions.intent.OPTIONS para indicarle a Asistente que obtenga un a la selección del usuario entre dos opciones.

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Choose a item"
            }
          }
        ]
      },
      "systemIntent": {
        "intent": "actions.intent.OPTION",
        "data": {
          "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
          "listSelect": {
            "title": "Hello",
            "items": [
              {
                "optionInfo": {
                  "key": "first title key"
                },
                "description": "first description",
                "image": {
                  "url": "/assistant/images/badges/XPM_BADGING_GoogleAssistant_VER.png",
                  "accessibilityText": "first alt"
                },
                "title": "first title"
              },
              {
                "optionInfo": {
                  "key": "second"
                },
                "description": "second description",
                "image": {
                  "url": "https://lh3.googleusercontent.com/Nu3a6F80WfixUqf_ec_vgXy_c0-0r4VLJRXjVFF_X_CIilEu8B9fT35qyTEj_PEsKw",
                  "accessibilityText": "second alt"
                },
                "title": "second title"
              }
            ]
          }
        }
      }
    }
  }
}

Al recibir el mensaje del ejemplo anterior, Asistente se hace cargo de la conversación y le pide al usuario que haga una selección en función de las opciones dadas. Cuando se recopilan todas las entradas requeridas del usuario, el Asistente envía este resultado auxiliar a tu entrega en una solicitud de webhook de Dialogflow.

El siguiente fragmento muestra un ejemplo del resultado auxiliar con la selección a elección del usuario.

{
  "responseId": "ea166558-615a-48f3-ae5b-7f55d895784b",
  "queryResult": {
    "queryText": "actions_intent_OPTION",
    "action": "",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "",
    "fulfillmentMessages": [],
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_option",
        "parameters": {
          "OPTION": "key of selected item"
        }
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
      "displayName": "Dialogflow intent name of matched intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": []
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "Title of selected item",
              "inputType": "TOUCH"
            }
          ],
          "arguments": [
            {
              "textValue": "Key of selected item",
              "name": "OPTION"
            }
          ],
          "intent": "actions.intent.OPTION"
        }
      ],
      "user": {},
      "conversation": {},
      "availableSurfaces": []
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

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 webhook de Dialogflow. El expectUserResponse valor de false en los mensajes de respuesta que se le envían a Asistente que no se esperan más entradas del usuario y que debería finalizar el conversación.

{
  "payload": {
    "google": {
      "expectUserResponse": false,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Goodbye!"
            }
          }
        ]
      }
    }
  }
}

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