--- title: "Ganchos" url: https://docs.catalyst.zoho.com/es/convokraft/sdk/js/hooks/ description: "Aprende sobre el paquete JS SDK proporcionado por el servicio Catalyst ConvoKraft que tiene la capacidad de integrar potentes asistentes de chatbot en tu aplicación de Catalyst." last_updated: 2026-03-30T08:10:30Z service: ConvoKraft type: general --- # Hooks Los hooks de ConvoKraft son funciones que pueden ser configuradas por los desarrolladores en el ámbito global de una aplicación web de Catalyst y pueden ser accedidas usando el objeto ConvoKraft. El ConvoKraft JS SDK proporciona los siguientes hooks: * `handleResponse` * `handleMissed` * `handleError` * `minimizeChat` * `didConnect` * `setOnBoarding` * `setOnBoardingSentences` * `setClientSessionData` * `handleUpload` * `handleWelcome` ### handleResponse Basándote en la respuesta proporcionada por ConvoKraft para cualquier acción, puedes manejar los datos y personalizar la representación visual de la respuesta según tus requisitos específicos. La respuesta original enviada será enviada en la clave `data` de una Deluge function desde tu aplicación web. Para personalizar la respuesta, necesitas pasar el valor de data al siguiente hook junto con el elemento HTML, dentro del cual la aplicación web puede renderizar la respuesta original de ConvoKraft. **Sintaxis** ```javascript convokraft.handleResponse=function(actionName,data,element,responseHandled,fromHistory,fromPagination) { //Ingresa la lógica aquí return true; } ``` La siguiente tabla proporciona detalles sobre los diversos elementos de la función:
Elemento Descripción
`actionName` El namespace de la acción invocada.
`data` Contiene los datos personalizados que se envían desde Deluge al hook.
`element` Contiene el elemento de respuesta personalizado de ConvoKraft que se mostrará en la ventana de chat.
`responseHandled` Esta es una función de callback obligatoria, que ayuda al bot a saber que las operaciones DOM están completas y puede hacer scroll del div del chat hacia arriba.
`fromHistory` Esta clave contiene un valor booleano que representa si el mensaje actual que se está construyendo es de la sesión actual o de sesiones anteriores.
`fromPagination` Esta clave contiene un valor booleano que representa si el mensaje actual que se está construyendo es un mensaje después de una llamada de paginación. Si es true, no es aconsejable llamar a `responseHandled()`, para que los mensajes no se desplacen completamente hacia abajo.
**Código de ejemplo** ```javascript convokraft.handleResponse = function(actionName,data,element,responseHandled,fromHistory,fromPagination) { if(actionName=="schedule_event") { element.innerHTML="This is a test function from "+data.name; element.style.padding="10px"; responseHandled(); return false; //Renderiza la respuesta construida anteriormente } return true; //Renderiza la respuesta original de ConvoKraft } ``` ### handleMissed Si el mensaje del usuario no coincide con ninguna de las acciones configuradas de tu bot, y en ese caso si has definido el hook `convokraft.handleMissed()` en el ámbito global de tu aplicación web, entonces ConvoKraft mostrará la respuesta personalizada renderizada a través de este hook. **Sintaxis** ```javascript convokraft.handleMissed = function(element, responseHandled, fromHistory, fromPagination) { //Ingresa la lógica del elemento que se renderizará como respuesta de convokraft } ``` La siguiente tabla describe los elementos de la sintaxis y sus descripciones:
Elemento Descripción
`element` Contiene el elemento de respuesta personalizado de ConvoKraft que se mostrará en la ventana de chat.
`responseHandled` Esta es una función de callback obligatoria, que ayuda al bot a saber que las operaciones DOM están completas y puede hacer scroll del div del chat hacia arriba.
`fromHistory` Esta clave contiene un valor booleano que representa si el mensaje actual que se está construyendo es de la sesión actual o de sesiones anteriores.
`fromPagination` Esta clave contiene un valor booleano que representa si el mensaje actual que se está construyendo es un mensaje después de una llamada de paginación. Si es `true`, no es aconsejable llamar a `responseHandled()`, para que los mensajes no se desplacen completamente hacia abajo.
**Código de ejemplo** ```javascript convokraft.handleMissed= function(element,responseHandled,fromHistory){ element.innerHTML = "
Sorry! Not found!
"; responseHandled(); return false; } ``` ### handleError Si ocurre algún error de API mientras se ejecuta una acción, puedes usar este hook para mostrar una respuesta de error personalizada definiendo `convokraft.handleError` en el ámbito global de tu aplicación web de Catalyst. **Sintaxis** ```javascript convokraft.handleError = function(element, responseHandled, fromHistory, fromPagination) { //Ingresa la lógica para personalizar el mensaje de error } ``` La siguiente tabla describe los elementos de la sintaxis y sus descripciones:
Elemento Descripción
`element` Contiene el elemento de respuesta personalizado de ConvoKraft que se mostrará en la ventana de chat.
`responseHandled` Esta es una función de callback obligatoria, que ayuda al bot a saber que las operaciones DOM están completas y puede hacer scroll del div del chat hacia arriba.
`fromHistory` Esta clave contiene un valor booleano que representa si el mensaje actual que se está construyendo es de la sesión actual o de sesiones anteriores.
`fromPagination` Esta clave contiene un valor booleano que representa si el mensaje actual que se está construyendo es un mensaje después de una llamada de paginación. Si es `true `, no es aconsejable llamar a `responseHandled()`, para que los mensajes no se desplacen completamente hacia abajo.
**Código de ejemplo** ```javascript convokraft.handleError= function(element,responseHandled){ if(typeof data !== "undefined"){ messageString = data.data.code; } else{ messageString = "Api Error!"; } element.innerHTML = "
Sorry! "+messageString+"
"; responseHandled(); } ``` ### minimizeChat Este hook permite al usuario minimizar o maximizar la ventana de chat cuando se hace clic en su encabezado. **Sintaxis** ```javascript convokraft.minimizeChat=function() { //obtener tu div de chat y aplicar animación de minimizar y estilos según necesites } ``` **Código de ejemplo** ```javascript convokraft.minimizeChat=function() { if(document.getElementById("zdivid").style.marginBottom=="-400px"||document.getElementById("zdivid").style.marginBottom=="") { document.getElementById("zdivid").style.marginBottom="-0px"; } else { document.getElementById("zdivid").style.marginBottom="-400px"; } } ``` ### didConnect Este hook se usa para notificar a la aplicación web de Catalyst que el chat se ha cargado completamente. **Sintaxis** ```javascript convokraft.didConnect=function() { //Ingresa la lógica aquí } ``` **Código de ejemplo** ```javascript convokraft.didConnect=function() { var loadingDiv=document.getElementById("loadingDiv"); if(loadingDiv) { loadingDiv.style.display='none'; } } ``` ### setOnBoarding Si no hay historial de chat, entonces la pantalla de bienvenida se mostrará por defecto. Este hook puede definirse en el ámbito global de tu aplicación web para personalizar la pantalla de bienvenida del bot de ConvoKraft según tus requisitos. **Sintaxis** ```javascript convokraft.setOnBoarding=function(element,sentences,placeholders) { //construir HTML y estilos según tu necesidad y agregarlo al elemento } ``` La siguiente tabla explica los elementos de la sintaxis y sus descripciones:
Elemento Descripción
`element` Contiene el elemento HTML que necesita ser personalizado.
`sentences` Contiene las oraciones de ejemplo de esa acción particular.
`placeholders` Es un array de strings que puede usarse para contener diferentes parámetros para las oraciones mostradas en la pantalla de bienvenida
**Código de ejemplo** ```javascript convokraft.setOnBoarding=function(element,sentences,placeholders) { var html="
This is a custom onboarding screen by client app and here are the list of sentences:
"; element.innerHTML=html; element.style.padding="10px"; } ``` ### setOnBoardingSentences Este hook se usa para personalizar las oraciones de bienvenida o las sugerencias de acciones que aparecen cuando abres una ventana de chat de ConvoKraft. Por defecto, la ventana de chat muestra las sugerencias basadas en las oraciones de ejemplo configuradas de las acciones de ConvoKraft. Se puede pasar un array de objetos en formato JSON como argumentos a este hook como se lista a continuación. También ten en cuenta que con la ayuda de las oraciones en el JSON, se pueden establecer y retornar diferentes valores para los placeholders. ```javascript [ { "id": "1", "sentence": "Apply leave for {{fromdate}} and {{todate}}", "actual_sentence": "Apply leave for today and tomorrow" }, { "id": "2", "sentence": "What is the {{property}} of {{country}}?", "actual_sentence": "What is the capital of India?" } ] //Filtrar o modificar las oraciones que se mostrarán en la pantalla de incorporación ``` **Sintaxis** ```javascript convokraft.setOnBoardingSentences=function(sentences) { //definir HTML y estilos según tu necesidad y agregarlo al elemento } ``` **Código de ejemplo** ```javascript convokraft.setOnBoardingSentences=function(sentences) { sentences.splice(0,8); return sentences; } ``` > **Nota:** * Este hook se considerará solo cuando el hook `setOnBoarding` no esté aplicado. * Si quieres oraciones personalizadas en el hook `setOnBoarding`, aplica el mismo proceso para las oraciones en el hook `setOnBoarding`. ### setClientSessionData Este hook se usa para obtener los datos de sesión del cliente personalizado de tu aplicación web de Catalyst. Asegúrate de definirlo en el ámbito global de tu aplicación web de Catalyst para que ConvoKraft pueda acceder a él. **Sintaxis** ```javascript convokraft.setClientSessionData=function() { //Devolver un objeto JSON } ``` **Código de ejemplo** ```javascript convokraft.setClientSessionData=function() { return { portal_name: "zylker", ui_version: "2.0" } } ``` > **Nota:** * Asegúrate de retornar los datos de sesión como un objeto JSON. * Cuando usas una Deluge function, los datos JSON que se retornan desde este handle pueden obtenerse usando `sessionData.set("client_data").` ### handleUpload Este hook se usa para definir las operaciones a realizar después de cargar un archivo. Si la plataforma de desarrollo elegida es Deluge o Function, entonces el archivo se cargará en el entorno en la nube de Catalyst. En caso de Webhooks, necesitarás definir tu propia ruta de archivo en el atributo `file`. Puedes configurar los mensajes respectivos en los argumentos de callback `onSucces` y `onFailure`, según tus requisitos específicos. **Sintaxis** ```javascript convokraft.handleUpload = function(input){ //haz lo que desees con el elemento que se renderizará como respuesta de convokraft } ``` Los siguientes atributos son soportados para este hook:
Nombre del atributo Uso
`sessionId` El ID de la sesión de transcript actual.
`param` La información del param del prompt actual como nombre del param, tipo y mensaje del prompt.
`file` El objeto de archivo proporcionado por el usuario.
`action` El namespace de la acción de la conversación actual.
`bot` El namespace del bot de la conversación actual.
`onSuccess` El callback obligatorio que acepta el ID del archivo como entrada.
`onProgressChange` El callback obligatorio que acepta el porcentaje de carga calculado como parámetro. Esto debe llamarse cada vez que el porcentaje de carga cambie. Si la carga está completa, establece el porcentaje a 100 y un mensaje para mostrar el estado de éxito como `onProgressChange(100,"File upload completed");`
`onFailure` El callback obligatorio que acepta una entrada de string con un mensaje indicando la razón del fallo de la carga.
**Código de ejemplo** ```javascript convokraft.handleUpload=function(uploadObject){ let percentage = 20; let onSuccess = uploadObject.onSuccess; let onFailure = uploadObject.onFailure; var percentageInterval = setInterval(function() { if(percentage === 100){ clearInterval(percerntageInterval); uploadObject.updateProgress(100,"Your file is being processed. Please wait..."); setTimeout(function() { if(zia.fileUploadCount > 1){ onSuccess((Date.now()).toString()); } else{ onFailure("Your file is over 2MB. Please upload a file of less size."); } }, 5000); return; } percentage+=20; uploadObject.onProgressChange(percentage); }, 500); } ``` ### handleWelcome Este hook se usa para modificar el mensaje de bienvenida (el primer mensaje mostrado en la sesión de chat). Este hook puede usarse cuando necesitas personalizar solo la UI. Si necesitas que se ejecute una lógica de backend para mostrar el mensaje de bienvenida, entonces usa la función welcome message handler. **Sintaxis** ```javascript convokraft.handleWelcome = function(config){ //haz lo que desees con el elemento que se renderizará como respuesta de convokraft } ``` **Código de ejemplo** ```javascript convokraft.handleWelcome = function(config) { config.element.innerHTML = `Hello Guest! Here are few things I can do for you. <div class='suggestion'>Raise a ticket</div> <div class='suggestion'>List my inventory and assets</div>`; } ```