En esta guía, se proporcionan varios ejemplos para implementar webhooks, así como recomendaciones para solucionar problemas de webhooks.
Establece un parámetro de sesión
En los siguientes ejemplos, se muestra cómo establecer un parámetro de sesión.
Go
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Consulta la guía de inicio rápido de Webhooks.Java
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Devuelve una respuesta de entrega
En los siguientes ejemplos, se muestra cómo devolver una respuesta de entrega.
Go
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Consulta la guía de inicio rápido de webhooks.Java
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Establece los parámetros de formulario según sea necesario
En los siguientes ejemplos, se muestra cómo marcar un parámetro como obligatorio.
Java
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Valida un parámetro de formulario
En los siguientes ejemplos, se muestra cómo validar un parámetro de formulario.
Java
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
ID de sesión de registro
En el siguiente ejemplo, se muestra cómo registrar el session ID
desde una solicitud de webhook.
Python
Para autenticarte en Dialogflow CX, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Soluciona problemas
Ciclo de vida de una llamada de webhook
Las llamadas de webhook siempre las inicia Dialogflow CX y van a un servidor web a través de HTTPS. Las llamadas de webhooks de servicios web genéricos se originan en una dirección IP de Internet que pertenece a Google y puede llegar a servidores web (servidores de webhook) que están disponibles en la Internet pública. Por otro lado, los webhooks del Directorio de servicios siempre comienzan desde una dirección Google Cloud interna y solo pueden llegar a los servidores de webhook en redes privadas dentro de Google Cloud.
Registros útiles para depurar webhooks
La depuración de problemas de webhook suele implicar la recopilación de los registros de Dialogflow CX de Cloud Logging y los registros del servidor de webhook. Si el servidor de webhook se implementa con Cloud Run Functions, sus registros estarán en Cloud Logging. De lo contrario, los registros suelen residir donde se ejecuta el servidor de webhook.
Los registros de webhook estándar contienen un campo detectIntentResponseId con un UUID que puede ser
útil para rastrear una llamada en particular en los servidores de webhook. Este registro existe en
los registros de Cloud Logging de Dialogflow CX cuando
Cloud Logging está habilitado.
Problemas comunes con los webhooks
Estos son algunos errores que se pueden encontrar en los registros de Dialogflow CX para las llamadas a webhooks:
Error de resolución del nombre de host del servidor de webhook
Dialogflow CX buscó el nombre de host de un webhook genérico y
este no existe en el DNS. Asegúrate de que el nombre de host esté registrado
en el DNS público. Si el nombre de host es nuevo, es posible que el registro tarde un poco en propagarse. Mensaje de Cloud Logging:
State: URL_ERROR, Reason: ERROR_DNS.
El servidor de webhook devuelve un error del cliente
Además de ERROR_DNS, este estado indica una respuesta 4xx del servidor del webhook. Puede ser un estado no autorizado (401: ERROR_AUTHENTICATION)
o que no se encontró la URL en el servidor de webhook (404: ERROR_NOT_FOUND).
Mensaje de registro de Cloud Logging: State: URL_ERROR.
Se agota el tiempo de espera del agente de Dialogflow antes de que el servidor de webhook devuelva una respuesta
Dialogflow CX alcanzó el límite de tiempo de espera del webhook antes de que finalizara el servidor web. Los dos enfoques posibles aquí son reducir el tiempo de procesamiento del servidor de webhook o aumentar el tiempo que Dialogflow CX espera el webhook. Por lo general, reducir el tiempo de procesamiento genera mejores resultados, aunque
no es trivial en muchos casos. Ten en cuenta que hay un límite de tiempo de espera máximo
para los webhooks y que los emisores o usuarios finales tendrían que esperar más tiempo para obtener
una respuesta del agente antes de aumentar este parámetro de configuración. Mensaje de Cloud Logging: State: URL_TIMEOUT, Reason: TIMEOUT_WEB.
gRPC agota el tiempo de espera antes de que el servidor de webhook devuelva una respuesta
Se alcanzó el límite de tiempo establecido por gRPC en la llamada a la API de Dialogflow CX
antes de que finalizara la llamada al webhook. Este límite suele establecerse a nivel de la integración
y es independiente de los parámetros de Dialogflow CX y de los límites de tiempo de espera
del webhook. Para obtener más información sobre los plazos de gRPC, consulta
https://grpc.io/docs/guides/deadlines/.
Mensaje de Cloud Logging: State: URL_REJECTED, Reason: REJECTED_DEADLINE_EXCEEDED.
Dialogflow no pudo comunicarse con el servidor de webhook
No se pudo acceder al servidor de webhook debido a
un error de red o se estableció la conexión y el servidor de webhook
devolvió el estado HTTP 5xx, lo que indica un problema mientras se procesaba la
solicitud. Asegúrate de que Dialogflow CX pueda acceder a la dirección del servidor de webhook
a nivel de red. Si la solicitud aparece en los registros del servidor del webhook,
busca por qué la llamada devolvió un error 5xx. Mensaje de Cloud Logging:
State: URL_UNREACHABLE.
Realiza un seguimiento de las llamadas de webhook
Se puede correlacionar una llamada de webhook estándar entre Dialogflow CX y
un servidor de webhook con el ID de sesión, el ID de detectIntentResponse, el ID de seguimiento
para Cloud Run Functions y una marca de tiempo de la llamada. El seguimiento flexible de webhooks se puede realizar con la marca de tiempo de la llamada y los valores de los parámetros de sesión especificados en la definición del webhook en el momento del diseño. Para obtener más información
sobre las solicitudes de webhooks estándar y flexibles, consulta
Webhooks.
El ID de sesión aparece en el campo sessionInfo.session de la
WebhookRequest.
Este ID de sesión debe ser único para cada conversación
y puede ayudarte a comparar los registros del agente con los registros del webhook
para las solicitudes que usan el mismo ID de sesión.
En la sección anterior, Registra el ID de sesión,
se muestra cómo registrar el ID de sesión desde un webhook.
Además, si alojas tu webhook en
Cloud Run Functions
o en una opción sin servidores similar de Google Cloud ,
puedes usar el campo trace de
las entradas de registro
como un filtro de registro.
Una sola ejecución de una función genera varias entradas de registro
con el mismo valor de seguimiento.
En el siguiente ejemplo, se usan el ID de sesión y el valor de seguimiento para asociar un registro de errores de un agente de Dialogflow CX en particular con las entradas de registro del webhook de Cloud Run Functions correspondientes. En el ejemplo, se usan filtros de Cloud Logging para un agente que habilitó Cloud Logging.
1. Filtra los registros de Dialogflow CX para obtener los registros de errores de un agente en particular
Usa el siguiente filtro de Cloud Logging para filtrar los registros de Dialogflow CX de los registros de errores de un agente en particular:
labels.location_id="global"
labels.agent_id="AGENT_ID"
severity=ERROR
Una entrada de error de registro de webhook se ve de la siguiente manera:
{
"insertId": "-j4gkkre31e2o",
"jsonPayload": {
"code": 14,
"message": "Error calling webhook 'https://us-central1-PROJECT_ID.cloudfunctions.net/function-webhook': State: URL_UNREACHABLE, Reason: UNREACHABLE_5xx, HTTP status code: 500"
},
"labels": {
"agent_id": "e9e01392-1351-42dc-9b15-b583fb2d2881",
"environment_id": "",
"location_id": "global",
"session_id": "07c899-a86-78b-a77-569625b37"
},
"logName": "projects/PROJECT_ID/logs/dialogflow-runtime.googleapis.com%2Frequests",
"receiveTimestamp": "2024-10-28T21:49:04.288439054Z",
"resource": {
"labels": {
"project_id": "PROJECT_ID"
},
"type": "global",
},
"severity": "ERROR",
"timestamp": "2024-10-28T21:49:04.132548Z"
}
Observa el campo labels.session_id, que contiene el ID de sesión.
Usarás el ID de sesión en el siguiente paso.
2. Filtra los registros de Cloud Run Functions por ID de sesión
Usa el siguiente filtro de Cloud Logging para filtrar los registros de Cloud Run Functions por ID de sesión:
resource.type = "cloud_run_revision"
resource.labels.service_name = "CLOUD_RUN_FUNCTION_NAME"
resource.labels.location = "CLOUD_RUN_FUNCTION_REGION"
textPayload="Debug Node: session ID = SESSION_ID"
Los registros resultantes corresponden a los registros de webhook realizados durante la sesión proporcionada. Por ejemplo:
{
"insertId": "671c42940007ebebdbb1d56e",
"labels": {
"execution_id": "pgy8jvvblovs",
"goog-managed-by": "cloudfunctions",
"instance_id": "004940b3b8e3d975a4b11a4ed7d1ded4ce3ed37467ffc5e2a8f13a1908db928f8200b01cc554a5eda66ffc9d23d76dd75cec1619a07cb5751fa2e8a93bc6cfc3df86dfa0650a"
},
"logName": "projects/PROJECT_ID/logs/run.googleapis.com%2Fstdout",
"receiveTimestamp": "2024-10-26T01:15:00.523313187Z",
"resource": {
"labels": {
"configuration_name": "function-webhook",
"location": "us-central1",
"project_id": "PROJECT_ID",
"revision_name": "function-webhook-00001-jiv",
"service_name": "function-webhook",
},
"type": "cloud_run_revision"
},
"spanId": "6938366936362981595",
"trace": "d1b54fbc8945dd59bdcaed37d7d5e185",
"textPayload": "Debug Node: session ID = 07c899-a86-78b-a77-569625b37",
"timestamp": "2024-10-26T01:15:00.519147Z"
}
Toma nota del campo trace, que se usa en el siguiente paso.
3. Filtra los registros de Cloud Functions para un seguimiento en particular
Usa el siguiente filtro de Cloud Logging para filtrar los registros de Cloud Function de un seguimiento en particular:
resource.type = "cloud_run_revision"
resource.labels.service_name = "CLOUD_RUN_FUNCTION_NAME"
resource.labels.location = "CLOUD_RUN_FUNCTION_REGION"
trace="projects/PROJECT_ID/traces/TRACE_ID"
donde TRACE_ID es el último segmento de la traza. Por ejemplo, el TRACE_ID
para projects/PROJECT_ID/traces/e41eefc1fac48665b442bfa400cc2f5e es
e41eefc1fac48665b442bfa400cc2f5e.
El resultado es el registro del servidor de webhook que se generó durante la ejecución de la solicitud de webhook asociada con el ID de sesión del paso 1 y con el seguimiento del paso 2. El registro se vería de la siguiente manera.
{
"insertId": "671c42940008465e29f5faf0",
"httpRequest": {
"requestMethod": "POST",
"requestUrl": "https://us-central1-TEST_PROJECT.cloudfunctions.net/function-webhook",
"requestSize": "2410",
"status": 200,
"responseSize": "263",
"userAgent": "Google-Dialogflow",
"remoteIp": "8.34.210.1",
"serverIp": "216.239.36.1",
"latency": "0.166482342s",
"protocol": "HTTP/1.1"
},
"resource": {
"type": "cloud_run_revision",
"labels": {
"project_id": "PROJECT_ID",
"service_name": "function-webhook",
"location": "us-central1",
"revision_name": "function-webhook-00001-jiv",
"configuration_name": "function-webhook"
}
},
"timestamp": "2024-10-26T01:15:00.352197Z",
"severity": "INFO",
"labels": {
"instanceId": "004940b3b813af8a656c92aac1bd07ffad5165f1353e1e346b6161c14bcde225f68f4a88ceedc08aa9020f387b1b59471f73de45f2882a710ced37dea921f05ad962347690be",
"goog-managed-by": "cloudfunctions"
},
"logName": "projects/test-project-12837/logs/run.googleapis.com%2Frequests",
"trace": "projects/test-project-12837/traces/d1b54fbc8945dd59bdcaed37d7d5e185",
"receiveTimestamp": "2024-10-26T01:15:00.548931586Z",
"spanId": "604a07f7b33b18db",
"traceSampled": true
}