Para usar entregas en un sistema de producción, debes implementar y aplicar un servicio de webhook. Para administrar la entrega, el servicio webhook debe aceptar solicitudes JSON y mostrar respuestas JSON como se especifica en esta guía. El flujo de procesamiento detallado para las entregas y los webhooks se describe en el documento de descripción general de las entregas.
Requisitos del servicio de webhook
El servicio de webhook debe cumplir con los siguientes requisitos:
- Administrar solicitudes HTTPS. HTTP no es compatible. Si alojas tu servicio de webhook en Google Cloud con una solución de Compute o de procesamiento sin servidores, consulta la documentación del producto para la entrega con HTTPS. Para conocer otras opciones de hosting, consulta Obtén un certificado SSL para el dominio.
- Asegurarse de que se pueda acceder públicamente a la URL del servicio de webhook.
- Administrar las solicitudes POST con un cuerpo JSON
WebhookRequest. - Responder a las solicitudes
WebhookRequestcon un cuerpo JSONWebhookResponse.
Autenticación
| X | Elemento |
|---|---|
| Nombre de usuario y contraseña de acceso | 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 siguiente formato: "authorization: Basic <base 64 encoding of the string username:password>". |
| Encabezados de autenticación | Para la configuración de webhook, puedes especificar pares clave-valor de 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. |
| Autenticación integrada de Cloud Run Functions | Puedes usar la autenticación integrada cuando usas Cloud Run Functions. Para usar este tipo de autenticación, no proporciones encabezados de nombre de usuario, contraseña ni autorización. Si proporcionas alguno de estos campos, no se usarán para la autenticación integrada. |
| Tokens de identidad del servicio | Puedes usar tokens de identidad del servicio para la autenticación. Si no proporcionas el nombre de usuario de acceso, la contraseña de acceso o un encabezado con una clave de authorization, Dialogflow asume automáticamente que se deben usar tokens de identidad del servicio y agrega un encabezado HTTP de autorización a las solicitudes de webhook. Este encabezado tiene el siguiente formato: "authorization: Bearer <identity token>". |
| Autenticación TLS mutua | Consulta la documentación de autenticación TLS mutua . |
Solicitud de webhook
Cuando hay una coincidencia con un intent configurado para la entrega, Dialogflow envía una solicitud POST HTTPS del webhook al servicio de webhook. El cuerpo de esta solicitud es un objeto JSON con información sobre el intent coincidente.
Además de la consulta del usuario final, muchas integraciones también envían información sobre este. Por ejemplo, un ID que identifica de forma única al usuario. Se puede acceder a esta información a través del campo originalDetectIntentRequest en la solicitud de webhook, que contiene la información enviada desde la plataforma de integración.
Para obtener más información, consulta la
WebhookRequest
documentación de referencia.
La siguiente es una solicitud de muestra:
{
"responseId": "response-id",
"session": "projects/project-id/agent/sessions/session-id",
"queryResult": {
"queryText": "End-user expression",
"parameters": {
"param-name": "param-value"
},
"allRequiredParamsPresent": true,
"fulfillmentText": "Response configured for matched intent",
"fulfillmentMessages": [
{
"text": {
"text": [
"Response configured for matched intent"
]
}
}
],
"outputContexts": [
{
"name": "projects/project-id/agent/sessions/session-id/contexts/context-name",
"lifespanCount": 5,
"parameters": {
"param-name": "param-value"
}
}
],
"intent": {
"name": "projects/project-id/agent/intents/intent-id",
"displayName": "matched-intent-name"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en"
},
"originalDetectIntentRequest": {}
}
Respuesta de webhook
Después de que el webhook recibe una solicitud, debe enviar una respuesta. El cuerpo de esta respuesta es un objeto JSON que contiene la siguiente información:
- La respuesta que Dialogflow le muestra al usuario final.
- Las actualizaciones de los contextos activos para la conversación.
- Un evento de seguimiento para activar la coincidencia de un intent
- Una carga útil personalizada para enviar a la integración o al cliente de intents de detección.
Se aplican las siguientes limitaciones a tu respuesta:
- Responde en un plazo de 10 segundos para las aplicaciones del Asistente de Google o de 5 segundos para todas las otras aplicaciones; de lo contrario, se agotará el tiempo de espera de la solicitud.
- Mantén el tamaño de la respuesta en 64 KiB o menos.
Para obtener más información, consulta la
WebhookResponse
documentación de referencia.
Respuesta de texto
A continuación, se muestra un ejemplo de una respuesta de texto:
{
"fulfillmentMessages": [
{
"text": {
"text": [
"Text response from webhook"
]
}
}
]
}
Respuesta de tarjeta
A continuación, se muestra un ejemplo de una respuesta de tarjeta:
{
"fulfillmentMessages": [
{
"card": {
"title": "card title",
"subtitle": "card text",
"imageUri": "https://example.com/images/example.png",
"buttons": [
{
"text": "button text",
"postback": "https://example.com/path/for/end-user/to/follow"
}
]
}
}
]
}
Respuesta del Asistente de Google
A continuación, se muestra un ejemplo de una respuesta del Asistente de Google:
{
"payload": {
"google": {
"expectUserResponse": true,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "this is a Google Assistant response"
}
}
]
}
}
}
}
Contexto
A continuación, se muestra un ejemplo que establece el contexto de salida:
{
"fulfillmentMessages": [
{
"text": {
"text": [
"Text response from webhook"
]
}
}
],
"outputContexts": [
{
"name": "projects/project-id/agent/sessions/session-id/contexts/context-name",
"lifespanCount": 5,
"parameters": {
"param-name": "param-value"
}
}
]
}
Evento
A continuación, se muestra un ejemplo que invoca un evento personalizado:
{
"followupEventInput": {
"name": "event-name",
"languageCode": "en-US",
"parameters": {
"param-name": "param-value"
}
}
}
Entidad de sesión
A continuación, se muestra un ejemplo que establece una entidad de sesión:
{
"fulfillmentMessages": [
{
"text": {
"text": [
"Choose apple or orange"
]
}
}
],
"sessionEntityTypes":[
{
"name":"projects/project-id/agent/sessions/session-id/entityTypes/fruit",
"entities":[
{
"value":"APPLE_KEY",
"synonyms":[
"apple",
"green apple",
"crabapple"
]
},
{
"value":"ORANGE_KEY",
"synonyms":[
"orange"
]
}
],
"entityOverrideMode":"ENTITY_OVERRIDE_MODE_OVERRIDE"
}
]
}
Carga útil personalizada
A continuación, se muestra un ejemplo que proporciona una carga útil personalizada:
{
"fulfillmentMessages": [
{
"payload": {
"facebook": { // for Facebook Messenger integration
"attachment": {
"type": "",
"payload": {}
}
},
"slack": { // for Slack integration
"text": "",
"attachments": []
},
"richContent": [ // for Dialogflow Messenger integration
[
{
"type": "image",
"rawUrl": "https://example.com/images/logo.png",
"accessibilityText": "Example logo"
}
]
],
// custom integration payload here
}
}
]
}
Habilita y administra la entrega
Si deseas habilitar y administrar la entrega para el agente con la consola, sigue estos pasos:
- Ve a la consola de Dialogflow ES.
- Selecciona un agente.
- Selecciona Entrega en el menú de la barra lateral.
- Con el botón para activar o desactivar, selecciona Enabled (Habilitado) en el campo Webhook.
- Proporciona los detalles del servicio de webhook en el formulario. Si el webhook no requiere autenticación, deja los campos de autenticación en blanco.
- Haz clic en Guardar.
Para habilitar y administrar la entrega del agente con la API, consulta la
referencia del agente. Los métodos getFulfillment y updateFulfillment te permiten administrar la configuración de las entregas.
Si deseas habilitar la entrega para un intent con la consola, haz lo siguiente:
- En el menú de la barra lateral izquierda, selecciona Intents.
- Selecciona un intent.
- Ve a la sección Entrega.
- Activa la opción Enable webhook call for this intent.
- Haz clic en Guardar.
Si deseas habilitar la entrega para un intent con la API, consulta la
referencia de los intents y establece el
webhookState campo en WEBHOOK_STATE_ENABLED.
Errores de webhook
Si el servicio webhook experimenta un error, debería mostrar uno de los siguientes códigos de estado HTTP:
400: Solicitud incorrecta401: No autorizado403: Prohibido404: No encontrado500: Error interno del servidor503: Servicio no disponible
En cualquiera de las siguientes situaciones de error, Dialogflow responde al usuario final con la respuesta integrada configurada para el intent que coincide:
- Se excedió el tiempo de espera de respuesta
- Se recibió un código de estado de error
- La respuesta no es válida
- El servicio de webhook no está disponible
Además, si una llamada a la API de intents de detección
activa la coincidencia del intent, el campo status en la respuesta de intents de detección
contiene la información del error de webhook. Por ejemplo:
"status": {
"code": 206,
"message": "Webhook call failed. <details of the error...>"
}
Reintentos automáticos
Dialogflow ES incluye mecanismos internos que vuelven a intentar automáticamente ciertos errores de webhook para mejorar la solidez. Solo se vuelven a intentar los errores no terminales, como los 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 de webhook o anula la duplicación de solicitudes.
Usa Cloud Run Functions
Puedes usar Cloud Run Functions para la entrega de varias maneras. El editor directo de Dialogflow se integra a Cloud Run Functions. Cuando usas el editor directo para crear y editar tu código de webhook, Dialogflow establece una conexión segura con tu Cloud Function.
También puedes usar una Cloud Function que no creó el editor directo. Si la Cloud Function reside en el mismo proyecto que tu agente, tu agente puede llamar a tu webhook sin necesidad de realizar una configuración especial.
Sin embargo, debes configurar manualmente esta integración en las siguientes dos situaciones:
- Debe existir la cuenta de servicio del Agente de servicio de Dialogflow
service account
con la siguiente dirección para tu proyecto de agente:
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.
Tokens de identidad del servicio
Cuando Dialogflow llama a un webhook, proporciona un
token de identidad de Google
con la solicitud. Cualquier webhook 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.
Por ejemplo, puedes verificar el email del token de ID de la siguiente manera:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Muestras
En los siguientes ejemplos, se muestra cómo recibir un WebhookRequest y enviar un WebhookResponse. En estos ejemplos, se usan intents creados en la
guía de inicio rápido.
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.
import (
"encoding/json"
"fmt"
"log"
"net/http"
)
type intent struct {
DisplayName string `json:"displayName"`
}
type queryResult struct {
Intent intent `json:"intent"`
}
type text struct {
Text []string `json:"text"`
}
type message struct {
Text text `json:"text"`
}
// webhookRequest is used to unmarshal a WebhookRequest JSON object. Note that
// not all members need to be defined--just those that you need to process.
// As an alternative, you could use the types provided by
// the Dialogflow protocol buffers:
// https://godoc.org/google.golang.org/genproto/googleapis/cloud/dialogflow/v2#WebhookRequest
type webhookRequest struct {
Session string `json:"session"`
ResponseID string `json:"responseId"`
QueryResult queryResult `json:"queryResult"`
}
// webhookResponse is used to marshal a WebhookResponse JSON object. Note that
// not all members need to be defined--just those that you need to process.
// As an alternative, you could use the types provided by
// the Dialogflow protocol buffers:
// https://godoc.org/google.golang.org/genproto/googleapis/cloud/dialogflow/v2#WebhookResponse
type webhookResponse struct {
FulfillmentMessages []message `json:"fulfillmentMessages"`
}
// welcome creates a response for the welcome intent.
func welcome(request webhookRequest) (webhookResponse, error) {
response := webhookResponse{
FulfillmentMessages: []message{
{
Text: text{
Text: []string{"Welcome from Dialogflow Go Webhook"},
},
},
},
}
return response, nil
}
// getAgentName creates a response for the get-agent-name intent.
func getAgentName(request webhookRequest) (webhookResponse, error) {
response := webhookResponse{
FulfillmentMessages: []message{
{
Text: text{
Text: []string{"My name is Dialogflow Go Webhook"},
},
},
},
}
return response, nil
}
// handleError handles internal errors.
func handleError(w http.ResponseWriter, err error) {
w.WriteHeader(http.StatusInternalServerError)
fmt.Fprintf(w, "ERROR: %v", err)
}
// HandleWebhookRequest handles WebhookRequest and sends the WebhookResponse.
func HandleWebhookRequest(w http.ResponseWriter, r *http.Request) {
var request webhookRequest
var response webhookResponse
var err error
// Read input JSON
if err = json.NewDecoder(r.Body).Decode(&request); err != nil {
handleError(w, err)
return
}
log.Printf("Request: %+v", request)
// Call intent handler
switch intent := request.QueryResult.Intent.DisplayName; intent {
case "Default Welcome Intent":
response, err = welcome(request)
case "get-agent-name":
response, err = getAgentName(request)
default:
err = fmt.Errorf("Unknown intent: %s", intent)
}
if err != nil {
handleError(w, err)
return
}
log.Printf("Response: %+v", response)
// Send response
if err = json.NewEncoder(w).Encode(&response); err != nil {
handleError(w, err)
return
}
}
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.