Llamada a un servicio antes de procesar un mensaje en IBM Cloud Pak for Data

Configuración de webhook

Para añadir los detalles de webhook, complete los pasos siguientes:

1. En el panel de navegación, haga clic en Entornos y abra el entorno en el que desea configurar el webhook.

2. Haz clic en el icono para abrir la configuración del entorno.

3. Establezca el conmutador Webhook de premensaje en Habilitado.

4. En el evento Sincrónico, seleccione una de las siguientes opciones:

   • Continuar procesando la entrada del usuario sin actualizar el webhook si hay un error.

   • Devuelve un error al cliente si falla la llamada al webhook.

Para obtener más información, consulte Configuración de la gestión de errores de webhook para el preprocesamiento.

1. En el campo URL, añada el URL de la aplicación externa a la que desea enviar llamadas de solicitud POST de HTTP.

Por ejemplo, puede escribir una acción web Cloud Functions que compruebe si un mensaje está en un idioma distinto del inglés y lo envíe al servicio Language Translator para que lo convierta al inglés. Especifique el URL para la acción web, como en este ejemplo:

    https://us-south.functions.cloud.ibm.com/api/v1/web/my_org_dev/default/translateToEnglish.json

Debe especificar un URL que utilice el protocolo SSL, es decir, un URL que empiece por https.

1. Para configurar la autenticación de los webhooks pre-mensaje, haga clic en Editar autenticación. Para obtener instrucciones detalladas, consulte Definición del método de autenticación para webhooks pre-mensaje y post-mensaje.

2. En el campo Tiempo de espera, especifique el tiempo, en segundos, que desea que el asistente espere una respuesta del webhook antes de devolver un error. La duración del tiempo de espera no puede de menos de 1 segundo ni de más de 30 segundos.

3. En la sección Cabeceras, haga clic en Añadir cabecera + para añadir las cabeceras que desee pasar al servicio, de una en una.

Si la aplicación externa a la que llamas devuelve una respuesta, es posible que pueda enviar una respuesta en diferentes formatos. El webhook requiere que la respuesta esté formateada en JSON. La siguiente tabla ilustra cómo añadir una cabecera para indicar que desea que el valor resultante se devuelva en formato JSON.

1. Después de guardar el valor de la cabecera, la cadena se sustituye por asteriscos y no se puede volver a ver.

2. Los detalles de su webhook se guardan de forma automática.

Configuración del manejo de errores de webhooks para el preprocesamiento

Puedes decidir si se devuelve un error en el paso de preprocesamiento si falla la llamada al webhook. Tiene dos opciones:

• Continúa procesando la entrada del usuario sin actualizar el webhook si hay un error : El asistente ignora los errores y procesa el mensaje sin el resultado del webhook. Si el preprocesamiento es útil pero no esencial, considere esta opción.

• Devolver un error al cliente si falla la llamada al webhook : Si el preprocesamiento es crítico antes de que el asistente procese un mensaje, seleccione esta opción.

Importante: Cuando se activa la opción «Devolver un error al cliente si falla la llamada al webhook», todo se detiene hasta que la fase de posprocesamiento se haya completado correctamente.

Pruebe periódicamente el proceso externo para identificar posibles fallos. Si es necesario, ajuste esta configuración para evitar interrupciones en el procesamiento de mensajes.

Prueba del webhook

Importante: Realiza pruebas exhaustivas de tu webhook antes de habilitarlo para un asistente que se utilice en un entorno de producción.

El webhook se activa cuando se envía un mensaje al asistente para que se procese.

Resolución de problemas del webhook

Los códigos de error siguientes pueden ayudarle a localizar la causa de los problemas que se puede encontrar. Si tiene una integración de chat web, por ejemplo, sabrá que su webhook tiene un problema si cada mensaje de prueba que envía devuelve un mensaje como There is an error with the message you just sent, but feel free to ask me something else. Si aparece este mensaje, utilice una herramienta de API REST, como cURL, para enviar una solicitud de API /message de prueba, de modo que pueda ver el código de error y el mensaje completo que se devuelve.

