Llamada a un servicio tras procesar un mensaje para 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 posmensaje 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 postprocesamiento.

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, tal vez almacene las respuestas del asistente en un sistema de gestión de contenidos independiente. Cuando el asistente entiende la entrada, la acción procesada devuelve un ID exclusivo que corresponde a una respuesta del CMS. Para llamar a un servicio que recupera una respuesta del CMS para un ID exclusivo determinado, especifique el URL de la instancia de servicio. Por ejemplo, https://example.com/get_answer.

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 post-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 posprocesamiento

Puedes decidir si se devuelve un error en el paso de postprocesamiento 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 postprocesado es útil pero no esencial, considere esta opción.

• Devolver un error al cliente si falla la llamada al webhook : Si el postprocesamiento es crítico después de que el asistente envíe una respuesta, 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 la respuesta.

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 sólo cuando su asistente procesa un mensaje y una respuesta está lista para ser devuelta al canal.

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 del webhook post-mensaje de petición para que tu código externo pueda procesarlo.

La carga útil contiene el cuerpo de la respuesta que devuelve su asistente para la llamada a la API de la versión 2 /message, con y sin estado. El nombre del evento message_processed indica que el webhook post-mensaje genera la petición. Para obtener más información sobre el cuerpo de la solicitud del mensaje, consulta la referencia de la API.

El siguiente ejemplo muestra cómo se formatea el cuerpo de una solicitud sencilla:

{
 "event": {
    "name": "message_processed"
},
"options": {},
"payload": {
    "output": {
        "intents": [
            {
                "intent": "General_Greetings",
                "confidence": 1
            }
        ],
        "entities": [],
        "generic": [
            {
                "response_type": "text",
                "text": "Hello. Good evening"
            }
        ]
    },
    "user_id": "test user",
    "context": {
        "global": {
            "system": {
                "user_id": "test user",
                "turn_count": 11
            },
            "session_id": "sxxx"
        },
        "skills": {
            "actions skill": {
                "user_defined": {
                    "var": "anthony"
                },
                "system": {
                    "state": "nnn"
                }
            }
        }
    }
}

Ejemplo 1

Este ejemplo muestra cómo añadir y'all al final de cada respuesta del asistente.

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

• URL: https://your-webhook-url/

• Nombre de cabecera: Content-Type

• Valor de cabecera: application/json

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

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

function main(params) {
  console.log(JSON.stringify(params))
  if (params.payload.output.generic[0].text !== '') {
      //Get the length of the input text
        var length = params.payload.output.generic[0].text.length;
        //create a substring that removes the last character from the input string, which is typically punctuation.
        var revision = params.payload.output.generic[0].text.substring(0,length-1);
        const response = {
            body : {
                payload : {
                    output : {
                        generic : [
                              {
                                  //Replace the input text with your shortened revision and append y'all to it.
                                "response_type": "text",
                                "text": revision + ', ' + 'y\'all.'
                              }
                        ],
                    },
                },
            },
        };
        return response;
  }
  else {
    return { 
        body : params
    }
  }
}

Ejemplo 2

Este ejemplo muestra cómo traducir la respuesta de un mensaje al idioma del cliente. Sólo funciona si realiza los pasos del Ejemplo 2 para definir un webhook previo al mensaje que traduzca el mensaje original al inglés.

Defina una secuencia de acciones web en IBM Cloud Functions. La primera acción de la secuencia comprueba el idioma del texto entrante original, que almacenaste en una variable de contexto llamada original_input en el código del webhook previo al mensaje. La segunda acción de la secuencia traduce el texto de respuesta del diálogo del inglés al idioma original utilizado por el cliente.

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

• URL: https://your-webhook-url/

• 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.output.generic[0].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': 'nnnn'
       },
  headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.context.skills['actions skill'].user_defined.original_input
  ],
  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 param
}
};

La segunda 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.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'
        },
    body: { 
        text: [ 
            params.payload.output.generic[0].text
            ],
            target: params.payload.context.skills["actions skill"].user_defined.language
    },
    json: true 
    };
      return rp(options)
      .then(res => {
          params.payload.context.skills["actions skill"].user_defined["original_output"] = params.payload.output.generic[0].text;
          params.payload.output.generic[0].text = res.translations[0].translation;
          return {
            body : params
          }
  })
  }
  return { 
    body : params
  }
};

Eliminación del webhook

Si no desea procesar respuestas de mensajes 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 Configuración del entorno, haga clic en Webhook post-mensaje.

4. Efectúe uno de los pasos siguientes:

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

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