Un webhook puede ser un webhook estándar o un webhook flexible. Con un webhook estándar, los agentes conversacionales (Dialogflow CX) definen los campos de solicitud y respuesta. Con un webhook flexible, defines los campos de solicitud y respuesta.
Webhooks estándar
Con los webhooks estándar, usas los mensajes de solicitud y respuesta definidos por los agentes conversacionales (Dialogflow CX). El mensaje de solicitud proporciona muchos detalles sobre la sesión. Por ejemplo, se incluyen la página activa actual, el intent coincidente reciente, los valores de los parámetros de sesión y las respuestas definidas por el agente.
Solicitud de webhook estándar
Cuando se llama a una entrega con un webhook, los agentes conversacionales (Dialogflow CX) envían una solicitud de webhook HTTPS POST a tu servicio de webhook.
El cuerpo de esta solicitud es un objeto JSON WebhookRequest
con información sobre la sesión.
Algunas integraciones propagan el campo WebhookRequest.payload
con información adicional.
Por ejemplo, la integración de la puerta de enlace telefónica de Dialogflow CX proporciona el identificador de llamadas del usuario final.
Consulta la documentación de referencia de WebhookRequest
(V3) o WebhookRequest
(V3Beta1) para obtener más detalles.
Respuesta de webhook estándar
Cuando tu servicio de webhook recibe una solicitud de webhook, necesita enviar una respuesta de webhook. Se aplican las siguientes limitaciones a tu respuesta:
- La respuesta debe ocurrir dentro del tiempo de espera que configures cuando crees el recurso de webhook; de lo contrario, se agotará el tiempo de espera de la solicitud.
- La respuesta debe tener un tamaño menor o igual que 64 KiB.
Consulta la documentación de referencia de WebhookResponse
(V3) o WebhookResponse
(V3Beta1) para obtener más detalles.
Configuración estándar de recursos de webhook
A continuación, se describe la configuración de recursos de webhook para los webhooks estándares:
Término | Definición |
---|---|
Nombre visible | Es el nombre que se muestra en la consola para el webhook. |
Tiempo de espera del webhook | Cuando los agentes conversacionales (Dialogflow CX) envían una solicitud de webhook a tu servicio de webhook, es posible que se agote el tiempo de espera mientras espera una respuesta. Este parámetro de configuración controla ese tiempo de espera en segundos. Si se produce un tiempo de espera, los agentes conversacionales (Dialogflow CX) invocan un evento webhook.error.timeout. |
Tipo | Establece Directorio de servicios si usas el directorio de servicios para acceder a redes privadas. De lo contrario, establece Servicio web genérico. |
URL de webhook | Proporciona la dirección URL de tu servicio de webhook. |
Subtipo | Se establece en Estándar. |
Webhook específico del entorno | Puedes proporcionar webhooks específicos del entorno. |
Autenticación | Consulta la sección de autenticación. |
Certificado de AC personalizado | Se usa para subir certificados de AC personalizados. |
Webhooks flexibles
Con webhooks flexibles, defines el método HTTP de la solicitud, los parámetros de URL de la solicitud y los campos de los mensajes de solicitud y respuesta. La solicitud solo puede proporcionar valores de parámetros seleccionados, y la respuesta solo puede proporcionar valores de anulación de parámetros. Esta limitación es beneficiosa, ya que simplifica la interfaz entre el agente y el webhook. En general, no es necesario comunicar nada más que los valores de los parámetros de sesión entre un agente y un webhook. También simplifica la implementación de tu webhook, ya que los mensajes de solicitud y respuesta solo contienen lo que necesitas, y puedes proporcionar mensajes de webhook únicos para varias situaciones.
Solicitud de webhook flexible
Cuando crees el recurso de webhook para tu agente, puedes especificar lo siguiente para las solicitudes de webhook:
- Es el método HTTP que se usa para las solicitudes de webhook que se envían a tu servicio de webhook.
- Son los valores de los parámetros de sesión que los agentes conversacionales (Dialogflow CX) deben enviar a tu servicio de webhook con la URL.
- Si eliges
POST
,PUT
oPATCH
como método, puedes especificar los valores de los parámetros de sesión que los agentes conversacionales (Dialogflow CX) deben enviar a tu servicio de webhook a través del cuerpo JSON de la solicitud.
Para enviar valores de parámetros de sesión con la URL de la solicitud o el cuerpo JSON, usa referencias de parámetros como lo harías normalmente. No es necesario que escapes la referencia del parámetro con una URL ni que la encierres entre comillas. Durante el tiempo de ejecución, Agentes conversacionales (Dialogflow CX) escapará el valor del parámetro como sea necesario. Se proporcionará una lista o un valor compuesto como JSON.
Cuando uses una referencia de parámetro en el cuerpo JSON, debes encerrar la referencia entre comillas, independientemente del tipo de parámetro. Si el parámetro es, en realidad, un valor escalar, una lista o un valor compuesto numérico, los agentes conversacionales (Dialogflow CX) quitarán las comillas cuando envíen la solicitud en el tiempo de ejecución para preservar el tipo de datos del parámetro. Los tipos de escalares de cadena permanecerán entre comillas. Si se hace referencia a un valor escalar, de lista o compuesto numérico dentro de un valor de cadena (por ejemplo, "Este es un número: $session.params.size"), el parámetro se tratará como una cadena ("Este es un número: 3").
Por ejemplo, puedes proporcionar los valores de los parámetros de sesión fruit
y size
a la URL de la solicitud de la siguiente manera:
https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size
Y, al cuerpo de la solicitud JSON, de la siguiente manera:
{
"fruitParameter": "$session.params.fruit",
"sizeParameter": "$session.params.size"
}
Respuesta flexible del webhook
Cuando crees el recurso de webhook para tu agente, puedes especificar los parámetros de sesión que los agentes de conversación (Dialogflow CX) deben establecer en campos específicos de la respuesta del webhook durante el tiempo de ejecución.
Se aplican las siguientes limitaciones a tu respuesta:
- La respuesta debe ocurrir dentro del tiempo de espera que configures cuando crees el recurso de webhook; de lo contrario, se agotará el tiempo de espera de la solicitud.
- La respuesta debe tener un tamaño menor o igual que 64 KiB.
Usa el siguiente formato para especificar un campo escalar, de lista o compuesto:
$.fully.qualified.path.to.field
Por ejemplo, considera la siguiente respuesta JSON:
{
"routes" : [
{
"legs" : [
{
"distance" : {
"text" : "2,064 mi",
"value" : 3321004
}
}
]
}
]
}
Para especificar el campo "value", usa lo siguiente:
$.routes[0].legs[0].distance.value
Configuración flexible de recursos de webhook
A continuación, se describe la configuración de recursos de webhook para webhooks flexibles:
Término | Definición |
---|---|
Nombre visible | Es el nombre que se muestra en la consola para el webhook. |
Tiempo de espera del webhook | Cuando los agentes conversacionales (Dialogflow CX) envían una solicitud de webhook a tu servicio de webhook, es posible que se agote el tiempo de espera mientras espera una respuesta. Este parámetro de configuración controla ese tiempo de espera en segundos. Si se produce un tiempo de espera, los agentes conversacionales (Dialogflow CX) invocan un evento webhook.error.timeout. |
Tipo | Establece Directorio de servicios si usas el directorio de servicios para acceder a redes privadas. De lo contrario, establece Servicio web genérico. |
URL de webhook | Proporciona la dirección URL de tu servicio de webhook, que puede incluir referencias a parámetros de sesión. |
Subtipo | Establece la opción en Flexible. |
Método | Establece el método HTTP para la solicitud delwebhook. |
Cuerpo de la solicitud | Proporciona el cuerpo JSON de la solicitud como se describió anteriormente. |
Configuración de respuestas | Proporciona los parámetros de sesión que se deben establecer en los campos de respuesta como se describió anteriormente. |
Webhook específico del entorno | Puedes proporcionar webhooks específicos del entorno. |
Autenticación | Consulta la sección de autenticación. |
Certificado de AC personalizado | Se usa para subir certificados de AC personalizados. |
Usa una plantilla personalizada predefinida
Dialogflow ofrece plantillas personalizadas predefinidas que puedes usar para integrar webhooks flexibles con el CRM de Salesforce.
En la pestaña Administrar, haz clic en Webhooks y, luego, en + Crear.
En Subtipo, selecciona Flexible.
Haz clic en Configurar con una plantilla predefinida para habilitar la función.
En el menú desplegable Tipo de integración, selecciona Salesforce.
En el menú desplegable Nombre de la API, selecciona un nombre de API. La plantilla completa automáticamente el formulario delwebhook según el nombre de la API que elijas.
Si corresponde, puedes configurar manualmente los siguientes campos según tus parámetros:
- URL de webhook
- Método
- Cuerpo JSON de la solicitud
- Configuración de la respuesta
Los campos de OAuth obligatorios se destacarán en la sección Autenticación.
Haz clic en Guardar para crear el webhook.
Requisitos del servicio de webhook
El servicio de webhook debe cumplir con los siguientes requisitos:
- Debe administrar solicitudes HTTPS. HTTP no es compatible. Si alojas tu servicio de webhook en Google Cloud Platform mediante una solución de Compute o de procesamiento sin servidores, consulta la documentación del producto para la entrega con HTTPS. A fin de conocer otras opciones de hosting, consulta Obtén un certificado SSL para el dominio.
- La URL para las solicitudes debe ser de acceso público, a menos que se aloje como una función de Cloud Run o se acceda a ella como un webhook del Directorio de servicios.
- Debe controlar las solicitudes y respuestas como se describe en la sección de webhook estándar o webhook flexible.
- Si tu agente no se integra al acceso a la red privada del Directorio de servicios, las llamadas de webhook se consideran fuera del perímetro de servicio y se bloquean cuando se habilitan los Controles del servicio de VPC. El Directorio de servicios admite extremos limitados. Consulta el Directorio de servicios para obtener más información.
Autenticación
Es importante proteger el servicio de webhook para que solo tú o tu agente de agentes conversacionales (Dialogflow CX) estén autorizados a realizar solicitudes. Esto se configura cuando se crea un recurso de webhook. Los agentes conversacionales (Dialogflow CX) admiten los siguientes mecanismos de autenticación:
Término | Definición |
---|---|
Encabezados de autenticación | Para la configuración del webhook, puedes especificar pares clave-valor de encabezado HTTP opcionales. Si se proporcionan, los agentes conversacionales (Dialogflow CX) agregan estos encabezados HTTP a las solicitudes de webhook. Es común proporcionar un solo par con una clave de authorization . Los valores de encabezado admiten referencias de parámetros de sesión y análisis de funciones del sistema, como en los mensajes de respuesta estáticos. |
Autenticación básica con nombre de usuario y contraseña | En la configuración del webhook, puedes especificar valores opcionales de nombre de usuario y contraseña de acceso. Si se proporciona, los agentes de conversación (Dialogflow CX) agregan un encabezado HTTP de autorización a las solicitudes de webhook. Este encabezado tiene el siguiente formato: "authorization: Basic <base 64 encoding of the string username:password>" . |
OAuth de terceros | Puedes especificar la configuración de OAuth de terceros para que los agentes conversacionales (Dialogflow CX) intercambien un token de acceso del sistema de OAuth y lo agreguen en el encabezado HTTP de autorización. Solo se admite el flujo de credenciales de cliente. |
Tokens de acceso del agente de servicio | Puedes seleccionar el token de acceso en la autenticación del agente de servicio para usar tokens de acceso del agente de servicio para la autenticación. Se puede usar para acceder a otras APIs de Google Cloud. |
Tokens de ID del agente de servicio | Puedes seleccionar el token de ID en la autenticación del agente de servicio para usar tokens de ID de agente de servicio para la autenticación. Se puede usar para acceder a las funciones y los servicios de Cloud Run. |
Autenticación mutua de TLS | Consulta la documentación de autenticación TLS mutua. |
OAuth de terceros
Los agentes conversacionales (Dialogflow CX) pueden recopilar un token de acceso de un proveedor de OAuth externo y agregarlo al encabezado HTTP de autorización cuando realizan sus solicitudes de webhook.
A continuación, se describe la configuración de recursos para OAuth de terceros:
Término | Definición |
---|---|
ID de cliente | Es el ID de cliente que se usará cuando se solicite un token de OAuth. |
Secreto del cliente | El secreto que se usará cuando se solicite un token de OAuth. |
URL del extremo de OAuth | La URL que se debe usar para solicitar un token de OAuth. |
Permisos de OAuth | Es una lista separada por comas de los permisos para los que se puede usar el token de OAuth. |
Las solicitudes que se envían a la URL del extremo de OAuth para recibir un token no incluyen los encabezados de solicitud personalizados configurados para la solicitud de webhook. Puedes pasar información personalizada al servidor de OAuth como parámetros dentro de la cadena de consulta de la URL del extremo de OAuth.
Tokens de acceso del agente de servicio
Los agentes conversacionales (Dialogflow CX) pueden generar un token de ID o un token de acceso con el agente de servicio de agentes conversacionales (Dialogflow CX).
El token se agrega en el encabezado HTTP de autorización cuando los agentes de conversación (Dialogflow CX) llaman a un webhook.
Token de ID
Se puede usar un token de ID para acceder a las funciones y los servicios de Cloud Run después de otorgar el rol de invocador a
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
El público que se use para generar el token de ID será la URL completa del webhook, excepto los parámetros de consulta. Si usas Cloud Run, asegúrate de que los públicos de Cloud Run admitan esta URL. Por ejemplo, si la URL del webhook es
https://myproject.cloudfunctions.net/my-function/method1?query=value
La siguiente URL debe estar en los públicos personalizados.
https://myproject.cloudfunctions.net/my-function/method1
Cualquier webhook también puede validar de manera opcional el token con bibliotecas cliente de Google o bibliotecas de código abierto como github.com/googleapis/google-auth-library-nodejs.
Token de acceso
Un token de acceso se puede usar para acceder a otras APIs de Google Cloud después de otorgar los roles necesarios a
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Verificación de certificados HTTPS
Los agentes conversacionales (Dialogflow CX) usan el almacén de confianza predeterminado de Google para verificar los certificados HTTPS. Si deseas usar certificados que el almacén de confianza predeterminado de Google no reconoce para tu servidor HTTPS, como certificados autofirmados o certificados raíz personalizados, consultaCertificados de CA personalizados.
Webhooks específicos del entorno
Si usas entornos para aislar los sistemas de producción de los sistemas de desarrollo (recomendado), puedes configurar tus webhooks para que sean específicos del entorno. Para cada recurso de webhook que definas, puedes proporcionar una URL y una configuración de autenticación únicas para cada entorno que hayas definido para el agente.
Esto te permite desarrollar y probar de forma segura las actualizaciones de código de tuwebhook antes de implementarlas en producción.
Crea o edita recursos de webhook
Una vez que tengas en ejecución un servicio de webhook, debes crear un recurso de webhook en tu agente que tenga información sobre la conectividad y la autenticación. Después de la creación, también puedes editar la configuración del recurso de webhook en cualquier momento.
Para crear o editar un recurso de webhook, haz lo siguiente:
Console
- Abre la consola de Dialogflow CX.
- Elige tu proyecto de Google Cloud.
- Selecciona el agente.
- Selecciona la pestaña Administrar.
- Haz clic en Webhooks.
- Haz clic en Crear o en un recurso de webhook de la lista para editarlo.
- Ingresa la configuración de recursos de webhook estándar o la configuración de recursos de webhook flexible.
- Haz clic en Guardar.
API
Para crear un recurso de webhook, consulta el método create
para el tipo Webhook
.
Para editar un recurso de webhook (excepto la configuración específica del entorno), consulta el método patch
o update
para el tipo Webhook
.
Selecciona un protocolo y una versión para la referencia de webhook:
Protocolo | V3 | V3beta1 |
---|---|---|
REST | Recurso de webhook | Recurso de webhook |
RPC | Interfaz de webhook | Interfaz de webhook |
C++ | WebhooksClient | No disponible |
C# | WebhooksClient | No disponible |
Go | WebhooksClient | No disponible |
Java | WebhooksClient | WebhooksClient |
Node.js | WebhooksClient | WebhooksClient |
PHP | No disponible | No disponible |
Python | WebhooksClient | WebhooksClient |
Ruby | No disponible | No disponible |
Para editar la configuración específica del entorno de un webhook, consulta el método patch
o update
para el tipo Environment
.
Selecciona un protocolo y una versión para la referencia del entorno:
Protocolo | V3 | V3beta1 |
---|---|---|
REST | Recurso del entorno | Recurso del entorno |
RPC | Interfaz del entorno | Interfaz del entorno |
C++ | EnvironmentsClient | No disponible |
C# | EnvironmentsClient | No disponible |
Go | EnvironmentsClient | No disponible |
Java | EnvironmentsClient | EnvironmentsClient |
Node.js | EnvironmentsClient | EnvironmentsClient |
PHP | No disponible | No disponible |
Python | EnvironmentsClient | EnvironmentsClient |
Ruby | No disponible | No disponible |
Errores de webhook
Si tu servicio de webhook encuentra un error mientras controla una solicitud de webhook, tu código de webhook debería mostrar uno de los siguientes códigos de estado HTTP:
400
Solicitud incorrecta401
Sin autorización403
Prohibido404
No encontrado500
Falla del servidor503
Servicio no disponible
En cualquiera de las siguientes situaciones de error, Agentes conversacionales (Dialogflow CX) invoca un error de webhook o un evento integrado de tiempo de espera y continúa el procesamiento de manera habitual:
- Se excedió el tiempo de espera de respuesta
- Código de estado de error recibido
- La respuesta no es válida
- El servicio de webhook no está disponible
Además, si la llamada al servicio de webhook se activó mediante una llamada a la API de detección de intents, el campo queryResult.webhookStatuses
en la respuesta de detección de intent contiene la información del estado del webhook.
Reintentos automáticos
Los agentes conversacionales (Dialogflow CX) incluyen mecanismos internos que vuelven a intentarlo automáticamente en ciertos errores de webhook para mejorar la solidez. Solo se vuelven a intentar los errores no terminales (por ejemplo, errores de tiempo de espera o de conexión).
Para reducir la probabilidad de llamadas duplicadas, haz lo siguiente:
- Establece umbrales de tiempo de espera de webhook más largos.
- Admite la idempotencia en la lógica del webhook o anula la duplicación.
Usa funciones de Cloud Run
Los agentes conversacionales (Dialogflow CX) se integran a las funciones de Cloud Run, por lo que puedes crear fácilmente un webhook seguro y sin servidores. Si creas una función que reside en el mismo proyecto que tu agente, solo debes seleccionar Service Agent Auth -> ID Token en la configuración de Auth. Luego, tu agente podrá llamar de forma segura a tu webhook.
Sin embargo, hay dos situaciones en las que debes configurar manualmente esta integración:
- Debe existir la cuenta de servicio del Agente de servicio de agentes de conversación (Dialogflow CX) con la siguiente dirección para tu proyecto de agente:
Esta cuenta de servicio especial y la clave asociada se suelen crear automáticamente cuando creas el primer agente para un proyecto. Si tu agente se creó antes del 1 de noviembre de 2020, puedes activar la creación de esta cuenta de servicio especial:service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
- Crea un agente nuevo para el proyecto.
- Ejecuta el siguiente comando:
gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
- Si tu función de webhook reside en un proyecto diferente al agente, debes proporcionar el rol de IAM del Invocador de Cloud Functions a la cuenta de servicio del Agente de servicio de agentes conversacionales (CX de Dialogflow) en el proyecto de la función.
- Selecciona Service Agent Auth -> ID Token en la sección de configuración de Auth.
Usa webhooks alojados en contenedores y el framework ezcx de Go
Si deseas implementar un webhook alojado en contenedores con Go, consulta el framework ezcx de Go. Este framework puede simplificar muchos de los pasos necesarios para crear un webhook.
Usa funciones de Cloud Run con tráfico solo interno
Las funciones de Cloud Run configuradas para aceptar tráfico interno de redes de VPC en el mismo proyecto o el mismo perímetro de VPC SC se pueden usar como webhook, siempre que el agente esté en el mismo proyecto o el mismo perímetro de VPC SC.
Usa el Directorio de servicios para acceder a redes privadas
Los agentes conversacionales (Dialogflow CX) se integran al acceso a la red privada del Directorio de servicios, por lo que pueden conectarse a destinos de webhook dentro de tu red de VPC. Esto mantiene el tráfico dentro de la red de Google Cloud y aplica IAM y los Controles del servicio de VPC.
Para configurar un webhook que se oriente a una red privada, sigue estos pasos:
Sigue las instrucciones de Configuración de la red privada del Directorio de servicios para configurar tu red de VPC y el extremo del Directorio de servicios.
Debe existir la cuenta de servicio del Agente de servicio de agentes de conversación (Dialogflow CX) con la siguiente dirección para tu proyecto de agente:
Otorga a la cuenta de servicio del agente de servicio de agentes conversacionales (Dialogflow CX) los siguientes roles de IAM:service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
servicedirectory.viewer
del proyecto del Directorio de serviciosservicedirectory.pscAuthorizedService
del proyecto de red
Cuando crees el webhook, proporciona el servicio del Directorio de servicios junto con la URL y la información de autenticación opcional.
Console
API
Consulta el campo
serviceDirectory
para el tipoWebhook
. .Selecciona un protocolo y una versión para la referencia de webhook:
Protocolo V3 V3beta1 REST Recurso de webhook Recurso de webhook RPC Interfaz de webhook Interfaz de webhook C++ WebhooksClient No disponible C# WebhooksClient No disponible Go WebhooksClient No disponible Java WebhooksClient WebhooksClient Node.js WebhooksClient WebhooksClient PHP No disponible No disponible Python WebhooksClient WebhooksClient Ruby No disponible No disponible
Para solucionar problemas, puedes configurar una verificación de tiempo de actividad privada para verificar que tu Directorio de servicios esté configurado correctamente.
Muestras y solución de problemas
Consulta la guía práctica de webhooks.