Cuerpo de solicitud de ejemplo

Es útil conocer el formato del cuerpo de la petición del webhook pre-mensaje para que tu código externo pueda procesarlo.

La carga útil contiene el cuerpo de la solicitud de la versión 2 de la API /message, con o sin estado. El nombre del evento message_received indica que la solicitud es generada por el webhook pre-mensaje. Para obtener más información sobre el cuerpo de la solicitud del mensaje, consulta la referencia de la API.

{
  "payload" : { Copy of request body sent to /message }
  "event": {
      "name": "message_received"
   }
}

Omitir el procesamiento secundario

Las mejoras introducidas en los webhooks previos al mensaje permiten que IBM Cloud Pak for Data omita el procesamiento del mensaje y devuelva directamente la respuesta desde el webhook. Esta funcionalidad se activa configurando el x-watson-assistant-webhook-return encabezado en la respuesta « HTTP » del webhook.

Cuerpo de respuesta

El servicio que recibe la solicitud POST del webhook debe devolver un objeto JSON (Accept: application/json).

El cuerpo de respuesta debe tener la estructura siguiente:

{
  "payload": {
    ...
  }
}

La respuesta payload debe incluir el payload del cuerpo de la solicitud. Su código puede modificar los valores de las propiedades o modificar las variables de contexto, pero la carga útil del mensaje devuelto debe seguir el esquema del método message . Para obtener más información, consulta la referencia de la API.

Ejemplo 1

Este ejemplo muestra cómo comprobar el idioma del texto de entrada y añadir la información del idioma a la cadena de texto de entrada.

En la página de configuración del webhook pre-mensaje, se especifican los siguientes valores:

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/check_language

• Nombre de cabecera: Content-Type

• Valor de cabecera: application/json

El webhook pre-mensaje llama a una acción web IBM Cloud Functions de nombre check_language.

El código node.js de la acción web check_language tiene el aspecto siguiente.

let rp = require("request-promise");

function main(params) {
console.log(JSON.stringify(params))
if (params.payload.input.text !== '') {
  // Send a request to the Watson Language Translator service to check the language of the input text.
const options = { method: 'POST',
  url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/identify?version=2018-05-01',
  auth: {
           'username': 'apikey',
           'password': 'nnn'
       },
headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.input.text
  ],
  json: true,
};
     return rp(options)
    .then(res => {
        params.payload.context.skills["actions skill"].user_defined["language"] = res.languages[0].language;
        console.log(JSON.stringify(params))
        //Append "in" plus "the language code" to the input text, surrounded by parentheses.
        const response = {
            body : {
                payload : {
                    input : {
                        text : params.payload.input.text + ' ' + '(in ' + res.languages[0].language + ')'
                    },
                },
            },
        };
        return response;
})
}
return { 
    body : params
}
};

Para probar el webhook, pulse Vista previa. Envíe el texto Buenos días. El asistente probablemente no puede entender la entrada, y devuelve la respuesta de su nodo Anything else. Sin embargo, si vas a la página Analizar de tu asistente y abres Conversaciones, podrás ver lo que se ha enviado. Revise la conversación de usuario más reciente. El registro muestra que la entrada del usuario es Buenos días (in es). El es entre paréntesis representa el código de idioma para el español, por lo que el webhook funcionó y reconoció que el texto enviado era una frase en español.

Ejemplo 2

Este ejemplo muestra cómo comprobar el idioma del mensaje entrante y, si no es el inglés, traducirlo al inglés antes de enviarlo al asistente.

Defina una secuencia de acciones web en IBM Cloud Functions. La primera acción de la secuencia comprueba el idioma del texto entrante. La segunda acción de la secuencia traduce el texto de su idioma original al inglés.

En la página de configuración del webhook pre-mensaje, se especifican los siguientes valores:

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/translation_sequence

