Un webhook puede ser un webhook estándar o uno flexible. Con un webhook estándar, Dialogflow define los campos de solicitud y respuesta. Con un webhook flexible, defines los campos de solicitud y respuesta.
Webhooks estándar
Con webhooks estándar, usarás mensajes de solicitud y respuesta definidos por Dialogflow. 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, Dialogflow envía 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.
Algunos
integraciones
Propaga 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 de recursos de webhook estándar
A continuación, se describe la configuración de recursos de webhook para webhooks estándar:
Término | Definición |
---|---|
Nombre visible | El nombre que se muestra en la consola para el webhook. |
Tiempo de espera de webhook | Cuando Dialogflow envía una solicitud de webhook a tu servicio de webhook, es posible que se agote el tiempo de espera mientras se espera una respuesta. Esta configuración controla ese tiempo de espera en segundos. Si se produce un tiempo de espera, Dialogflow invoca un evento webhook.error.timeout. |
Tipo | Configúralo como Directorio de servicios si usas el directorio de servicios para el acceso a redes privadas. De lo contrario, configúralo como Servicio web genérico. |
URL de webhook | Proporciona la dirección URL para tu servicio de webhook. |
Subtipo | Debe establecerse 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 la AC personalizado | Se usa para subir certificados de la AC personalizados. |
Webhooks flexibles
Con webhooks flexibles, Defines el método HTTP de la solicitud, los parámetros de la 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 realmente beneficiosa, porque simplifica la interfaz entre el agente y el webhook. Rara vez se necesita comunicar algo 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, porque 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 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.
- Valores de parámetros de sesión que Dialogflow debe enviar al servicio de webhook usando la URL.
- Si eliges
POST
,PUT
oPATCH
como el método, puedes especificar los valores de los parámetros de sesión que Dialogflow se 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 escapar como URL de la referencia del parámetro. y no debes poner la referencia entre comillas. Durante el tiempo de ejecución, Dialogflow escapará la URL del valor del parámetro según sea necesario. Se proporcionará un valor compuesto o de lista en formato 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, Dialogflow quitará las comillas cuando envíe la solicitud en el tiempo de ejecución para preservar el tipo de datos del parámetro. Los tipos escalares de string permanecerán entre comillas. Si se hace referencia a un valor numérico escalar, de lista o compuesto en 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 del parámetro 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 de webhook flexible
Cuando crees el recurso webhook para tu agente, puedes especificar los parámetros de sesión que Dialogflow debe establecer a campos específicos de la respuesta del webhook en el entorno 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
}
}
]
}
]
}
Especificar el "valor" campo, 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 | El nombre que se muestra en la consola para el webhook. |
Tiempo de espera de webhook | Cuando Dialogflow envía una solicitud de webhook a tu servicio de webhook, es posible que se agote el tiempo de espera mientras espera una respuesta. Esta configuración controla ese tiempo de espera en segundos. Si se agota el tiempo de espera, Dialogflow invoca 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 | Proporcione la dirección URL de su servicio de webhook, que puede incluir referencias a parámetros de sesión. |
Subtipo | Configúralo en Flexible |
Método | Establece el método HTTP para la solicitud de webhook. |
Cuerpo de la solicitud | Proporciona el cuerpo JSON de la solicitud como se describió anteriormente. |
Configuración de respuesta | 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 la AC personalizado | Se usa para subir certificados de la AC personalizados. |
Usa una plantilla personalizada predefinida
Dialogflow ofrece plantillas personalizadas predefinidas que puedes usar para integrar webhooks flexibles con la 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 complete automáticamente el formulario de webhook según el nombre de la API que elegir.
Puedes configurar manualmente los siguientes campos, si corresponde, según tus parámetros:
- URL de webhook
- Método
- JSON del cuerpo de la solicitud
- Configuración de respuesta
Los campos obligatorios de OAuth se destacarán en Authentication secció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 el sección webhook estándar o 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 Dialogflow estén autorizados a realizar solicitudes. Esto se configura cuando se crea un recurso de webhook. Dialogflow CX admite los siguientes mecanismos de autenticación:
Término | Definición |
---|---|
Encabezados de autenticación | Para la configuración de webhook, puedes especificar pares clave-valor del encabezado HTTP opcionales. Si se proporcionan, Dialogflow agrega 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 | Para la configuración de webhook, puedes especificar valores opcionales de nombre de usuario y contraseña de acceso. Si se proporciona, Dialogflow agrega un encabezado HTTP de autorización a las solicitudes de webhook. Este encabezado tiene el 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 Dialogflow intercambie un token de acceso del proveedor de OAuth y lo agregue al 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 los 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 un token de ID en la autenticación del agente de servicio para usar tokens de ID del agente de servicio para la autenticación. Puede usarse para acceder a las funciones y los servicios de Cloud Run. |
Autenticación mutua de TLS | Consulta la documentación de Autenticación mutua de TLS. |
Verificación de certificados HTTPS
Dialogflow usa 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 utilizas entornos para aislar los sistemas de producción de los 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 única y parámetros de configuración de autenticación de cada entorno que hayas definido para el agente.
Esto te permite desarrollar y probar de forma segura las actualizaciones del código de tu webhook 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 flexible de recursos de webhook.
- Haz clic en Guardar.
API
Si deseas 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 de entorno | Interfaz de 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, Dialogflow 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.
Usa Cloud Run Functions
Dialogflow se integra en Funciones de Cloud Run, para crear 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 Dialogflow con la siguiente dirección para tu proyecto de agente:
Esta cuenta de servicio especial y la clave asociada normalmente se crea automáticamente cuando creas el primer agente de un proyecto. Si el 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 la Función de IAM del Invocador de Cloud Functions a la cuenta de servicio del Agente de servicio de Dialogflow en el proyecto de la función.
- Selecciona Service Agent Auth -> Token de ID en la sección Auth configuration.
Usa webhooks alojados en contenedores y el framework de Go ezcx
Si quieres implementar un webhook alojado en contenedores con Go, consulta el Framework de 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
Cloud Run funciones configuradas para aceptar tráfico interno de redes de VPC en o el mismo perímetro de VPC SC se pueden usar como un webhook agente está en el mismo proyecto o en el mismo perímetro de VPC SC.
Usa el Directorio de servicios para acceder a redes privadas
Dialogflow se integra al acceso a la red privada del Directorio de servicios, por lo que puede conectarse a destinos de webhook dentro de la 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 Dialogflow con la siguiente dirección para tu proyecto de agente:
Otorga a la cuenta de servicio del agente de servicio de Dialogflow 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 un verificación de tiempo de actividad privada para comprobar que tu Directorio de servicios esté configurado correctamente.
Autenticación del agente de servicio
Dialogflow puede generar un Token de ID o token de acceso mediante Agente de servicio de Dialogflow.
El token se agrega al encabezado HTTP de autorización cuando Dialogflow llama 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 que otorgues el rol de Invocador a
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
El público usado para generar el token de ID será la URL completa de webhook, excepto cualquier parámetro de consulta. Si usas Cloud Run, asegúrate de que esta URL sea compatible con los públicos de Cloud Run. Por ejemplo, si la URL de webhook se
https://myproject.cloudfunctions.net/my-function/method1?query=value
la siguiente URL debe estar en públicos personalizados.
https://myproject.cloudfunctions.net/my-function/method1
Cualquier webhook también puede validar el token de manera opcional con bibliotecas cliente de Google o bibliotecas de código abierto, github.com/googleapis/google-auth-library-nodejs.
Token de acceso
Se puede usar un token de acceso para acceder a otras APIs de Google Cloud después de otorgar los roles necesarios para
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Ejemplos y solución de problemas
Consulta la guía práctica de webhook.