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 webhook 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 la información sobre contextos y parámetros.

A fin de ver más ejemplos de mensajes JSON para webhooks de Dialogflow, puedes consultar 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 Actions on Google, como se resume a continuación:

  • El valor de originalDetectIntentRequest.source es "google".
  • El originalDetectIntentRequest.version indica la versión de Actions on Google para la solicitud.
  • originalDetectIntentRequest.payload contiene información específica de Actions on Google, como la solicitud de conversación en JSON de Asistente.
  • El campo Conversation.conversationToken no es compatible con las solicitudes de webhook de Dialogflow. En su lugar, tu entrega puede usar un contexto de Dialogflow para conservar los datos durante la vida útil de la 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 formato de webhook de Dialogflow.

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

En el fragmento que aparece a continuación, se muestra un ejemplo de una solicitud de conversación en formato de webhook de Dialogflow, en la que la entrada del usuario es una string 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

En el siguiente fragmento, se 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 necesita 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 objeto payload que encapsula un objeto "google". El objeto de carga útil "google" incluye información específica de Actions on Google. Debe contener, como mínimo, un campo expectUserResponse y un campo richResponse o systemIntent.

A continuación, se resumen los campos clave para el objeto de carga útil "google":

Campo Descripción
expectUserResponse Indica si tu entrega espera una respuesta del usuario. Establece el valor en true para mantener viva la conversación y false para finalizar la conversación.
userStorage Almacena datos persistentes vinculados a un usuario específico. La cantidad de almacenamiento total es de 10,000 bytes.
richResponse Este campo contiene audio, texto, tarjetas, sugerencias o datos estructurados para que el Asistente los procese. 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. Por lo general, tu respuesta contiene un systemIntent si tu entrega usa un intent auxiliar. El campo possibleIntents de systemIntent se debe establecer como un objeto ExpectedIntent, con el nombre del campo inputValueData cambiado a data.

Dentro del objeto ExpectedIntent, especifica estos valores:

  • intent: Es un nombre de intent para el asistente que indica el tipo de información que quieres que proporcione el usuario.
  • data: Es una especificación de valor, una cadena que describe los datos necesarios para que Asistente realice el asistente.

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

En la siguiente lista, se resumen las strings de especificación de valor para los asistentes que puedes configurar en un systemIntent para una respuesta de webhook de Dialogflow. Si quieres obtener una lista completa de los intents de Actions on Google para el control de conversación, consulta la referencia de Intents.

Nombre del intent Nombre del evento de Dialogflow Especificación de valor Descripción
actions.intent.CONFIRMATION actions_intent_CONFIRMATION "@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec" Obtiene 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 la 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ínculos directos 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, incluidos 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

En el siguiente fragmento, se muestra un ejemplo de una respuesta simple en el formato de webhook de Dialogflow.

{
  "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 auxiliar en el formato de webhook de Dialogflow. En este ejemplo, tu webhook usa el intent auxiliar actions.intent.OPTIONS para indicarle al Asistente que obtenga una selección de 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"
              }
            ]
          }
        }
      }
    }
  }
}

Cuando recibe el mensaje del ejemplo anterior, Asistente se encarga de forma temporal de la conversación y le pide al usuario que realice una selección en función de las opciones proporcionadas. Cuando se recopila toda la entrada necesaria 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 de 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

En el siguiente fragmento, se muestra un ejemplo de una respuesta simple para finalizar una sesión de conversación en el formato de webhook de Dialogflow. El valor expectUserResponse de false en el mensaje de respuesta le indica a Asistente que no se esperan más entradas del usuario y que debe finalizar la conversación actual.

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

Si deseas obtener información para anular el comportamiento predeterminado cuando los usuarios invocan una frase estándar para finalizar una conversación con Asistente, consulta la guía de salidas de conversación.