• Nombre de cabecera: Content-Type

• Valor de cabecera: application/json

El código node.js de la primera acción web de la secuencia tiene el aspecto siguiente:

let rp = require("request-promise");

function main(params) {
console.log(JSON.stringify(params))
if (params.payload.input.text !== '') {
const options = { method: 'POST',
  url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/identify?version=2018-05-01',
  auth: {
           'username': 'apikey',
           'password': 'nnn'
       },
headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.input.text
  ],
  json: true,
};
     return rp(options)
    .then(res => {
      //Set the language property of the incoming message to the language that was identified by Watson Language Translator. 
        params.payload.context.skills["actions skill"].user_defined["language"] = res.languages[0].language;
        console.log(JSON.stringify(params))
        return params;
})
}
else {
    params.payload.context.skills["actions skill"].user_defined["language"] = 'none'
    return params
}
};

La segunda acción web de la secuencia envía el texto al servicio Watson Language Translator para traducir el texto de entrada del idioma identificado en la acción web anterior al inglés. A continuación, la serie traducida se envía al asistente en lugar del texto original.

El código node.js de la segunda acción de la secuencia tiene el aspecto siguiente:

let rp = require("request-promise");

function main(params) {
console.log(JSON.stringify(params))
//If the the incoming message is not null and is not English, translate it.
if ((params.payload.context.skills["actions skill"].user_defined.language !== 'en') && (params.payload.context.skills["actions skill"].user_defined.language !== 'none')) {
const options = { method: 'POST',
  url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/translate?version=2018-05-01',
  auth: {
           'username': 'apikey',
           'password': 'nnn'
       },
  headers: {
    "Content-Type":"application/json"
  },
       //The body includes the parameters that are required by the Language Translator service, the text to translate and the target language to translate it into.
  body: { 
      text: [ 
          params.payload.input.text
          ],
          target: 'en' 
  },
  json: true 
};
     return rp(options)
    .then(res => {
        params.payload.context.skills["actions skill"].user_defined["original_input"] = params.payload.input.text;
        const response = {
            body : {
                payload : {
                    "context" : params.payload.context,
                    "input" : {
                        "text" : res.translations[0].translation,
                        "options" : {
                            "export" : true
                            }
                    },
                },
            },
        };
    return response
})
}
return { 
    body : params
    }
};

Al probar el webhook en el panel de vista previa, puede enviar Buenos días y el asistente responderá como si dijese Good morning en inglés. De hecho, cuando consulta la página Analizar de su asistente y abre Conversaciones, el registro muestra que la entrada del usuario fue Good morning.

Puede añadir un webhook post-mensaje para traducir la respuesta del mensaje al idioma del cliente antes de que se muestre. Para más información, véase el Ejemplo 2.

Ejemplo 3

Este ejemplo muestra cómo redactar una respuesta de webhook para que IBM Cloud Pak for Data omita el procesamiento del mensaje y devuelva directamente la respuesta del webhook.

function main(params) {
  // Your custom logic to determine the response
  let responseText = "This response is directly from the pre-message webhook.";

  const response = {
    headers: {
      "X-Watson-Assistant-Webhook-Return": "true"
    },
    body: {
      output: {
        generic: [
          {
            response_type: "text",
            text: responseText
          }
        ]
      }
    }
  };

  return response;
}

Eliminación del webhook

Si no desea preprocesar la entrada del cliente con un webhook, complete los siguientes pasos:

1. En su asistente, vaya a Entornos y abra el entorno en el que desea eliminar el webhook.

2. Haz clic en el icono para abrir la configuración del entorno.

3. En la página de configuración de Entorno, haz clic en Pre-message webhook.

4. Efectúe uno de los pasos siguientes:

   • Para dejar de llamar a un webhook para procesar cada mensaje entrante, ponga el interruptor Pre-mensaje webhook en Desactivado.

   • Para cambiar el webhook que desea llamar, haga clic en Eliminar webhook.