# Grupos y creación de planes Source: https://woku.app/docs/action-plans/create-plan Cómo configurar grupos de encargados y cómo woku genera borradores de planes de acción a partir del feedback woku escribe los borradores de los planes de acción por ti: analiza el feedback que recibe tu empresa y, cuando un grupo acumula suficientes oportunidades de mejora, redacta un plan con evidencia, título, resumen, objetivo, impacto esperado y tareas concretas para que el equipo lo revise y lo apruebe. La unidad de configuración es el **grupo de encargados**: define qué feedback escucha, quiénes lo revisan y cuándo woku debe crear un borrador. ## Crear un grupo En **Planes de acción**, presiona **Crear grupo** y completa las cuatro secciones del formulario. Crear, editar, activar, desactivar o eliminar grupos requiere ser administrador o dueño de la empresa. Cualquier miembro puede ver los grupos y sus planes. ### Información del grupo * **Nombre**: identifica al grupo, por ejemplo *Logística Ecommerce*. * **Descripción** (opcional): contexto para que el equipo entienda qué revisa este grupo. ### Qué feedback escucha Las condiciones se arman con los **trackers** de tu empresa, en filas del tipo **Cuando** un tracker **es** un valor. Por ejemplo: *Cuando Sucursal es Santiago Centro*. * Cada condición usa el operador **es igual a** (un valor exacto) o **es cualquier valor** (todos los valores del tracker, sin escribir uno por uno). Para escuchar varios trackers completos, agrega una condición **es cualquier valor** por cada tracker, unidas con **O si**. * Las condiciones se combinan con **Y además** (deben cumplirse ambas) u **O si** (basta con una). * Un grupo necesita al menos una condición. Sin condiciones no recibe ningún feedback. Una vista previa en el mismo formulario muestra en lenguaje natural qué feedback escuchará el grupo con las condiciones elegidas. ### Equipo y roles Selecciona a las personas del grupo y asigna a cada una un rol: * **Administrador**: puede revisar, aprobar, cancelar y enviar planes. * **Encargado**: puede revisar planes y participar en el chat con IA. Todo grupo necesita al menos un Administrador y al menos un Encargado. ### Regla de generación Define el umbral de la regla: *woku creará un borrador cuando este grupo acumule N oportunidades nuevas*. El valor por defecto es 300 y el mínimo es 1. Además de las oportunidades, woku considera los reconocimientos relacionados para entregar mejor contexto en el plan. ### Activar y desactivar Desde el detalle del grupo puedes **desactivarlo**: woku deja de generar planes para ese grupo y puedes reactivarlo cuando quieras. **Eliminar grupo** borra el grupo y su configuración de forma definitiva. ## Cómo se genera un borrador 1. Cada comentario nuevo clasificado como **oportunidad de mejora** que coincide con las condiciones del grupo suma a su contador de **oportunidades acumuladas**. 2. Cuando el acumulado desde el último plan alcanza el umbral, woku genera un **borrador** y el contador del grupo vuelve a cero. 3. El borrador congela una **ventana de evidencia**: el rango de fechas, las condiciones vigentes, los conteos de oportunidades, reconocimientos y comentarios analizados, y hasta seis citas textuales de clientes. Sobre esa evidencia, las métricas y los patrones detectados los calcula el motor de forma determinística. La IA solo redacta el título, el resumen, el objetivo, el impacto esperado, las tareas y los nombres de los patrones. La **prioridad** del plan (Alta, Media o Baja) la calcula el sistema, nunca la IA. > [!NOTE] > > **Seguimiento con el agente de IA.** Cuando el agente de seguimiento > conversó con clientes que dejaron una oportunidad de mejora dentro de la > ventana, el borrador recibe los resúmenes de esas conversaciones cerradas, > hasta 15, como contexto cualitativo para precisar causas y tareas. No cuentan > como comentarios nuevos ni cambian conteos, umbral o prioridad, y sus cifras > no se citan en el plan. El plan muestra cuántas conversaciones lo > respaldan y, al actualizar el borrador, suma las que se cerraron después. > [!NOTE] > > Si el grupo ya tiene un borrador abierto cuando vuelve a alcanzar el > umbral, woku no crea un plan duplicado: **extiende** el borrador > existente con la nueva evidencia y vuelve a avisar al equipo. ## Avisos al equipo Cuando se genera o se extiende un borrador, cada miembro del grupo recibe: * Una **notificación dentro de la aplicación**. * Un **correo** en español con el asunto *Nuevo borrador de plan para \{grupo}* y un enlace directo al plan. # Revisar y aprobar planes Source: https://woku.app/docs/action-plans/kanban Cómo revisar los planes de acción de un grupo, ajustarlos con el agente de IA, aprobarlos y cerrar su ciclo Los planes de acción se trabajan por **grupos de encargados**. Cada plan nace como borrador, el grupo lo revisa y lo ajusta (a mano o conversando con el agente de IA) y un administrador lo aprueba para cerrar el ciclo. ## Inicio del módulo Al abrir **Planes de acción** ves un panel resumen organizado por grupos, con buscador, filtros por tracker y una barra de periodo (**Día**, **Semana**, **Mes**, **Año** o **Histórico**). Las tarjetas del resumen muestran el grupo con más planes enviados y los totales del periodo: planes creados, por revisar, aprobados y enviados. ## Detalle de un grupo Al entrar a un grupo ves la tabla de sus planes, filtrable por **estado**, **fuente** y **prioridad**, con buscador por título o resumen. Arriba se muestran las métricas de comentarios analizados del periodo, separadas en **oportunidades** y **reconocimientos**. ## Detalle de un plan La vista de un plan tiene el **chat del grupo** a la izquierda y dos pestañas a la derecha: **Plan actual** e **Historial**. Las acciones disponibles dependen del estado: * En **borrador**: **Cancelar** y **Aprobar**. * En **aprobado**: **Editar** y **Enviar** (a una herramienta externa o a la gestión interna de woku). * En **error de envío**: **Editar** y **Reenviar**. * En **progreso** (gestión interna): el **tablero de tareas** y **Cerrar plan**. * **Completado**: vista de solo lectura con **Reabrir**. La pestaña **Plan actual** muestra el resumen, el objetivo y el impacto esperado, junto con tres métricas: **Oportunidades**, **Reconocimientos** y **Comentarios analizados**. Además incluye: * **Citas de clientes** con el botón **Ver comentarios**, que abre un panel para recorrer los comentarios reales de la evidencia del plan, filtrable por fuente y por tipo. Un comentario cuya respuesta tuvo una conversación de seguimiento permite abrirla desde el mismo panel. * **Patrones** detectados, con su cantidad de menciones. * Las **condiciones** del grupo con las que se congeló la evidencia. * Las **fuentes analizadas** y la **lista de tareas** del plan. Mientras el plan está en borrador, cualquier miembro del grupo puede editar el texto de una tarea directamente en la lista (máximo 160 caracteres). En un plan en gestión interna, además, los miembros mueven las tareas por el tablero, las asignan a personas del grupo y agregan o quitan tareas. ## Chat con Woku El chat es una conversación grupal entre los miembros y el agente de IA. Los mensajes se publican al instante y el agente responde de forma asíncrona: su respuesta llega en tiempo real a todos los participantes. El agente consulta datos reales del alcance congelado del plan, por fuente (Wokus, NPS, CSAT o CES). Cuando le pides un cambio y lo confirmas, lo aplica directamente al plan: título, resumen, objetivo, impacto, prioridad o la lista de tareas. Cada cambio queda registrado en el historial. > [!NOTE] > > El agente solo puede modificar planes en borrador. Cuando el plan está > aprobado el chat se bloquea; presiona **Editar** para volverlo a > borrador y seguir modificándolo. ## Estados Un plan pasa por estos estados: * **Por revisar**: borrador en revisión del grupo. * **Aprobado**: listo para enviarse. * **Enviado**: creado en la herramienta externa. * **En progreso**: en gestión interna dentro de woku. * **Completado**: gestión interna cerrada. * **Cancelado**: descartado. * **Error de envío**: el envío falló y se puede reintentar. Aprobar, cancelar, reabrir, cerrar y reanudar un plan son acciones de los **administradores del grupo**. Reabrir vuelve un plan aprobado o con error de envío al estado de borrador; reanudar vuelve un plan completado al estado en progreso. ## Cierre del plan Al aprobar un plan, un administrador elige el destino: * **Herramienta externa**: cuando la empresa tiene conectada una herramienta de gestión de trabajo, el plan aprobado se envía a esa herramienta. Los planes enviados abren una vista de solo lectura con un botón para abrirlo en la herramienta de destino, sus métricas y las tareas enviadas. * **Gestión en woku**: el plan se trabaja dentro de la plataforma. Pasa a **En progreso** y el grupo gestiona sus tareas en un **tablero** con columnas **Por hacer**, **En progreso** y **Hecho**, con responsables por tarea. Cuando el trabajo termina, un administrador **cierra** el plan y queda **Completado**; puede **reanudarlo** si hace falta. Un plan también cierra su ciclo cuando se cancela para descartarlo. ## Historial La pestaña **Historial** muestra la línea de tiempo del plan: generación por IA, evidencia agregada, tareas editadas, secciones actualizadas, aprobación, cancelación, reapertura, envío y errores de envío, inicio de la gestión interna y cierre del plan. # Actualizar un grupo de planes de acción Source: https://woku.app/docs/api-reference/v1--action-plan-groups/actualizar-un-grupo-de-planes-de-acción /openapi-v1.es.json patch /v1/action-plan-groups/{id} # Crear un grupo de planes de acción Source: https://woku.app/docs/api-reference/v1--action-plan-groups/crear-un-grupo-de-planes-de-acción /openapi-v1.es.json post /v1/action-plan-groups # Eliminar un grupo de planes de acción Source: https://woku.app/docs/api-reference/v1--action-plan-groups/eliminar-un-grupo-de-planes-de-acción /openapi-v1.es.json delete /v1/action-plan-groups/{id} # Habilitar o deshabilitar un grupo de planes de acción Source: https://woku.app/docs/api-reference/v1--action-plan-groups/habilitar-o-deshabilitar-un-grupo-de-planes-de-acción /openapi-v1.es.json patch /v1/action-plan-groups/{id}/enabled # Listar los grupos de planes de acción de la empresa que hace la llamada Source: https://woku.app/docs/api-reference/v1--action-plan-groups/listar-los-grupos-de-planes-de-acción-de-la-empresa-que-hace-la-llamada /openapi-v1.es.json get /v1/action-plan-groups # Obtener un grupo de planes de acción Source: https://woku.app/docs/api-reference/v1--action-plan-groups/obtener-un-grupo-de-planes-de-acción /openapi-v1.es.json get /v1/action-plan-groups/{id} # Agregar una tarea (borrador o plan gestionado) Source: https://woku.app/docs/api-reference/v1--action-plans/agregar-una-tarea-borrador-o-plan-gestionado /openapi-v1.es.json post /v1/action-plans/{id}/tasks # Aprobar un plan borrador Source: https://woku.app/docs/api-reference/v1--action-plans/aprobar-un-plan-borrador /openapi-v1.es.json post /v1/action-plans/{id}/approve # Cancelar un plan Source: https://woku.app/docs/api-reference/v1--action-plans/cancelar-un-plan /openapi-v1.es.json post /v1/action-plans/{id}/cancel # Cerrar un plan gestionado Source: https://woku.app/docs/api-reference/v1--action-plans/cerrar-un-plan-gestionado /openapi-v1.es.json post /v1/action-plans/{id}/complete # Editar una tarea: texto en un plan borrador/gestionado, estado y responsable en un plan gestionado Source: https://woku.app/docs/api-reference/v1--action-plans/editar-una-tarea:-texto-en-un-plan-borradorgestionado-estado-y-responsable-en-un-plan-gestionado /openapi-v1.es.json patch /v1/action-plans/{id}/tasks/{taskId} # Eliminar una tarea (plan borrador o gestionado) Source: https://woku.app/docs/api-reference/v1--action-plans/eliminar-una-tarea-plan-borrador-o-gestionado /openapi-v1.es.json delete /v1/action-plans/{id}/tasks/{taskId} # Gestionar un plan aprobado dentro de woku Source: https://woku.app/docs/api-reference/v1--action-plans/gestionar-un-plan-aprobado-dentro-de-woku /openapi-v1.es.json post /v1/action-plans/{id}/send provider: internal, administra el plan dentro de woku. Los destinos externos no están disponibles en la API pública. # Listar los planes de acción de la empresa que hace la llamada Source: https://woku.app/docs/api-reference/v1--action-plans/listar-los-planes-de-acción-de-la-empresa-que-hace-la-llamada /openapi-v1.es.json get /v1/action-plans # Obtener la conversación de IA del plan Source: https://woku.app/docs/api-reference/v1--action-plans/obtener-la-conversación-de-ia-del-plan /openapi-v1.es.json get /v1/action-plans/{id}/conversation Solo lectura. `busy` es true mientras la IA está componiendo una respuesta. `messages` está vacío para un plan al que nunca se le ha respondido. # Obtener la línea de tiempo del plan, eventos, los más antiguos primero Source: https://woku.app/docs/api-reference/v1--action-plans/obtener-la-línea-de-tiempo-del-plan-eventos-los-más-antiguos-primero /openapi-v1.es.json get /v1/action-plans/{id}/events # Obtener un plan de acción Source: https://woku.app/docs/api-reference/v1--action-plans/obtener-un-plan-de-acción /openapi-v1.es.json get /v1/action-plans/{id} # Reabrir a borrador un plan approved/delivery_error Source: https://woku.app/docs/api-reference/v1--action-plans/reabrir-a-borrador-un-plan-approveddelivery_error /openapi-v1.es.json post /v1/action-plans/{id}/reopen # Reabrir un plan gestionado completado Source: https://woku.app/docs/api-reference/v1--action-plans/reabrir-un-plan-gestionado-completado /openapi-v1.es.json post /v1/action-plans/{id}/resume # Reordenar tareas (plan borrador o gestionado) Source: https://woku.app/docs/api-reference/v1--action-plans/reordenar-tareas-plan-borrador-o-gestionado /openapi-v1.es.json patch /v1/action-plans/{id}/tasks/reorder # Responder al agente de IA del plan (turno de IA pagado, requiere confirmación) Source: https://woku.app/docs/api-reference/v1--action-plans/responder-al-agente-de-ia-del-plan-turno-de-ia-pagado-requiere-confirmación /openapi-v1.es.json post /v1/action-plans/{id}/conversation Requiere confirm:true. Devuelve un acuse del mensaje humano. La respuesta de la IA se compone de forma asíncrona, así que consulte GET conversation hasta que busy sea false. Solo un plan en borrador acepta respuestas (409 en caso contrario). # Actualizar una definición de tracker, nombre, sistema, descripción Source: https://woku.app/docs/api-reference/v1--external-trackers/actualizar-una-definición-de-tracker-nombre-sistema-descripción /openapi-v1.es.json patch /v1/external-trackers/{id} # Asigna (upsert) un valor de tracker a un Woku por nombre de tracker Source: https://woku.app/docs/api-reference/v1--external-trackers/asigna-upsert-un-valor-de-tracker-a-un-woku-por-nombre-de-tracker /openapi-v1.es.json post /v1/external-trackers/wokus/{wokuId} Idempotente: si (`wokuId`, `trackerName`) ya tiene un valor, se sobrescribe. Resuelve `trackerId` del lado del servidor. # Asigna (upsert) un valor de tracker a una entidad VoC por nombre de tracker Source: https://woku.app/docs/api-reference/v1--external-trackers/asigna-upsert-un-valor-de-tracker-a-una-entidad-voc-por-nombre-de-tracker /openapi-v1.es.json post /v1/external-trackers/{entityType}/{id} Idempotente: si (`entity`, `trackerName`) ya tiene un valor, se sobrescribe. Resuelve `trackerId` del lado del servidor. # Buscar asignaciones de tracker de Woku que coincidan con (name, value) dentro de la empresa. Devuelve entradas WokuExternalTracker paginadas. El llamante puede mapear .wokuId para obtener los Wokus completos. Source: https://woku.app/docs/api-reference/v1--external-trackers/buscar-asignaciones-de-tracker-de-woku-que-coincidan-con-name-value-dentro-de-la-empresa-devuelve-entradas-wokuexternaltracker-paginadas-el-llamante-puede-mapear-wokuid-para-obtener-los-wokus-completos /openapi-v1.es.json get /v1/external-trackers/search # Buscar entidades de VoC por filtros de tracker (AND, coincidencia parcial) Source: https://woku.app/docs/api-reference/v1--external-trackers/buscar-entidades-de-voc-por-filtros-de-tracker-and-coincidencia-parcial /openapi-v1.es.json post /v1/external-trackers/search-entities Devuelve las entidades de VoC (nps/csat/ces/form/flow) cuyas asignaciones de tracker coinciden con TODOS los filtros dados. La respuesta incluye los ids de entidad y los pares (name, value) coincidentes; mapea los ids para obtener las entidades. Woku no se puede buscar aquí; usa GET /v1/external-trackers/search para Woku. # Crear una definición de rastreador externo en el catálogo de la empresa Source: https://woku.app/docs/api-reference/v1--external-trackers/crear-una-definición-de-rastreador-externo-en-el-catálogo-de-la-empresa /openapi-v1.es.json post /v1/external-trackers La empresa y el creador se resuelven del lado del servidor a partir de la clave del llamante. Los nombres de tracker son únicos por empresa. # Desactivar una definición de rastreador (eliminación lógica). Los valores existentes siguen siendo legibles. Source: https://woku.app/docs/api-reference/v1--external-trackers/desactivar-una-definición-de-rastreador-eliminación-lógica-los-valores-existentes-siguen-siendo-legibles /openapi-v1.es.json patch /v1/external-trackers/{id}/deactivate # Eliminar un valor de tracker de un Woku por nombre de tracker Source: https://woku.app/docs/api-reference/v1--external-trackers/eliminar-un-valor-de-tracker-de-un-woku-por-nombre-de-tracker /openapi-v1.es.json delete /v1/external-trackers/wokus/{wokuId}/{trackerName} # Eliminar un valor de tracker de una entidad VoC por nombre de tracker Source: https://woku.app/docs/api-reference/v1--external-trackers/eliminar-un-valor-de-tracker-de-una-entidad-voc-por-nombre-de-tracker /openapi-v1.es.json delete /v1/external-trackers/{entityType}/{id}/{trackerName} # Lista las definiciones de tracker externas de la empresa que llama Source: https://woku.app/docs/api-reference/v1--external-trackers/lista-las-definiciones-de-tracker-externas-de-la-empresa-que-llama /openapi-v1.es.json get /v1/external-trackers # Lista los valores de tracker asignados a un Woku Source: https://woku.app/docs/api-reference/v1--external-trackers/lista-los-valores-de-tracker-asignados-a-un-woku /openapi-v1.es.json get /v1/external-trackers/wokus/{wokuId} # Lista los valores de tracker asignados a una entidad VoC (tool/form/flow) Source: https://woku.app/docs/api-reference/v1--external-trackers/lista-los-valores-de-tracker-asignados-a-una-entidad-voc-toolformflow /openapi-v1.es.json get /v1/external-trackers/{entityType}/{id} # Obtener una definición de rastreador, incluida la inactiva Source: https://woku.app/docs/api-reference/v1--external-trackers/obtener-una-definición-de-rastreador-incluida-la-inactiva /openapi-v1.es.json get /v1/external-trackers/{id} # Reactivar una definición de tracker desactivada Source: https://woku.app/docs/api-reference/v1--external-trackers/reactivar-una-definición-de-tracker-desactivada /openapi-v1.es.json patch /v1/external-trackers/{id}/activate # Leer una conversación de seguimiento de la empresa Source: https://woku.app/docs/api-reference/v1--follow-ups/leer-una-conversación-de-seguimiento-de-la-empresa /openapi-v1.es.json get /v1/follow-ups/{id} Se requiere la clave secreta de gestión. Las claves publicables de captura no permiten leer conversaciones. # Actualiza un destino de tickets Source: https://woku.app/docs/api-reference/v1--ticket-destinations/actualiza-un-destino-de-tickets /openapi-v1.es.json patch /v1/ticket-destinations/{id} # Crea un destino de tickets Source: https://woku.app/docs/api-reference/v1--ticket-destinations/crea-un-destino-de-tickets /openapi-v1.es.json post /v1/ticket-destinations kind: zendesk | custom | email. config/credentials se validan según kind. routingConditions admite el operador "equals", un valor, o "any", el tracker completo. # Eliminar un destino de tickets Source: https://woku.app/docs/api-reference/v1--ticket-destinations/eliminar-un-destino-de-tickets /openapi-v1.es.json delete /v1/ticket-destinations/{id} # Enviar una prueba de conectividad real a un destino guardado Source: https://woku.app/docs/api-reference/v1--ticket-destinations/enviar-una-prueba-de-conectividad-real-a-un-destino-guardado /openapi-v1.es.json post /v1/ticket-destinations/{id}/test Requiere confirm:true. Realiza una llamada saliente real: los webhooks personalizados reciben una carga de prueba; zendesk ejecuta una sonda de autenticación de solo lectura; email solo valida la configuración. El resultado se sanea a { ok, status, message }. # Lista los destinos de tickets de la empresa del solicitante Source: https://woku.app/docs/api-reference/v1--ticket-destinations/lista-los-destinos-de-tickets-de-la-empresa-del-solicitante /openapi-v1.es.json get /v1/ticket-destinations # Obtiene un destino de tickets Source: https://woku.app/docs/api-reference/v1--ticket-destinations/obtiene-un-destino-de-tickets /openapi-v1.es.json get /v1/ticket-destinations/{id} # Actualizar la configuración booleana de woku, idempotente Source: https://woku.app/docs/api-reference/v1--wokus/actualizar-la-configuración-booleana-de-woku-idempotente /openapi-v1.es.json patch /v1/wokus/{id}/settings Aplica solo los flags presentes en el body. Un flag igual al estado actual no produce ningún efecto. # Actualizar una definición de woku, solo si no tiene reseñas Source: https://woku.app/docs/api-reference/v1--wokus/actualizar-una-definición-de-woku-solo-si-no-tiene-reseñas /openapi-v1.es.json patch /v1/wokus/{id} # Crea un woku Source: https://woku.app/docs/api-reference/v1--wokus/crea-un-woku /openapi-v1.es.json post /v1/wokus # Crea un woku con una carga de archivo Source: https://woku.app/docs/api-reference/v1--wokus/crea-un-woku-con-una-carga-de-archivo /openapi-v1.es.json post /v1/wokus/form-data # Eliminar un woku y todas sus reseñas Source: https://woku.app/docs/api-reference/v1--wokus/eliminar-un-woku-y-todas-sus-reseñas /openapi-v1.es.json delete /v1/wokus/{id} # Lista las reseñas de un woku (texto y voz, paginado) Source: https://woku.app/docs/api-reference/v1--wokus/lista-las-reseñas-de-un-woku-texto-y-voz-paginado /openapi-v1.es.json get /v1/wokus/{id}/reviews Las más recientes primero. Las reseñas de voz exponen la transcripción; los datos de contacto del cliente nunca se incluyen, solo `clientId`. # Lista los wokus de la empresa que llama (paginado) Source: https://woku.app/docs/api-reference/v1--wokus/lista-los-wokus-de-la-empresa-que-llama-paginado /openapi-v1.es.json get /v1/wokus # Mueve un woku a una carpeta, o a la raíz (`folderId`: null) Source: https://woku.app/docs/api-reference/v1--wokus/mueve-un-woku-a-una-carpeta-o-a-la-raíz-`folderid`:-null /openapi-v1.es.json patch /v1/wokus/{id}/move # Obtener datos de reseña de un woku Source: https://woku.app/docs/api-reference/v1--wokus/obtener-datos-de-reseña-de-un-woku /openapi-v1.es.json get /v1/wokus/{wokuId}/review # Obtiene un woku con estadisticas de reseñas agregadas Source: https://woku.app/docs/api-reference/v1--wokus/obtiene-un-woku-con-estadisticas-de-reseñas-agregadas /openapi-v1.es.json get /v1/wokus/{id} # Healthcheck del namespace v1 Source: https://woku.app/docs/api-reference/v1/healthcheck-del-namespace-v1 /openapi-v1.es.json get /v1/health Devuelve { ok: true } cuando el namespace v1 es accesible. Sin autenticación. # Envíos Source: https://woku.app/docs/configuration/sends Revisa cuántas invitaciones salieron, cuántas se respondieron y por qué algunas no se pudieron enviar La pestaña **Envíos** de **Empresa** muestra qué pasó con las invitaciones que tu empresa envió por correo y por WhatsApp, desde el admin, la API, el MCP y las integraciones (Shopify, Pancake y CRM). ## Qué muestra Elige un período (por defecto, los últimos 30 días; también 7 o 90 días, el histórico o un rango personalizado) y verás: * **Enviadas**: invitaciones que salieron. * **Entregadas**: las que el proveedor confirmó como entregadas. * **Respondidas**: las que recibieron al menos una respuesta. * **Tasa de respuesta**: respondidas sobre enviadas. * **No enviadas**: invitaciones que nunca salieron, con el motivo. * **Envíos por herramienta**: una fila por herramienta con su tipo, los envíos por **Correo** y por **WhatsApp**, el total de **Enviados** y los **Respondidos**. ## Detalle de una herramienta Haz clic en una fila de **Envíos por herramienta** para abrir sus envíos en el mismo período. Ahí verás la tabla de **invitaciones**: fecha, destinatario (nombre, correo o teléfono del cliente), canal y qué pasó con cada una (respondió, entregada o enviada sin respuesta, o no llegó). Puedes filtrarla por **Respondieron**, **Sin responder** y **No enviadas** para saber a quién volver a escribir. Desde el detalle también puedes: * **Ver en Herramientas** o **Ver en vista clásica** para abrir la herramienta. * **Descargar CSV** con una fila por invitación: fecha, herramienta, canal, nombre, correo, teléfono, estado y motivo. El destinatario muestra el nombre, el correo o el teléfono del cliente de tu empresa; si no es cliente, muestra el correo o el teléfono al que se envió la invitación. Las invitaciones más antiguas enviadas a personas que no son clientes aparecen como **Sin datos de contacto**. **Entregadas** cuenta las invitaciones que el proveedor confirmó: por WhatsApp, Meta; por correo, Amazon SES. ## Por qué una invitación no se envió | Motivo | Qué hacer | | - | - | | Sin créditos de WhatsApp | Recarga créditos o mejora el plan para seguir enviando por WhatsApp. | | El plan no incluye envíos por WhatsApp | Mejora el plan para enviar invitaciones por WhatsApp. | | WhatsApp rechazó el envío | Revisa que el número sea correcto y tenga WhatsApp. | Las invitaciones no enviadas no cuentan en la tasa de respuesta. > [!TIP] > > Si envías invitaciones desde tu sistema con la API, también puedes leer > estos datos con [`GET /v1/dispatches`](/docs/development/api) y sus > estadísticas. Cada invitación no enviada trae `status: skipped` (o > `failed` si WhatsApp la rechazó) y el motivo en `skipReason`. Desde un > agente conectado al MCP, usa las [herramientas de Envíos](/docs/mcp/tools). # Accionabilidad y sentimiento Source: https://woku.app/docs/core-concepts/actionability-and-sentiment Las dos lecturas que woku hace de cada comentario: si alguien tiene que actuar y qué tan positivo es. Cada comentario que llega a un woku, NPS, CSAT o CES se analiza en dos dimensiones independientes. Cada una responde una pregunta distinta y se usa para algo distinto. | | Accionabilidad | Sentimiento | | - | - | - | | Pregunta | ¿Alguien tiene que hacer algo con este comentario? | ¿Qué tan positivo es el comentario? | | Valores | Requiere acción (oportunidad) o no requiere acción (reconocimiento) | Positivo, neutro o negativo | | Para qué se usa | Decide el agente de seguimiento, las alertas, los tickets y los planes de acción | Análisis: estadísticas, reportes y tarjetas | | Cuándo se calcula | Al recibir el comentario, antes de cualquier acción | Después, sin bloquear nada | ## Accionabilidad: reconocimiento y oportunidad Un comentario **requiere acción** (oportunidad) cuando pide, sugiere o implica algo que la empresa debería hacer, corregir, cambiar o responder. Incluye quejas, sugerencias dentro de un elogio ("excelente charla, pero se alargó") y preguntas que esperan respuesta. Un comentario **no requiere acción** (reconocimiento) cuando no hay nada que hacer: elogios, agradecimientos o reflexiones, aunque usen palabras como "fracaso" o "problema" como tema. > [!NOTE] > > La accionabilidad no mide si el comentario fue positivo o negativo. Un comentario de 5 estrellas con una sugerencia requiere acción, y eso es correcto. Los comentarios sin contenido (solo calificación, texto vacío o un texto de relleno enviado por una integración) no se clasifican y no disparan ninguna acción. ## Sentimiento El sentimiento describe el tono del comentario: positivo, neutro o negativo. Es solo análisis y nunca dispara acciones. ### Sentimiento de un comentario La IA no le pone una sola etiqueta a cada comentario: estima qué porcentaje de lectores lo leería como positivo, neutro y negativo (los tres suman 100 %). Así un comentario mixto o ambiguo no se fuerza a un solo lado. * La **etiqueta** del comentario es la lectura con mayor porcentaje (en caso de empate, neutro). * El **número** del comentario es el porcentaje positivo menos el negativo, de -100 a +100. Ejemplo: un comentario leído 20 % positivo, 30 % neutro y 50 % negativo queda etiquetado como negativo, con un número de **-30**. Una queja tranquila pesa menos que una con rabia, que podría quedar en 0 % positivo, 5 % neutro y 95 % negativo (**-95**). ### Sentimiento neto Para un conjunto de comentarios (un woku, una carpeta, una herramienta o un período), woku muestra: * La **distribución**: porcentaje positivo, neutro y negativo, que suman 100 %. Es el promedio de los porcentajes de cada comentario. * El **sentimiento neto**: porcentaje positivo menos porcentaje negativo, con los neutros incluidos en el total. Va de -100 a +100 y se muestra sin signo de porcentaje, igual que el NPS. Ejemplo: 60 % positivo, 25 % neutro y 15 % negativo dan un sentimiento neto de **+45**. Reglas de cálculo: * Cada comentario cuenta una vez y aporta sus tres porcentajes. El sentimiento de una carpeta o de un período se calcula siempre sobre todos sus comentarios, nunca promediando el de sus partes. * Con menos de 10 comentarios analizados, woku muestra la distribución pero no el número, porque la muestra es pequeña. * El sentimiento del texto es distinto del promedio de estrellas. Se muestran lado a lado. ## En la API Las respuestas de `/v1` que incluyen comentarios traen los dos campos: | Campo | Valores | Descripción | | - | - | - | | `feedbackType` | `improvement`, `recognition` o `null` | Accionabilidad. `null` cuando no hay contenido que clasificar o la clasificación aún no termina. | | `sentiment` | `positive`, `neutral`, `negative` o `null` | Sentimiento del texto. `null` hasta que se analiza. | # CES Source: https://woku.app/docs/core-concepts/ces Aprende a configurar herramientas CES: acción a evaluar, escala 1 a 5 y comentario opcional Una **herramienta CES** (Customer Effort Score) es la plantilla que tu empresa configura para medir el **esfuerzo**: qué tan fácil le resultó a un cliente lograr lo que venía a hacer. Es la métrica indicada para interacciones donde reducir la fricción importa más que sorprender: soporte, postventa, onboarding, devoluciones o trámites. Es el **gemelo del CSAT**: comparte escala, lógica de puntaje obligatorio y comentario opcional, y las mismas métricas. Lo que cambia es la pregunta y lo que mide. Una misma empresa puede tener varios CES al mismo tiempo. Por ejemplo: * CES de atención de soporte. * CES de proceso de devolución. * CES de onboarding. ## Acción a evaluar La pregunta del CES es **fija**: *"En una escala de 1 a 5, ¿qué tan fácil fue ?"*. Lo único que defines es la **acción**: aquello que el cliente intentaba lograr. Ejemplos de acción: * "resolver tu problema" * "completar tu compra" * "hacer tu devolución" Mantén la acción breve y concreta. La pregunta se traduce automáticamente entre español e inglés, o puedes redactar tú mismo las versiones en cada idioma. ## Nombre El **nombre** es el identificador interno de la herramienta. Solo lo ve tu equipo, tus clientes no lo verán. Úsalo para distinguir tus CES cuando tienes varios, por ejemplo "CES soporte" o "CES devoluciones". > [!NOTE] > > Un CES que ya tiene respuestas no se puede editar. Así todas las respuestas corresponden siempre a la misma pregunta. ## Escala 1 a 5 La escala es fija y no se configura. El cliente elige un valor entero de **1 a 5**, donde 1 es muy difícil y 5 es muy fácil. El **puntaje es obligatorio**. ## Comentario opcional Después de elegir su puntaje, el cliente puede dejar un comentario en **texto** o en **audio**, y decidir si se **identifica con su correo** o responde de forma **anónima**. Si responde anónimo, no se le pide email. ## Ajustes de respuesta En **Editar** hay dos ajustes que puedes cambiar aunque el CES ya tenga respuestas: * **Exigir email para responder**: solo se aceptan respuestas identificadas. * **Una respuesta por cliente**: cada cliente identificado responde una sola vez. Si lo intenta de nuevo, ve un mensaje que le confirma que ya respondió, también por WhatsApp. Las respuestas anónimas no cuentan. Cuando ya hay respuestas, el texto de la pregunta queda fijo, para que cada respuesta siga correspondiendo a la pregunta que se hizo. ## Carpetas Una herramienta CES puede vivir en una **carpeta**, junto con wokus, NPS y CSAT, y moverse entre carpetas sin perder sus respuestas. Al crearla por la API indica `folderId`. Lee la guía [Carpetas y herramientas](/docs/guides/folders-and-tools). ## Compartir Igual que en las demás herramientas, tienes tres formas: * **Código QR**: para imprimir, pegar en un tótem o mostrar en pantalla. * **Enlace**: para enviar por chat, WhatsApp o dentro de un email transaccional. * **Envío masivo por correo**: pega un listado desde Excel o Google Sheets. ## Reportes La página principal de CES muestra el **CES combinado de la empresa**, que reúne las respuestas de todas tus herramientas: porcentaje de **Experiencias fáciles**, distribución de **Facilidad general** (Fáciles, Neutras y Difíciles), promedio sobre 5 y porcentaje de respuestas con comentario. Debajo, la tabla de **CES personalizados** lista cada herramienta con sus respuestas, facilidad, promedio y última respuesta. Al entrar a una herramienta ves su detalle: * **Experiencias fáciles**: porcentaje de respuestas con puntaje 4 o 5. * **Facilidad promedio**, **total de respuestas** y **tasa de comentarios**. * **Detalle por nota**: histograma de respuestas de 1 a 5. * **Facilidad general**: distribución entre Fáciles, Neutras y Difíciles. * **Comentarios**: cada comentario clasificado como Reconocimiento o Mejora según si requiere acción, el **sentimiento** del texto con su sentimiento neto ([Accionabilidad y sentimiento](/docs/core-concepts/actionability-and-sentiment)), y un **Resumen IA** que se genera automáticamente. Para medir satisfacción en lugar de esfuerzo, revisa [CSAT](/docs/core-concepts/csat). # Clientes Source: https://woku.app/docs/core-concepts/clients El perfil unificado de cada persona: contacto, atributos e historial de respuestas Un **Cliente** en woku es el perfil unificado de cada persona que interactúa con tu empresa. Reúne sus datos de contacto y sus atributos, y agrupa automáticamente todas las respuestas que ha dado (wokus, NPS, CSAT, CES y formularios) bajo un mismo perfil. Cada cliente pertenece a **una empresa** y es **único por email** dentro de ella. Así, aunque una persona responda muchas veces y por distintos canales, sus respuestas quedan reunidas en una sola identidad. ## Qué guarda un cliente * **Contacto**: email, teléfono y WhatsApp. Los datos de contacto se guardan cifrados. * **Atributos personalizados**: los campos que tú definas para tu empresa (por ejemplo nombre, tipo de cliente, segmento). Estos atributos se configuran en el **formulario de captación** y viven en cada cliente. * **Historial de respuestas**: todas las opiniones y respuestas asociadas a esa persona. > [!NOTE] > > El nombre del cliente y cualquier otro dato adicional son atributos personalizados que tú defines. Cada empresa decide qué campos quiere capturar. ## Cómo se crean los clientes Un cliente puede aparecer de varias formas: 1. **Automáticamente al responder**: cuando una persona responde un woku, NPS, CSAT, CES o formulario e incluye su **email**, woku busca si ya existe un cliente con ese correo en tu empresa. Si no existe, lo crea; si existe, reutiliza el mismo perfil. Este es el mecanismo que **unifica las respuestas** de una misma persona. 2. **A mano desde el panel**: con el botón **"New client"** en la sección Clientes. 3. **Por importación masiva (CSV)**: sube un archivo con tu base de clientes; woku deduplica por email y valida los atributos. ## Qué puedes hacer con ellos Desde la sección **Clientes** del panel administrativo: * **Listar y buscar** en toda tu base de clientes (la búsqueda incluye los atributos personalizados como el nombre). El listado se actualiza en tiempo real. * **Configurar el formulario de captación**: en la pestaña **Form** defines qué atributos tendrá cada cliente. * **Crear, editar o eliminar** clientes. * **Exportar a CSV** para procesar en una hoja de cálculo o cargar a tu sistema. ## Ficha del cliente Al abrir un cliente ves su perfil completo: * **Identificación**: email, teléfono y atributos personalizados. * **Estadísticas**: total de respuestas, promedio de woku (sobre 5) y promedio de NPS (sobre 10), cada uno con su número de respuestas. * **Historial por tipo**: pestañas con sus respuestas de **wokus**, **NPS** y **formularios**, incluyendo comentarios y notas de voz. Desde la ficha también puedes **editar**, **eliminar** o **enviarle un formulario** al cliente. # CSAT Source: https://woku.app/docs/core-concepts/csat Aprende a configurar herramientas CSAT: nombre, experiencia o producto a evaluar, escala 1 a 5 y comentario opcional Una **herramienta CSAT** (Customer Satisfaction) es la plantilla que tu empresa configura para medir **qué tan satisfecho** queda un cliente después de un momento concreto, como una compra, una entrega o una atención. Cada respuesta queda asociada a esa herramienta, lo que te permite separar mediciones por canal o momento. Una misma empresa puede tener varios CSAT al mismo tiempo. Por ejemplo: * CSAT post compra. * CSAT de entrega. * CSAT de atención en tienda. ## Nombre El **nombre** es interno: solo lo ve tu equipo, los clientes no lo verán. Úsalo para distinguir tus herramientas cuando tienes varias, por ejemplo "CSAT entrega Santiago" o "CSAT post compra web". ## Experiencia o producto La pregunta del CSAT es **fija** y sigue el estándar de la industria: *"En una escala de 1 a 5, ¿qué tan satisfecho/a estás con \{experiencia o producto}?"*. Lo único que defines es la **experiencia o producto**: aquello sobre lo que preguntas. Ejemplos: * "tu compra" * "la entrega de tu pedido" * "la atención que recibiste" Mantén el texto breve y concreto. La pregunta se traduce automáticamente entre español e inglés, o puedes redactar tú mismo las versiones en cada idioma. > [!NOTE] > > Un CSAT que ya tiene respuestas no se puede editar. Así todas las respuestas de la herramienta corresponden siempre a la misma pregunta. ## Escala 1 a 5 La escala es fija y no se configura. El cliente elige un valor entero de **1 a 5**, donde 1 es muy insatisfecho y 5 es muy satisfecho. El **puntaje es obligatorio**. > [!NOTE] > > A diferencia de un woku, donde el comentario es el corazón de la respuesta, en un CSAT lo obligatorio es el puntaje y el comentario es opcional. ## Comentario opcional Después de elegir su puntaje, el cliente puede dejar un comentario en **texto** o en **audio**. Así cada respuesta combina el dato cuantitativo (el número) con el cualitativo (el por qué). El cliente también puede **identificarse con su correo** o responder de forma **anónima**. Si responde anónimo, no se le pide email. ## Ajustes de respuesta En **Editar** hay dos ajustes que puedes cambiar aunque el CSAT ya tenga respuestas: * **Exigir email para responder**: solo se aceptan respuestas identificadas. * **Una respuesta por cliente**: cada cliente identificado responde una sola vez. Si lo intenta de nuevo, ve un mensaje que le confirma que ya respondió, también por WhatsApp. Las respuestas anónimas no cuentan. Cuando ya hay respuestas, el texto de la pregunta queda fijo, para que cada respuesta siga correspondiendo a la pregunta que se hizo. ## Carpetas Una herramienta CSAT puede vivir en una **carpeta**, junto con wokus, NPS y CES, y moverse entre carpetas sin perder sus respuestas. Al crearla por la API indica `folderId`. Lee la guía [Carpetas y herramientas](/docs/guides/folders-and-tools). ## Compartir Compartir un CSAT funciona igual que compartir un woku. Tienes tres formas: * **Código QR**: para imprimir, pegar en un tótem o mostrar en pantalla. * **Enlace**: para enviar por chat, WhatsApp o dentro del email transaccional que ya mandas al cliente. * **Envío masivo por correo**: pega un listado desde Excel o Google Sheets y la aplicación se encarga del resto. ## Visión combinada de la empresa La vista principal del módulo muestra el **CSAT combinado** de toda la empresa: cuántas respuestas son de clientes **satisfechos**, **neutros** e **insatisfechos**, la **satisfacción promedio** sobre 5 y el **porcentaje de respuestas que dejó un comentario**. Debajo, una tabla lista tus CSAT con sus **respuestas**, su **satisfacción**, su **promedio** y la fecha de la **última respuesta**, para comparar herramientas de un vistazo. ## Detalle por herramienta Al entrar a un CSAT ves sus métricas propias: * **Clientes satisfechos**: porcentaje de respuestas con puntaje 4 o 5. * **Satisfacción promedio** y **total de respuestas**. * **Tasa de comentarios**: cuántas respuestas incluyen un comentario. * **Detalle por nota**: histograma con la cantidad de respuestas de cada puntaje, de 1 a 5. * **Distribución de satisfacción general**: satisfechos, neutros e insatisfechos. El bloque **Comentarios** reúne las respuestas con comentario y las clasifica automáticamente como **Reconocimiento** o **Mejora** según si requieren acción, y muestra el **sentimiento** del texto (positivo, neutro o negativo) con su sentimiento neto; ver [Accionabilidad y sentimiento](/docs/core-concepts/actionability-and-sentiment). Además, un **Resumen IA** se genera automáticamente con las respuestas de la herramienta, para leer en segundos lo que dicen tus clientes. CSAT y CES son herramientas espejo: comparten escala, lógica de puntaje obligatorio y comentario opcional, y las mismas métricas. Lo que cambia es la pregunta y lo que miden. Revisa [CES](/docs/core-concepts/ces) para medir esfuerzo. # Flow Source: https://woku.app/docs/core-concepts/flow Aprende a armar y compartir un Flow, la secuencia ordenada de wokus y herramientas NPS, CSAT y CES Un **Flow** orquesta varios pasos, en un orden definido, dentro de una misma experiencia de respuesta. Cada paso es un woku o una herramienta NPS, CSAT o CES. Es la herramienta indicada cuando una sola pregunta no alcanza para entender lo que pasó. ## Composición Un Flow está formado por: * **Nombre**: identifica el Flow internamente. * **Pasos ordenados**: de 1 a 20 pasos. Cada paso es un **woku**, una herramienta **NPS**, una herramienta **CSAT** o una herramienta **CES** de tu empresa, en el orden en que quieres que el cliente los responda. Una misma herramienta aparece una sola vez. Las herramientas que forman el Flow deben existir previamente: primero las creas de manera normal y después las combinas dentro de un Flow. Un woku cerrado, o configurado para una sola reseña por cliente, no puede ser un paso. Un Flow no vive dentro de carpetas. Los Flows que ya existían, un NPS opcional al inicio seguido de wokus, siguen funcionando igual y se leen como pasos en ese mismo orden. ## Orden de la secuencia El orden importa. Cada paso construye sobre el anterior, y el cliente lo percibe como un recorrido coherente. Algunas reglas que funcionan bien: * Parte por lo general y termina por lo específico, o al revés. Lo importante es que haya una lógica. * No mezcles momentos demasiado distintos en un mismo Flow. Si un cliente va a evaluar un evento, mantén el Flow centrado en ese evento. * Mantén entre 2 y 5 pasos. Más allá de eso, la tasa de finalización empieza a caer. ## Orden en la experiencia del cliente El cliente recorre los pasos en el orden en que los definiste. Si el primer paso es un NPS, captura la pregunta de recomendación cuando aún no se ha detenido a pensar momento por momento. Un CSAT o un CES en medio del recorrido sirve para medir satisfacción o esfuerzo justo después de un paso concreto. ## Barra de progreso Mientras el cliente recorre el Flow, ve siempre en qué paso va, por ejemplo "Paso 2 de 4". Esto reduce la sensación de "no se cuándo va a terminar esto" y aumenta la probabilidad de que complete todo el recorrido. ```mermaid theme={null} flowchart LR A[Inicio] --> B[Paso 1/4: NPS opcional] B --> C[Paso 2/4: Woku A] C --> D[Paso 3/4: Woku B] D --> E[Paso 4/4: Woku C] E --> F[Gracias] ``` ## Identificación del cliente Si el cliente decide identificarse con su correo en el primer paso, ese mismo correo se asocia automáticamente a las respuestas de los pasos siguientes (sean wokus, NPS, CSAT o CES). Esto te permite reconstruir el recorrido completo de un mismo cliente sin pedirle que repita su información. Si el cliente decide responder de forma anónima, todos los pasos quedan anónimos. ## Compartir Compartir un Flow funciona igual que un woku o un NPS: * **Código QR**: para imprimir o mostrar en pantalla. * **Enlace**: para enviar por chat, WhatsApp o pegar en tu sitio. * **Envío masivo por correo**: pegando un listado desde una hoja de cálculo. Al cliente se le entrega un solo enlace, no uno por woku. Es el Flow el que se encarga de avanzar paso a paso. ## Reportes Las respuestas de cada paso quedan guardadas en su propia herramienta (woku, NPS, CSAT o CES). Esto significa que: * Los reportes individuales por woku, NPS, CSAT y CES siguen funcionando como siempre. * La vista del Flow te muestra cuántas personas iniciaron y cuántas completaron el recorrido. ## Editar y eliminar Puedes editar un Flow para cambiar el nombre o reemplazar su lista de pasos: agregar o quitar herramientas y reordenarlas. Los cambios afectan a los nuevos clientes que abran el enlace, no a quienes ya respondieron. Eliminar un Flow no borra las herramientas que lo componían, ni las respuestas ya capturadas. Solo desactiva la experiencia encadenada. ## API, SDKs y MCP Un Flow se administra con `GET`, `POST`, `PATCH` y `DELETE` sobre `/v1/flows`, con `woku.flows` en los SDK de JavaScript y Python, y con `create_flow`, `update_flow` y `get_flow` en el servidor MCP. Todos usan la lista ordenada de pasos (`steps`, cada uno `{ type, toolId }`). ```ts theme={null} const flow = await woku.flows.create({ name: 'Posventa', steps: [ { type: 'nps', toolId: npsToolId }, { type: 'csat', toolId: csatToolId }, { type: 'woku', toolId: wokuId }, ], }); ``` Para un paso `nps`, el id de tu empresa como `toolId` significa el NPS de la empresa. Más detalle en la [guía de integración de la API](/docs/development/api#flows). # Agente de follow up Source: https://woku.app/docs/core-concepts/follow-up-agent Conoce el agente de inteligencia artificial que conversa por WhatsApp o correo con cada cliente que pidió mejorar algo y entrega el caso con evidencia El **agente de follow up** es un **agente de inteligencia artificial** de woku. Cuando un cliente deja un comentario de **mejora** en un woku, NPS, CSAT o CES, el agente le escribe para entender mejor qué pasó: hace preguntas concretas, recibe fotos, audios y documentos, y le entrega a tu equipo un resumen con la evidencia. Así, un comentario corto como "llegó roto" se convierte en un caso completo: qué se rompió, cómo llegó y qué esperaba el cliente, sin que nadie de tu equipo tenga que escribirle. > [!NOTE] > > El agente es una inteligencia artificial. Si el cliente le pregunta si es una persona, responde con honestidad que es un agente de inteligencia artificial de tu empresa que toma los detalles para el equipo. ## Cuándo actúa El agente conversa solo cuando la respuesta cumple todas estas condiciones: * El comentario se clasificó como **Mejora**. Los comentarios de **Reconocimiento** no reciben seguimiento. * El cliente está **identificado** y tiene WhatsApp o correo. Las respuestas anónimas no reciben seguimiento. * Es una respuesta **individual** a la herramienta. Las respuestas dentro de un Flow no reciben seguimiento. * El cliente no pidió dejar de recibir seguimientos. El agente se activa por empresa. Consulta con el equipo de woku para habilitarlo en la tuya. ## Dónde conversa El agente escribe donde ya está tu cliente: * **Si respondió la encuesta por WhatsApp**, el agente sigue en **ese mismo chat**, justo después de la encuesta, sin enviar una plantilla nueva. La encuesta y el seguimiento quedan como una sola conversación. * **Si respondió por web, API, correo o un código QR**, el agente le escribe por el **número de WhatsApp de follow up** o por **correo**. Por WhatsApp, el agente solo escribe dentro de la ventana de 24 horas que permite Meta desde el último mensaje del cliente. ## Cómo conversa * Hace **una pregunta concreta a la vez** sobre lo que contó el cliente. * **No pide datos que tu empresa ya tiene** ni cosas que el cliente ya dijo, como fechas, número de pedido o el producto que compró. * **Cierra cuando ya tiene lo necesario**. Si el comentario ya explicaba todo, el primer mensaje puede ser directamente un cierre. * Si el cliente **no quiere seguir**, cierra la conversación con respeto y sin insistir. * **Nunca promete reembolsos, descuentos ni acciones**, ni dice que algo ya se resolvió. Solo reúne información para tu equipo. * Si el cliente no responde, envía **un recordatorio** como máximo y luego cierra por inactividad. Un "gracias" o un "ok" después del cierre no reabre la conversación. ## Fotos, audios y documentos El cliente puede responder con **texto**, **fotos**, **audios** y **documentos** (por ejemplo PDF, Word, Excel o presentaciones), por WhatsApp o por correo. El agente los lee y no vuelve a preguntar lo que ya muestran. Los videos no son compatibles: si el cliente envía uno, el agente le pide que cuente por escrito lo que muestra. Cada archivo se guarda de forma **privada** con una etiqueta estable en la conversación, por ejemplo **Archivo 2**. Solo se puede abrir desde el admin de woku, con sesión iniciada en la empresa. ## El resumen para tu equipo Cuando la conversación termina con respuestas del cliente, el agente genera un **resumen** con: * Un **resumen ejecutivo** de lo que agregó el seguimiento. * **Acciones a tomar**, **temas** y **sentimiento**. * **Citas a los archivos** que respaldan cada afirmación, por ejemplo "(Archivo 1)". Ese resumen llega a donde tu equipo trabaja: * **Tickets de soporte**: si la respuesta generó un ticket, el resumen y los archivos se suman al ticket. * **Planes de acción**: los resúmenes de seguimiento se usan como contexto al generar planes, sin cambiar sus métricas. ## Dónde ver las conversaciones En el admin, las respuestas con seguimiento muestran el botón **Agente de IA** en la lista de respuestas de cada herramienta. Ahí ves la conversación completa, la encuesta previa, los archivos con su vista previa y el resumen. La misma conversación se abre desde el detalle del ticket y desde la evidencia de los planes de acción. ## Correo del cliente Cuando el agente continúa el chat de la encuesta por WhatsApp, no pide el correo al principio para no interrumpir lo importante. Si el cliente no tiene correo registrado, el agente se lo pide al final, una sola vez y de forma opcional. Si el cliente responde con su correo, queda guardado en su ficha. ## Para desarrolladores Las conversaciones se leen por API con `GET /v1/follow-ups/:id`, por los SDKs de [JavaScript](/docs/development/sdk-javascript#seguimiento) y [Python](/docs/development/sdk-python#seguimiento) y por MCP con `get_follow_up`. El detalle está en la [guía de la API](/docs/development/api#procedencia-y-seguimiento). # Forms Source: https://woku.app/docs/core-concepts/forms Aprende a configurar un Form: campos, ajustes y verificación de respuestas Un **Form** se compone de tres bloques: el **nombre**, los **campos** y los **ajustes**. ## Nombre Es la identificación interna del formulario. Te sirve para reconocerlo en el listado y para que el cliente sepa de qué se trata cuando lo abra. Sé breve y específico: "Inscripción Capacitación Excel" o "Datos de facturación". ## Campos Cada Form tiene una lista ordenada de campos. Para cada uno defines: * **Tipo** de dato que se va a capturar. * **Etiqueta** que verá el cliente. * Si es **obligatorio** u opcional. * **Placeholder** (texto guía dentro del campo, opcional). * **Opciones**, cuando el tipo lo requiere (select y multiselect). * **Orden** dentro del formulario. ### Tipos de campo disponibles | Tipo | Para qué sirve | | - | - | | `text` | Texto libre corto. | | `number` | Cantidad, monto, identificador numérico. | | `date` | Fecha (selector de calendario). | | `email` | Correo electrónico, con validación de formato. | | `phone` | Número de teléfono. | | `select` | Una opción de una lista. | | `multiselect` | Varias opciones de una lista. | Los tipos `select` y `multiselect` requieren que definas las opciones de la lista. ### Orden y obligatoriedad El orden determina cómo se presenta el formulario al cliente. La obligatoriedad bloquea el envío si el campo está vacío. Procura mantener pocos campos obligatorios para no asustar al cliente, y deja como opcional todo lo que no sea estrictamente necesario. > [!NOTE] > > Puedes editar libremente un Form mientras no tenga respuestas. Después de recibir la primera respuesta, no podrás agregar o eliminar campos ni cambiar sus tipos. Sí podrás ajustar sus textos, opciones, obligatoriedad y orden. ### Formularios multi-idioma Un mismo Form puede estar disponible en español e inglés bajo el mismo enlace. Al habilitar otro idioma, puedes escribir las traducciones manualmente o dejar que woku las genere con IA. Después puedes revisarlas o modificarlas desde la configuración. Las respuestas de todos los idiomas se consolidan en el mismo Form. Consulta [Encuestas multi-idioma](/docs/guides/multilanguage-surveys) para conocer su funcionamiento. ## Ajustes Los tres ajustes del formulario definen cómo se comporta: ### Respuestas anónimas Si está activado, el cliente puede enviar el formulario sin entregar ningún dato de contacto. Si está desactivado, el formulario exige que el cliente se identifique según el identificador elegido. ### Identificador del cliente Define cómo se identifica al cliente cuando no responde de forma anónima. Puede ser: * **Email**: se le pide su correo y se le envía un email de verificación. * **Teléfono**: se le pide su número de teléfono. Por defecto, es email. ### Una respuesta por cliente Si está activado, un mismo cliente no puede enviar dos respuestas al formulario. Útil para inscripciones, registros únicos o casos en los que necesitas evitar duplicados. ## Verificación de respuestas por email Cuando el cliente responde con su correo, el formulario crea primero una **respuesta provisional** que se guarda por hasta 7 días, mientras el cliente verifica su email. Cuando verifica: 1. La respuesta se convierte en una **respuesta definitiva**. 2. Queda asociada al cliente y disponible en los reportes. 3. Si la verificación nunca ocurre, la respuesta provisional se elimina automáticamente a los 7 días. ```mermaid theme={null} flowchart LR A[Cliente envía respuesta] --> B[Se crea provisional] B --> C[Email de verificación] C --> D{¿Verifica en 7 días?} D -->|Sí| E[Respuesta definitiva] D -->|No| F[Se elimina sola] ``` Si el formulario permite anónimo y el cliente responde sin email, la respuesta se guarda directamente como definitiva, sin paso de verificación. ## Estado del formulario Un Form puede estar: * **Activo**: recibe respuestas. * **Inactivo**: no recibe respuestas nuevas. Las respuestas previas siguen disponibles. * **Cerrado**: igual que inactivo, pero comunicado explícitamente al cliente. ## Compartir Igual que un woku, un NPS o un Flow. Tres opciones: * Código QR. * Enlace. * Envío masivo por correo. ## Respuestas Las respuestas quedan disponibles en la vista del Form. Para cada respuesta verás los valores de cada campo, la fecha de envío y, cuando corresponda, el dato de contacto del cliente. Puedes exportar todo a CSV para procesarlo en una hoja de cálculo o cargarlo a tu sistema. ## Análisis con IA Cuando el Form acumula al menos **5 respuestas**, abre la pestaña **Resumen** para generar un análisis con IA de todas las respuestas disponibles. El informe incluye: * Un resumen general del volumen y el período analizado. * Patrones, segmentaciones y anomalías entre los campos. * Conclusiones accionables. * Estadísticas por campo, como promedios para valores numéricos y frecuencias para opciones o texto. # Viajes del cliente Source: https://woku.app/docs/core-concepts/journeys Describe la experiencia de tus clientes, evalúa sus momentos y automatiza el seguimiento con control por cliente y caso Un **viaje del cliente** organiza cuándo escuchar a una persona y qué quieres entender en cada momento. Una **participación** es la evaluación de una compra o caso concreto. El mismo cliente puede tener varias participaciones independientes. ## Crear un viaje desde el negocio En el admin, abre **Voz del cliente > Viajes del cliente**. El formulario comienza con tres respuestas en tus palabras: 1. Qué experiencia vive tu cliente. 2. Qué momentos ocurren y en qué orden. 3. Qué quieres entender en cada momento. **Proponer mi viaje** interpreta esas respuestas con IA y propone momentos editables. No es un chat: las aclaraciones aparecen junto a los campos. Puedes corregir los momentos, reordenarlos, deshacer o diseñarlos por tu cuenta. El borrador se guarda separado de la configuración que ejecuta el motor. Después revisas las esperas y si el viaje creará tickets, planes o ambos. Puedes inscribir desde la plataforma o compartir el acceso del cliente; el inicio por otro sistema se configura en el primer momento. Cada acción tiene su propia sección y puede apagarse sin completar sus destinatarios. Revisa la propuesta antes de guardar. **Guardar y conectar** deja un viaje nuevo apagado: conecta sus sistemas y actívalo cuando sus recursos estén listos. ## Quién inicia la evaluación Solo el primer momento define cómo comienza el viaje. | Forma de inicio | Qué inicia la participación | Primera respuesta | | - | - | - | | Desde Woku (`operator`) | Un usuario agrega al cliente desde la plataforma, API o MCP | No es necesaria para continuar | | El cliente al responder (`response`) | Se guarda la respuesta del cliente a la primera herramienta | Es obligatoria para iniciar | | Otro sistema (`webhook`) | Llega el webhook del primer momento con su referencia y contacto | No es necesaria para continuar | En el admin, puedes inscribir con email o teléfono. El email normalizado identifica al cliente cuando está presente; si no hay email, se usa el teléfono normalizado y el primer envío va por WhatsApp. En la inscripción manual, el mismo identificador puede completar este viaje varias veces, pero solo tener una evaluación en curso a la vez. API y MCP conservan `subjectKey` para integraciones que necesitan una referencia de caso distinta del contacto. El ciclo se completa cuando el cliente responde la última herramienta o 30 días después del primer envío de esa herramienta. Entonces puedes inscribir de nuevo al mismo cliente sin pedirle otra clave. Cada ciclo conserva su propio historial. Desde **Compartir**, el envío por email o WhatsApp inscribe al cliente de forma predeterminada y le envía la primera herramienta. Si desactivas la inscripción, recibe esa misma herramienta, pero el viaje queda pendiente hasta que la responda. Se usan las plantillas habituales de Woku, CSAT, CES o NPS; el cliente no recibe una invitación a un viaje ni necesita conocer su nombre interno. Los recordatorios respetan la configuración del primer momento y se detienen al responder o detener la evaluación. El **QR o enlace**, compartido en una etiqueta de producto, WhatsApp u otro medio, inicia el recorrido solo con la primera respuesta. Escanear, abrir el enlace o completar los datos de contacto no lo inicia. La primera herramienta queda preparada; su respuesta inicia una vez y no vuelve a enviar esa herramienta. El acceso puede solicitar la referencia de compra y el contacto necesarios para el seguimiento. Mientras no exista la primera respuesta, la participación aparece **Pendiente de inicio**. ## Cuándo evaluar los siguientes momentos Los momentos posteriores avanzan automáticamente. No admiten un segundo inicio manual. * **Espera en días**: evaluar después del hito configurado del momento anterior. La espera inicial sugerida es de 10 días. Si eliges 0 días, Woku espera 1 hora antes de enviar la siguiente herramienta. El formulario usa el envío del momento anterior como origen; cuando el cliente inicia respondiendo, la primera espera parte de esa respuesta. * **Webhook principal**: esperar la confirmación del sistema que conoce ese momento. * **Respaldo opcional del webhook**: si no llega la confirmación, evaluar ese mismo momento después de los días configurados. El plazo necesita una participación y un hito anterior conocidos. Cada momento tiene su propia conexión, incluso si normalmente avanza por espera. Si su webhook llega antes, **adelanta la evaluación y cancela la espera**. El timer y el webhook no producen dos envíos iniciales. Si ya actuó el respaldo, un webhook tardío no repite el envío. El respaldo envía la evaluación del momento; no demuestra que una entrega u otro hecho de negocio haya ocurrido. Sin respaldo, el momento sigue esperando su webhook. ## Herramientas propias de cada momento Cada momento crea una herramienta **Woku, CSAT, CES o NPS**. Dos momentos distintos nunca comparten herramienta ni reciben una herramienta existente. En un viaje nuevo, la herramienta se reutiliza por defecto entre los clientes de ese mismo momento. Puedes elegir una herramienta por participación cuando el caso lo requiera. | Opción | Alcance | | - | - | | Compartida en este momento (`shared`, predeterminada) | Reutiliza la herramienta solo dentro de ese momento y configuración, conservando la correlación de cada caso | | Una por participación (`per_enrollment`) | Cada compra o caso tiene su herramienta en ese momento | CSAT evalúa satisfacción, CES facilidad y NPS recomendación. `toolSpec.subject` contiene la experiencia, acción o empresa/producto, no la pregunta completa. NPS también usa `toolSpec.audience`. Las variables admiten español e inglés. Woku requiere una imagen o video subido, mediante `toolSpec.fileId`, y toma el nombre del momento como título. `toolSpec.descriptionEn` permite fijar su versión inglesa; si falta, Woku conserva la traducción automática existente. La creación nueva usa **un envío inicial y un recordatorio al día siguiente por defecto**. Puedes cambiar o desactivar el recordatorio en cada momento. Las definiciones anteriores conservan su configuración de intentos. ### Tus herramientas ordenadas en carpetas Las herramientas de cada momento pueden ordenarse solas en **Viajes > viaje > momento**. Es opcional, se activa una vez por empresa y nunca mueve una herramienta que ya tiene carpeta. Mover o renombrar esas carpetas no rompe el viaje. Más detalle en [Carpetas y herramientas](/docs/guides/folders-and-tools#viajes-en-carpetas). ## Conectar CRM, logística y otros sistemas Por ejemplo, el CRM avisa la compra a la URL de **Venta**, y el software logístico avisa a la URL de **Entrega**. Ambos deben enviar **la misma referencia de compra o caso**. Un email identifica al contacto, pero no reemplaza esa referencia: una persona puede tener dos pedidos simultáneos. Configura cada conexión desde su momento: 1. Elige URL con credencial incluida, o la firma que emite el sistema externo. 2. Indica las rutas de la referencia, email y teléfono cuando el payload tenga otra estructura, por ejemplo `order.id`. 3. Guarda la conexión y prueba la lectura con un ejemplo. Esta prueba no envía herramientas, no inscribe clientes ni verifica la firma del emisor. 4. Genera y copia la URL al sistema correspondiente. Una credencial configurada no demuestra que ya haya llegado una llamada real. Generar otra URL reemplaza la anterior de ese momento. Los secretos del emisor se guardan cifrados y no se devuelven. Renombrar o reordenar conserva las claves de los momentos y sus credenciales. La API de administración permite consultar y configurar las conexiones: * `GET /v1/journeys/{id}/connections` * `POST /v1/journeys/{id}/moments/{stageKey}/url-token` * `POST /v1/journeys/{id}/moments/{stageKey}/sender-secret` * `POST /v1/journeys/{id}/moments/{stageKey}/preview` Usa la URL que devuelve la operación de generación como destino del sistema emisor. Un payload con la forma predeterminada es: ```json theme={null} { "subjectKey": "order-123", "contact": { "email": "cliente@example.com" } } ``` Los momentos posteriores pueden enviar solo la referencia si el contacto ya se conoce. Incluye un `X-Woku-Event-Id` estable en los reintentos del mismo evento. Una señal de un momento posterior que llega antes del inicio se conserva hasta que se cumplan sus condiciones. Woku no mezcla referencias distintas ni adivina que dos pedidos son el mismo por tener igual email. ## Tickets y planes El formulario separa dos destinos: **emails para tickets** y un **grupo de planes formado por usuarios de la empresa**. El email del creador aparece por defecto para tickets. En el grupo, el creador queda como administrador y puedes agregar otros usuarios de Woku como responsables. Al enfocar el buscador aparecen cinco usuarios; al escribir se filtra el resto. Los seleccionados se muestran debajo con sus avatares. Puedes apagar **Crear tickets** o **Crear planes** por separado, incluso ambos. Una acción apagada no produce nuevos tickets o planes y no exige completar sus destinatarios. Las preferencias y los valores escritos quedan disponibles para reactivarla. En la API, usa `recipients.ticketsEnabled` y `recipients.plansEnabled`; al omitirlos, ambas acciones siguen activadas por compatibilidad. Woku provisiona el destino de soporte, el grupo de planes y los trackers del viaje. Las señales quedan acotadas a ese viaje. Los tickets siguen las reglas de señales; los planes se generan al alcanzar el umbral del grupo. No toda respuesta genera un ticket ni cada evaluación completada genera un plan. En viajes v2, el valor del tracker **Viaje** es una identidad estable: la clave legible del viaje en formato slug, seguida de su ID completo. Dos viajes con el mismo nombre tienen valores distintos y renombrar uno no cambia esa identidad. **ID del viaje** conserva el ID sin formato para el enrutamiento interno. Solo usuarios que ya pertenecen a la empresa pueden integrar el grupo de planes. El grupo define membresía y permisos; no se aceptan emails externos como destino de planes. Si falta un destino o grupo válido, la activación muestra el pendiente. Los módulos dueños de esos recursos conservan sus ajustes; guardar un viaje sin modificar destinatarios no debe reemplazar cambios hechos allí. ## Seguir y detener un caso La vista del viaje muestra un resumen y abre una tabla paginada de evaluaciones por referencia, contacto, estado, versión y próximo paso. El historial distingue herramienta preparada, envío y respuesta según la evidencia disponible. Los resultados de una herramienta compartida incluyen sus distintas participaciones. **Detener evaluación** se aplica al caso seleccionado: * Muestra los nombres de los momentos que todavía no se han enviado. * Guarda quién lo solicitó, cuándo y el motivo opcional. * Cancela esperas y recordatorios pendientes de esa participación. * Bloquea activaciones posteriores desde webhooks, timers o respuestas tardías. * Conserva respuestas, historial, herramientas compartidas, tickets y planes. * Mantiene las demás participaciones del cliente en curso. Una entrega ya aceptada por el proveedor no se puede retirar. **Deteniendo** indica trabajo en proceso; puedes reintentar la solicitud. Si un proceso se interrumpe con un envío en vuelo, puede aparecer una entrega incierta que necesita revisión. No hay acción de reanudar un caso detenido. Puedes crear una evaluación nueva para ese cliente cuando la detención termine. La API usa el identificador exacto de participación: ```text theme={null} GET /v1/journeys/{id}/enrollments?limit=20 GET /v1/journeys/{id}/enrollments/{enrollmentId} POST /v1/journeys/{id}/enrollments/{enrollmentId}/stop ``` El listado devuelve `items` y, si hay más, `nextCursor`. Pasa ese valor como `cursor` para continuar. Detener admite `{"reason":"Compra cancelada"}` y una clave de idempotencia. Apagar el viaje completo es una operación distinta de detener una participación. ## Versiones y compatibilidad La API nueva declara `authoringVersion: 2`, `startMode`, `moments` y `recipients`. El admin usa el formulario nuevo para esos viajes. Los contratos anteriores conservan su editor y reglas, incluidos sus eventos y snapshots. Para adoptar v2, crea un viaje nuevo; cambiar el número de contrato de una definición existente se rechaza. Cambiar una configuración de comportamiento crea una versión nueva para futuras participaciones. Las que ya comenzaron conservan su configuración. Las credenciales y los mapeos de conexión, junto con el interruptor de la definición son ajustes operativos compartidos, no una forma de reactivar un caso detenido. ## API, SDKs y MCP La API de administración y los SDKs usan la clave secreta de la empresa. La entrada pública del cliente es independiente: `GET` y `POST /v1/journey-entries/{journeyId}` preparan el acceso; solo una respuesta válida guardada confirma el inicio. Los SDKs ofrecen listado, detalle, detención y configuración de conexiones. El listado y el detalle incluyen `folderId` y `momentFolders`, y `journeyFolders` consulta y activa la organización en carpetas. En MCP puedes usar `create_journey`, `update_journey`, `list_journey_evaluations`, `get_journey_evaluation` y `stop_journey_evaluation`, junto con las herramientas de conexión, `get_journey_folders_status` y `organize_journey_folders`. Las operaciones que detienen o reemplazan credenciales requieren confirmación explícita. Para empezar sin escribir la definición completa, el agente puede consultar `woku_guide` con `topic=customer_journeys`, proponer los momentos con `propose_journey` y guardar un viaje apagado con `create_journey_from_brief` tras tu confirmación. `upload_woku_media` importa la imagen o video MP4 y `set_journey_moment_media` lo adjunta al momento Woku correspondiente. [Consulta los caminos de subida según el agente](/docs/mcp/tools#crear-un-woku-o-viaje-con-media). Configura contenido de webhook, variables localizadas, campos del cliente, imagen por URL, carpetas y trackers en la [guía de integración de cuatro momentos](/docs/development/journey-integration). El contenido manual o de webhook es independiente del avance; el contenido dinámico crea una herramienta por participación. # NPS Source: https://woku.app/docs/core-concepts/nps Aprende a configurar herramientas NPS: mensaje, audiencia y formas de compartir Una **herramienta NPS** (NPS Tool) es la plantilla que tu empresa configura una vez y reutiliza cada vez que necesita medir la lealtad de un grupo de clientes. Cada respuesta que recibe queda asociada a esa herramienta, lo que te permite separar mediciones por canal, audiencia o momento. Una misma empresa puede tener varios NPS Tools al mismo tiempo. Por ejemplo: * NPS post compra. * NPS post evento. * NPS de clientes recurrentes. * NPS interno para colaboradores. Cada uno mide algo distinto, y por eso es valioso mantenerlos separados. ## Mensaje El **mensaje** es la pregunta o frase que verá el cliente antes de calificar. Es lo único que debes redactar al crear el NPS, y es lo que más influye en la calidad de la respuesta. Algunas recomendaciones: * Sé breve. Una sola frase es suficiente. * Mantén el espíritu del NPS: pregunta por la probabilidad de recomendación, no por la satisfacción puntual. * Adapta el tono a la audiencia. No es lo mismo dirigirse a un cliente corporativo que a un asistente de un evento. Ejemplos: * "¿Qué tan probable es que recomiendes nuestros talleres a un colega?" * "¿Recomendarías este producto a un amigo?" * "En una escala de 0 a 10, ¿qué tan probable es que vuelvas a trabajar con nosotros?" ## Audiencia La **audiencia** identifica al grupo de personas al que está dirigido el NPS. Te sirve para no mezclar mediciones que responden a contextos distintos, y para filtrar los reportes con facilidad cuando tu empresa empieza a tener varios NPS Tools. ## Escala 0 a 10 La escala es fija y no se configura. Va de 0 a 10 y se clasifica automáticamente: | Puntaje | Categoría | | - | - | | 0 a 6 | Detractor | | 7 a 8 | Pasivo | | 9 a 10 | Promotor | El cálculo del puntaje NPS final también es automático: **% Promotores - % Detractores**. ## Reseña opcional Después de elegir su puntaje, el cliente puede dejar un comentario en **texto** o en **audio**, igual que en un woku. Esto convierte cada respuesta en un dato cuantitativo (el número) y cualitativo (el por qué) al mismo tiempo. El cliente también puede elegir entre identificarse con su correo o responder de forma **anónima**. Si responde anónimo, no se le pide email. ## Ajustes de respuesta En **Editar** hay dos ajustes que puedes cambiar aunque el NPS ya tenga respuestas: * **Exigir email para responder**: solo se aceptan respuestas identificadas. * **Una respuesta por cliente**: cada cliente identificado responde una sola vez. Si lo intenta de nuevo, ve un mensaje que le confirma que ya respondió, también por WhatsApp. Las respuestas anónimas no cuentan. Cuando ya hay respuestas, el texto de la pregunta queda fijo, para que cada respuesta siga correspondiendo a la pregunta que se hizo. ## Carpetas Una herramienta NPS puede vivir en una **carpeta**, junto con wokus, CSAT y CES, y moverse entre carpetas sin perder sus respuestas. Al crearla por la API indica `folderId`. Lee la guía [Carpetas y herramientas](/docs/guides/folders-and-tools). ## Compartir Compartir un NPS funciona igual que compartir un woku. Tienes tres formas: ### Código QR Ideal para imprimir en folletos, pegar en un tótem al final de un evento, o mostrarlo en pantalla al cierre de una presentación. ### Enlace Útil para enviar por chat, WhatsApp, dentro del email transaccional que tu empresa ya manda al cliente, o como botón en tu propio sitio. ### Envío masivo por correo Pega un listado de correos desde Excel o Google Sheets en la ventana de envío y la aplicación se encarga del resto. Recibirás una notificación cuando todos los correos hayan sido enviados, con el detalle de aquellos que no se pudieron entregar. ## Reportes Desde la aplicación administrativa puedes consultar: * Puntaje NPS de la herramienta. * Distribución de promotores, pasivos y detractores. * Listado completo de respuestas con sus comentarios. * Exportación a CSV. Si necesitas integrar los datos en tus propios dashboards, los mismos reportes están disponibles desde la API. Revisa los endpoints `GET /v1/reports/company-nps` y `GET /v1/reports/nps-tool/{npsToolId}` en la **Guía de Integración API**. # woku Source: https://woku.app/docs/core-concepts/woku Aprende sobre las características de un woku: imagen, nombre y compartir Un woku es una herramienta diseñada para capturar la opinión de tus clientes de manera rápida y sin interrumpir su experiencia. ‍Un woku se aplica cuando el cliente aún está viviendo el momento, lo que permite capturar su emocionalidad y obtener una respuesta más auténtica y genuina. ## Imágen La imagen que acompaña un woku es crucial, ya que representa el momento que se desea evaluar y es lo primero que verán los clientes. Se recomienda que la imagen sea cuadrada, de 1080 x 1080 píxeles, y en formato SVG, PNG, JPG o GIF. A continuación, las tres opciones principales para elegir la imagen: **Imagen del momento:** Debe ser una foto que capture el instante evaluado, como un evento, una capacitación o un producto. Incluso puede ser una selfie con tu cliente. La imagen debe ser de buena calidad, incluir personas y tener los elementos clave centrados. A continuación, te mostramos ejemplos reales de cómo nuestros clientes han capturado los momentos clave que desean evaluar mediante una imagen. ![Audiencia y presentador en el escenario durante el evento 'Encuentro Ecosistema CNP 2024', con pantallas iluminadas y una atmósfera de iluminación púrpura.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/ejemplo-evento-1.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=3e64be0ce526efc35e2f21ee0ab71969) **Encuentro Ecosistema Santiago - Kutamma** ![Ceremonia de graduación en el escenario de la Universidad de Concepción, con graduados y autoridades sentados frente a una cortina azul con el logo de la universidad.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/ejemplo-ceremonia.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=3d0d974bb6ea4d516d4bb1eb143ca302) **Ceremonia de Titulación - Facultad de Ingeniería de la Universidad de Concecpción** ![Frascos de paté vegetal de la marca Bagán en diferentes sabores, dispuestos sobre un fondo blanco.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/ejemplo-pate.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=8f1085448f8c7c7a0f3f4168441600bf) **Paté Vegetal - Bagán** ![Primer plano en blanco y negro de una mano usando un guante de malla metálica mientras corta carne asada junto a vegetales a la parrilla.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/ejemplo-asadores.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=2ff80474e4bb04a0298ed5f482a04900) **Campeonato de asadores - Estadio Español de Chiguayante** ![Grupo de personas sonriendo y posando para una selfie en una sala de reuniones, con laptops y documentos en la mesa.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/ejemplo-selfie.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=3db44ce76765dbb16529e8076f8edac7) **Selfie de Capacitación de Incuba UdeC - woku** **Imagen tipo afiche:** Es una imagen diseñada con colores, tipografías e íconos alineados a tu marca. El texto debe ser breve para no abrumar, y debe haber un margen de 80 píxeles en cada lado para evitar que el contenido importante quede cortado. A continuación, algunos ejemplos reales de cómo nuestros clientes han diseñado sus imágenes tipo afiche para representar los momentos que desean evaluar. ![Afiche promocional del evento 'Despega: Ciclo de Formación', con un diseño de cohete despegando, dirigido por Óscar Sánchez, programado para el 23 de octubre de 2024.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/ejemplo-pitch.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=5affcb414dcb84326615bf26db696ee4) **Sesión de Pitch del programa Despega - Gearbox** ![Afiche del 'Encuentro Ciencia-Empresa UCSC', programado para el martes 9 de julio a las 19 horas en Hacienda Patagonia, San Pedro de la Paz. Incluye detalles del evento y una foto del lugar con asistentes.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/ejemplo-ciencia-empresa.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=3e8daff042bbcb64b0f44036bfec9c7e) **Encuentro Ciencia Empresa - Dirección de Innovación de la Universidad Católica de la Santísima Concepción** ![Afiche de 'Asesoría Psicolaboral BASIC' con la psicóloga Valentina Burboa, en un diseño minimalista con fondo blanco y detalles en azul.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/ejemplo-psicolaboral.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=dee546a13d0e87cb90828f9d0cf16cf8) **Asesoría Psicolaboral - Laborally** Es fundamental que la imagen sea atractiva, ya que esto captará el interés del cliente y lo motivará a interactuar y dejar su opinión. ## Nombre El nombre del woku debe identificar claramente el aspecto que se está evaluando, siendo descriptivo y conciso. Debe contener entre 4 y 140 caracteres para asegurar que sea fácil de leer y entender. Evita formular el nombre como una pregunta para no influir en las respuestas del cliente. Un buen nombre ofrece una referencia clara sin inducir interpretaciones específicas. A continuación, se muestran los nombres que acompañan a los ejemplos de las imágenes de la sección anterior. **Nombre: Encuentro Ecosistema Santiago** ![Audiencia y presentador en el escenario durante el evento 'Encuentro Ecosistema CNP 2024', con pantallas iluminadas y una atmósfera de iluminación púrpura.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/ejemplo-evento-1.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=3e64be0ce526efc35e2f21ee0ab71969) **Encuentro Ecosistema Santiago - Kutamma** ‍**Nombre: Ceremonia de Titulación Metalúrgica, Minas y Química UdeC**‍ ![Ceremonia de graduación en el escenario de la Universidad de Concepción, con graduados y autoridades sentados frente a una cortina azul con el logo de la universidad.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/ejemplo-ceremonia.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=3d0d974bb6ea4d516d4bb1eb143ca302) **Ceremonia de Titulación - Facultad de Ingeniería de la Universidad de Concecpción** **Nombre: Bagán! Paté vegetal** ![Frascos de paté vegetal de la marca Bagán en diferentes sabores, dispuestos sobre un fondo blanco.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/ejemplo-pate.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=8f1085448f8c7c7a0f3f4168441600bf) **Paté Vegetal - Bagán** **Nombre: Tercer Campeonato de Asadores** ![Primer plano en blanco y negro de una mano usando un guante de malla metálica mientras corta carne asada junto a vegetales a la parrilla.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/ejemplo-asadores.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=2ff80474e4bb04a0298ed5f482a04900) **Campeonato de asadores - Estadio Español de Chiguayante** **Nombre: Presentación woku** ![Grupo de personas sonriendo y posando para una selfie en una sala de reuniones, con laptops y documentos en la mesa.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/ejemplo-selfie.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=3db44ce76765dbb16529e8076f8edac7) **Selfie de Capacitación de Incuba UdeC - woku** **Nombre: Sesión 10 - Pitch** ![Afiche promocional del evento 'Despega: Ciclo de Formación', con un diseño de cohete despegando, dirigido por Óscar Sánchez, programado para el 23 de octubre de 2024.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/ejemplo-pitch.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=5affcb414dcb84326615bf26db696ee4) **Sesión de Pitch del programa Despega - Gearbox** **Nombre: Encuentro Ciencia-Empresa UCSC** ![Afiche del 'Encuentro Ciencia-Empresa UCSC', programado para el martes 9 de julio a las 19 horas en Hacienda Patagonia, San Pedro de la Paz. Incluye detalles del evento y una foto del lugar con asistentes.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/ejemplo-ciencia-empresa.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=3e8daff042bbcb64b0f44036bfec9c7e) **Encuentro Ciencia Empresa - Dirección de Innovación de la Universidad Católica de la Santísima Concepción** **Nombre: Asesoría Psicolaboral BASIC** ![Afiche de 'Asesoría Psicolaboral BASIC' con la psicóloga Valentina Burboa, en un diseño minimalista con fondo blanco y detalles en azul.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/ejemplo-psicolaboral.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=dee546a13d0e87cb90828f9d0cf16cf8) **Asesoría Psicolaboral - Laborally** ## Carpetas Puedes ordenar tus wokus en **carpetas** y subcarpetas, junto con tus herramientas NPS, CSAT y CES. Mover un woku a otra carpeta no cambia sus reseñas ni su enlace. Lee la guía [Carpetas y herramientas](/docs/guides/folders-and-tools). ## Compartir Para que el cliente pueda evaluar el woku, es necesario compartirlo con ellos. Es importante hacerlo cuando la experiencia esté por finalizar o haya terminado, para que los clientes puedan opinar con perspectiva sobre su vivencia. Para compartir el woku, ingresa y selecciona el botón de compartir. ![Interfaz de woku mostrando el woku 'Taller de Trabajo en Equipo' sin reseñas ni calificaciones, con las opciones para editar, eliminar, descargar CSV, generar un reporte y compartir el woku. También se visualiza un gráfico de barras que representa opiniones positivas versus reseñas con oportunidades de mejora, aunque en este caso no se han recibido reseñas aún.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/compartir-woku-vista.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=d22591764b8648f7073da1f6d8f81ef1) **Vista de woku: Taller de Trabajo en Equipo sin reseñas** Dispones de varias formas de hacerlo: ![Interfaz de woku mostrando las opciones para compartir el woku 'Taller de Trabajo en Equipo'. Se incluyen un código QR para escanear, botones para copiar la URL, descargar el código QR y enviar el woku a múltiples correos electrónicos. También hay un campo para ingresar un correo electrónico y la opción de enviar o cancelar el envío del woku.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/compartir-woku-opciones.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=6a2290bc5dc9df07342755dd01d7772c) **Opciones para compartir woku: Taller de Trabajo en Equipo** ### Código QR Puedes mostrar el código QR directamente desde la aplicación de woku en tu celular o computadora. También tienes la opción de descargarlo para imprimirlo o incluirlo en materiales visuales. Esta opción es especialmente útil en presentaciones, ya que puedes mostrar el QR al final para que los asistentes lo escaneen fácilmente. También puedes colocarlo en un tótem en eventos o áreas de atención al cliente, permitiendo que las personas lo escaneen y evalúen su experiencia de manera rápida y sencilla. ### Enlace Compartir el woku mediante un enlace es ideal para sesiones online, ya que puedes enviarlo directamente por el chat de la videollamada. También es muy práctico para enviarlo por WhatsApp, ya sea en grupos o en mensajes directos, facilitando llegar a los clientes de forma personal o en espacios compartidos. ![Vista de un mensaje de WhatsApp que invita a un usuario a calificar el 'Taller de Trabajo en Equipo' mediante un enlace de woku. El mensaje incluye el texto '¡Queremos saber tu opinión!' y un enlace directo a la evaluación en review.woku.app.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/whatsapp-compartir.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=55cc3a368e6642ece1d52318003f23b6) **woku compartido a través de un enlace en la aplicación móvil de WhatsApp** ### Mails Si necesitas realizar envíos masivos, puedes compartir el woku a través de correos electrónicos. Copia el listado de correos desde una hoja de cálculo (como Excel o Google Sheets) y pégalo directamente en la ventana emergente de envío. ![Interfaz de la aplicación de woku en computadora, mostrando la ventana emergente para ingresar una lista de emails para el envío masivo del woku. Incluye un campo de texto para los correos y botones de 'Enviar' y 'Descartar'.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/compartir-mail-masivo.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=5a6ad5686e48ced67f892b3c3971e7a4) **Interfaz de woku para compartir un woku mediante el envío de emails masivos** Una vez que presiones el botón enviar, los correos comenzarán a enviarse automáticamente. Este proceso puede tomar algún tiempo dependiendo de la cantidad de destinatarios. Si cierras la ventana emergente, los correos seguirán enviándose en segundo plano. Cuando todos los correos hayan sido enviados, recibirás una alerta en la parte inferior izquierda de la pantalla de la aplicación de woku. ![Interfaz de la aplicación de woku en computadora para compartir un woku con opciones de código QR, enlace URL, envío a múltiples emails y envío a un solo correo electrónico. En la parte inferior izquierda, aparece una alerta que indica 'Emails enviados con éxito'.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/confirmacion-emails-enviados.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=a7077d6e00a2856b04b6ab3a11840fae) **Alerta de que fueron enviado los emails con éxito** Además, recibirás un correo de confirmación indicando que el envío fue exitoso. Si hubo algún problema en el envío de ciertos correos, recibirás un correo con el listado de aquellos que no se pudieron enviar debido a algún error. ![Correo de confirmación de envío de emails](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/mail-confirmacion-exitosa.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=a7ce993d82361f16329613269bf63b0a) **Mail de confirmación de envio existoso** Para enviar el woku a una sola persona, solo debes ingresar su correo en el campo correspondiente y enviarlo. En este caso no te llegará un mail de confirmación. ![Interfaz de la aplicación de woku en computadora para compartir un woku mediante diferentes métodos: código QR, enlace URL, envío a múltiples emails y envío a un solo correo electrónico. Incluye opciones para copiar el URL, descargar el QR y un campo destacado para ingresar un correo electrónico individual.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/compartir-mail-individual.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=3b7be8a808f0e09b8c612f5e68ca864f) **Compartir el woku mediante un correo electrónico** # Guía de Integración API Source: https://woku.app/docs/development/api Documentación completa de la API v1 de woku: wokus, NPS, CSAT, CES, formularios, flows, invitaciones, capturas del SDK móvil, trackers externos, destinos de tickets y planes de acción > [!NOTE] > > **Disponible en todos los planes, incluido el gratuito.** La API v1 y los SDK oficiales están habilitados para toda cuenta de woku. [Conoce los planes](https://woku.app/pricing). Esta guía te muestra cómo integrar la API de **woku** en tus propias aplicaciones para automatizar la creación de **wokus**, capturar respuestas de todas las herramientas de feedback, enviar encuestas por correo o WhatsApp y enriquecer tus datos con identificadores de tus sistemas internos. > [!NOTE] > > Esta guía aplica **solo a la versión v1** de la API. Corresponde exactamente a la pestaña **API Reference** que ves en la parte superior de la documentación. Para el comportamiento histórico (rutas sin el prefijo `/v1/`), cambia el selector de versión a **v0**. ## Referencia interactiva Toda la API está documentada de forma interactiva en la pestaña **API Reference** de esta misma documentación. Allí puedes ver cada endpoint con su esquema completo, ejecutarlo en vivo desde el navegador y copiar ejemplos en tu lenguaje preferido. Esta guía es complementaria: te explica el flujo y el "por qué" de cada llamada para que la integración te tome el menor tiempo posible. ## SDKs oficiales Si trabajas en JavaScript/TypeScript o Python, no necesitas armar las solicitudes a mano. Los **SDK oficiales de servidor** envuelven esta misma API v1 con un cliente tipado que suma reintentos, idempotencia y paginación automática. Inicializas el cliente con tu Clave de Compañía una sola vez: ```ts JavaScript theme={null} import { Woku } from '@wokuapp/sdk'; const woku = new Woku({ apiKey: process.env.WOKU_API_KEY }); const tracker = await woku.trackers.create({ name: 'Tienda #1', system: 'retail' }); ``` ```python Python theme={null} from woku import Woku woku = Woku(api_key="sk_...") tracker = woku.trackers.create({"name": "Tienda #1", "system": "retail"}) ``` * **JavaScript / TypeScript:** [SDK de JavaScript](/docs/development/sdk-javascript) (`@wokuapp/sdk`) * **Python:** [SDK de Python](/docs/development/sdk-python) (`woku`) Ambos autentican con la misma Clave de Compañía descrita en [Autenticación](#autenticación). ## Introducción La API de woku te permite operar de forma programática todas las herramientas de feedback: **wokus**, **NPS**, **CSAT**, **CES**, **formularios** y **flows**, además de **invitaciones**, **trackers externos**, **destinos de tickets** y **planes de acción**. Los casos de uso típicos: 1. **Crear wokus automáticamente** cuando ocurre un evento en tu aplicación (por ejemplo, cierre de una venta, fin de una sesión de capacitación, entrega de un producto). 2. **Capturar respuestas** directamente desde tu interfaz o backend, sin redirigir al cliente al sitio de woku: calificaciones y reseñas de wokus, puntajes NPS, CSAT y CES, y respuestas de formularios. 3. **Enviar encuestas por correo o WhatsApp** a listas de destinatarios desde tu backend. 4. **Capturar feedback desde tu app móvil** con un único endpoint idempotente, pensado para el SDK de React Native. 5. **Etiquetar herramientas** con identificadores de tus sistemas (CRM, ERP, ticketing) para luego buscarlas cruzadas. 6. **Extraer respuestas y reportes** hacia tus dashboards y sistemas internos. 7. **Configurar a dónde llegan los tickets de soporte** (Zendesk, un servicio propio o correo) y cómo se enrutan según tus trackers. 8. **Gestionar planes de acción generados por IA**: aprobarlos y trabajarlos dentro de woku. Todas las llamadas son HTTP con JSON o `multipart/form-data` y responden con estructuras consistentes. ### URL Base ``` https://clientapi.woku.app ``` Todos los endpoints v1 viven bajo el prefijo `/v1/`. ### Autenticación Cada empresa registrada en woku tiene una **Clave de Compañía** que se incluye en el header `Authorization` de cada solicitud: ``` Authorization: Bearer ``` La clave la obtiene el propietario de la empresa desde la sección **Información** de la empresa, en la aplicación administrativa: [https://admin.woku.app](https://admin.woku.app/) ![Interfaz de la aplicación woku en la sección de 'Información' de la empresa. Se muestran los datos de la compañía, incluyendo el logo, nombre, página web y enlaces a redes sociales como Instagram, Facebook, LinkedIn, X (ex Twitter), TikTok y GitHub. En la parte inferior, se destaca la opción 'Obtener Clave', que permite copiar la clave de la compañía para clientapi.woku.app.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/api-clave-empresa.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=9577faa826819f297e9559f4bd97837a) **Vista de la ventana de información de la empresa.** > [!TIP] > > La misma clave que usabas en v0 funciona para v1. No necesitas regenerarla para migrar. ## Compañía ### Obtener la compañía actual Recupera los datos de la empresa asociada a la Clave de Compañía. Útil para validar que tu integración esté autenticando con la cuenta correcta. **Endpoint** ``` GET /v1/companies/me ``` **Headers** * `Authorization: Bearer ` **Respuestas** * `200 OK`: Devuelve el objeto de la compañía. * `403 Forbidden`: La clave no es válida o no tiene permiso. ## Wokus Las funciones de **wokus** te permiten crear, consultar, calificar y compartir wokus de forma programática. ### Crear un woku con URL de archivo Crea un woku usando una imagen o video alojado en una URL pública (CDN, S3, ImageKit, etc.). **Endpoint** ``` POST /v1/wokus ``` **Headers** * `Content-Type: application/json` * `Authorization: Bearer ` **Body** ```json theme={null} { "description": "Customer Service Experience - Store #123", "fileUrl": "https://cdn.example.com/images/product-image.jpg", "folderSecondaryKey": "store-123", "parentFolderSecondaryKey": "region-north", "clientEmail": "customer@example.com", "clientPhone": 56912345678 } ``` **Campos** * `description` *(string, obligatorio)*: Entre 3 y 140 caracteres. * `fileUrl` *(string, obligatorio)*: URL pública de una imagen o video (preferentemente `.mp4`). * `folderSecondaryKey` *(string, opcional)*: Clave de la carpeta donde se almacena el woku. * `parentFolderSecondaryKey` *(string, opcional)*: Clave de la carpeta padre. No puede ser la misma que `folderSecondaryKey`. * `clientEmail` *(string, opcional)*: Email del cliente asociado. * `clientPhone` *(number, opcional)*: Número de WhatsApp. **Respuestas** * `201 Created`: Devuelve el objeto del woku creado. * `400 Bad Request`: El body no pasó la validación. * `403 Forbidden`: Clave inválida. ### Crear un woku con archivo (multipart) Cuando el archivo está en tu propio storage o tu cliente sube la imagen directamente desde un formulario, usa el endpoint con `multipart/form-data`. **Endpoint** ``` POST /v1/wokus/form-data ``` **Headers** * `Content-Type: multipart/form-data` * `Authorization: Bearer ` **Form fields** * `file` *(binary, obligatorio)*: Archivo de imagen o video. * `description` *(string, obligatorio)*: Entre 3 y 140 caracteres. * `folderSecondaryKey` *(string, opcional)*. * `parentFolderSecondaryKey` *(string, opcional)*. * `clientEmail` *(string, opcional)*. * `clientPhone` *(string, opcional)*. **Respuestas** * `201 Created`: Woku creado. * `400 Bad Request`: Validación fallida (formato de archivo, tamaño, campos requeridos). * `403 Forbidden`: Clave inválida. ### Subir media para reutilizar en un Woku o viaje Si necesitas el `fileId` antes de crear una herramienta, envía el archivo en `file` a `POST /v1/woku-media` con `multipart/form-data` y la Clave de Compañía. La respuesta `201` contiene `fileId`, `filename` y `type` (`image` o `video`). Usa ese `fileId` en `create_woku` o `set_journey_moment_media` del MCP, o en `toolSpec.fileId` de un momento Woku del API. Se aceptan imágenes reales JPEG, PNG, WebP o GIF de hasta 10 MB, que se normalizan a WebP dentro de 1080 × 1080 píxeles sin cambiar su proporción, y videos MP4 de hasta 25 MB. El servicio inspecciona el contenido, no confía en la extensión ni en el `Content-Type` enviado. Un MP4 debe tener un frame de video decodificable. Un archivo inválido devuelve `400`; una solicitud multipart que supera 25 MB devuelve `413`. Un archivo local de Codex o Claude Code puede subirlo por terminal; [consulta el ejemplo](../mcp/tools#crear-un-woku-o-viaje-con-media). ### Obtener los datos de un woku Recupera el woku junto con sus calificaciones y reseñas. **Endpoint** ``` GET /v1/wokus/:id/review ``` **Headers** * `Authorization: Bearer ` **Path params** * `id` *(string, obligatorio)*: Identificador del woku. **Respuestas** * `200 OK`: Objeto del woku con sus reseñas. * `403 Forbidden`: Clave inválida. * `404 Not Found`: No existe un woku con ese ID en tu empresa. ### Listar los wokus de la empresa Lista paginada de los wokus de tu empresa. **Endpoint** ``` GET /v1/wokus ``` **Query params** * `page` *(number, opcional)*: Por defecto 1. * `limit` *(number, opcional)*: Por defecto 20. **Respuestas** * `200 OK`: Lista paginada de wokus. * `403 Forbidden`: Clave inválida. ### Obtener un woku con estadísticas Devuelve un woku con sus estadísticas agregadas de reseñas. **Endpoint** ``` GET /v1/wokus/:id ``` **Respuestas** * `200 OK`: Woku con estadísticas. * `403 Forbidden`: El woku pertenece a otra empresa. * `404 Not Found`: No existe el woku. ### Listar las reseñas de un woku Reseñas en texto y audio, paginadas, de la más reciente a la más antigua. Las reseñas de audio exponen su transcripción. Nunca se incluyen datos de contacto del cliente, solo `clientId`. Cada reseña incluye `responseChannel`: el canal por el que llegó (`whatsapp`, `email`, `review-app`, `widget-web`, `mobile-sdk`, `api`, o un valor personalizado definido por ti); es `null` en respuestas históricas. **Endpoint** ``` GET /v1/wokus/:id/reviews ``` **Query params** * `page` *(number, opcional)*. * `limit` *(number, opcional)*. **Respuestas** * `200 OK`: Lista paginada de reseñas. * `403 Forbidden`: El woku pertenece a otra empresa. * `404 Not Found`: No existe el woku. ### Calificar con una reseña en texto Agrega una calificación de 1 a 5 estrellas con un comentario escrito. **Endpoint** ``` POST /v1/wokus/:id/textnotes ``` **Headers** * `Content-Type: application/json` * `Authorization: Bearer ` **Body** ```json theme={null} { "qualification": 5, "description": "Excellent service! The staff was very helpful.", "clientEmail": "customer@example.com", "clientPhone": 56912345678, "anonymous": false } ``` **Campos** * `qualification` *(integer, obligatorio)*: Valor entre 1 y 5. * `description` *(string, obligatorio)*: Reseña en texto, máximo 3000 caracteres. * `clientEmail` *(string, opcional)*: Si no se entrega, `anonymous` debe ser `true`. * `clientPhone` *(number, opcional)*. * `anonymous` *(boolean, opcional)*: Por defecto `false`. * `responseChannel` *(string, opcional, máx 48)*: Canal por el que llegó la respuesta. Valores canónicos: `whatsapp`, `email`, `review-app`, `widget-web`, `mobile-sdk`, `api`. También puedes enviar tu propio valor personalizado, que reemplaza el valor por defecto. Por defecto `api`. **Respuestas** * `201 Created`: Reseña registrada (`held: false`). Si la empresa no tiene créditos de opiniones, la respuesta trae `held: true`: la opinión queda en espera, el `id` corresponde a esa espera y no a una reseña, y se registra sola cuando la empresa recarga créditos. * `400 Bad Request`: Validación fallida. * `403 Forbidden`: Clave inválida. * `404 Not Found`: No existe el woku. ### Calificar con una reseña en audio Sube un archivo de audio junto con la calificación. **Endpoint** ``` POST /v1/wokus/:id/voicemails ``` **Headers** * `Content-Type: multipart/form-data` * `Authorization: Bearer ` **Form fields** * `file` *(binary, obligatorio)*: Audio. Recomendado `.mp4` o `.wav`. * `qualification` *(string `"1"`, `"5"`, obligatorio)*. * `clientEmail` *(string, opcional)*. * `clientPhone` *(string, opcional)*. * `anonymous` *(string `"true"` o `"false"`, opcional)*. * `responseChannel` *(string, opcional, máx 48)*: Canal por el que llegó la respuesta. Valores canónicos: `whatsapp`, `email`, `review-app`, `widget-web`, `mobile-sdk`, `api`. También puedes enviar tu propio valor personalizado, que reemplaza el valor por defecto. Por defecto `api`. **Respuestas** * `201 Created`: Reseña registrada (`held: false`). Si la empresa no tiene créditos de opiniones, la respuesta trae `held: true`: la opinión queda en espera, el `id` corresponde a esa espera y no a una reseña, y se registra sola cuando la empresa recarga créditos. * `400 Bad Request`: Validación fallida. * `403 Forbidden`: Clave inválida. * `404 Not Found`: No existe el woku. ### Compartir un woku por correo Envía el woku a uno o varios destinatarios. Es el mismo flujo que se inicia desde la interfaz de compartir. **Endpoint** ``` POST /v1/wokus/:id/share ``` **Headers** * `Content-Type: application/json` * `Authorization: Bearer ` **Body (destinatario único)** ```json theme={null} { "clientEmail": "customer@example.com" } ``` **Body (múltiples destinatarios)** ```json theme={null} { "clientEmails": ["customer1@example.com", "customer2@example.com"] } ``` > [!TIP] > > Debes enviar **uno u otro** de los dos campos, no ambos. **Respuestas** * `200 OK`: Envío encolado. * `400 Bad Request`: Validación fallida (correo mal formado, ambos campos vacíos, etc.). * `403 Forbidden`: Clave inválida. ## Capturas del SDK móvil Endpoint único de ingesta pensado para el [SDK de React Native](/docs/development/sdk-react-native). Recibe una captura normalizada y la enruta según su `kind`: `woku` (reseña de un woku), `nps`, `csat` o `ces`. El canal de la respuesta queda sellado como `mobile-sdk` del lado del servidor. **Endpoint** ``` POST /v1/captures ``` Acepta dos tipos de contenido: * `application/json`: capturas de texto o calificación. El body es la captura. * `multipart/form-data`: capturas con audio. El archivo va en el campo `file` y la captura como JSON en el campo `payload`. El audio está disponible para `woku` y `nps`; los comentarios de audio aún no están soportados para `csat` ni `ces`. **Body (JSON)** ```json theme={null} { "id": "3f2c9a2e-8b1d-4f6a-9c3e-1a2b3c4d5e6f", "kind": "woku", "targetId": "671000000000000000000001", "rating": 5, "comment": "Excelente atención en la tienda.", "respondent": { "email": "customer@example.com" } } ``` **Campos** * `id` *(string, opcional)*: Identificador generado por el cliente. Se usa como clave de idempotencia. * `kind` *(string, obligatorio)*: `woku`, `nps`, `csat` o `ces`. * `targetId` *(string)*: Id del woku (obligatorio para `woku`), del NPS Tool (opcional para `nps`) o del CSAT/CES Tool (obligatorio para `csat` y `ces`). * `rating` *(integer, opcional)*: Calificación del woku, de 1 a 5. * `score` *(integer, opcional)*: Puntaje NPS de 0 a 10, o CSAT/CES de 1 a 5. * `comment` *(string, opcional, máx 3000)*: Comentario en texto. Obligatorio en las capturas de texto de un woku. * `respondent` *(object, opcional)*: `email`, `phone`, `externalId`. Sin identificador, la captura queda anónima. **Idempotencia** La clave de idempotencia se toma del header `X-Woku-Idempotency-Key` o, en su ausencia, del campo `id` del body. Si el mismo envío se reintenta (por ejemplo, por la cola offline del SDK), la API devuelve el resultado ya registrado en lugar de crear un duplicado. **Respuestas** * `201 Created`: Captura aceptada. Devuelve `id`, `kind`, `remoteId` y `status: "accepted"`. * `400 Bad Request`: Validación fallida (falta `targetId`, audio en `csat` o `ces`, `payload` malformado). * `403 Forbidden`: Clave inválida. * `409 Conflict`: La herramienta acepta una respuesta por cliente y este cliente ya respondió (`code: "ALREADY_RESPONDED"`). ## Respuestas NPS Puedes capturar puntajes NPS y extraer las respuestas individuales hacia tus sistemas. Los reportes agregados están en la sección [Reportes NPS](#reportes-nps). ### Capturar un puntaje NPS **Endpoint** ``` POST /v1/nps ``` **Body** ```json theme={null} { "score": 9, "npsToolId": "671000000000000000000001", "clientEmail": "customer@example.com" } ``` **Campos** * `score` *(integer, obligatorio)*: De 0 a 10. * `npsToolId` *(string, opcional)*: NPS Tool específico. Si se omite, el puntaje se registra a nivel de compañía. * `clientEmail` *(string, opcional)*: Si no se entrega, la respuesta queda anónima. * `anonymous` *(boolean, opcional)*. * `responseChannel` *(string, opcional, máx 48)*: Canal por el que llegó la respuesta. Valores canónicos: `whatsapp`, `email`, `review-app`, `widget-web`, `mobile-sdk`, `api`. También puedes enviar tu propio valor personalizado, que reemplaza el valor por defecto. Por defecto `api`. **Respuestas** * `201 Created`: Devuelve `npsId` y el objeto de la respuesta. * `400 Bad Request`: Validación fallida. * `403 Forbidden`: El NPS Tool no pertenece a tu empresa. * `409 Conflict`: La herramienta acepta una respuesta por cliente y este cliente ya respondió (`code: "ALREADY_RESPONDED"`). ### Agregar una reseña a un puntaje NPS Una vez creado el puntaje, puedes adjuntarle una reseña opcional en texto o audio. **Endpoints** ``` POST /v1/nps/:id/textnotes POST /v1/nps/:id/voicemails ``` * **Texto**: body JSON `{ "description": "..." }`, máximo 3000 caracteres. * **Audio**: `multipart/form-data` con el archivo en el campo `file` (m4a, aac o mp4). La transcripción se genera en el servidor. **Respuestas** * `201 Created`: Reseña adjuntada. * `400 Bad Request`: Validación fallida. * `403 Forbidden`: El NPS pertenece a otra empresa. * `404 Not Found`: No existe el NPS. ### Consultar NPS Tools y respuestas Endpoints de lectura para traer los datos NPS a tus sistemas: * `GET /v1/nps-tools`: Lista paginada de los NPS Tools de tu empresa. * `GET /v1/nps-tool/:id`: Definición de un NPS Tool (para construir la pregunta). * `GET /v1/nps`: Respuestas paginadas, de la más reciente a la más antigua. * `GET /v1/nps/:id`: Una respuesta individual. `GET /v1/nps` acepta los filtros `npsToolId`, `from` y `to` (fechas ISO sobre la fecha de creación) y `withFeedback=true` (solo respuestas con reseña en texto o audio), además de `page` y `limit`. Las respuestas nunca incluyen datos de contacto del cliente, solo `clientId`. Cada respuesta incluye `responseChannel`: el canal por el que llegó (`whatsapp`, `email`, `review-app`, `widget-web`, `mobile-sdk`, `api`, o un valor personalizado definido por ti); es `null` en respuestas históricas. ## CSAT y CES Las familias **CSAT** (satisfacción, escala 1 a 5) y **CES** (esfuerzo, escala 1 a 5) son espejos exactos. Los ejemplos usan `csat`; reemplaza `csat` por `ces` y `csatToolId` por `cesToolId` para obtener la familia CES. A diferencia de NPS, el id de la herramienta es siempre obligatorio: los CSAT y CES son siempre encuestas personalizadas. ### Capturar un puntaje CSAT **Endpoint** ``` POST /v1/csat ``` **Body** ```json theme={null} { "score": 4, "csatToolId": "671000000000000000000002", "clientEmail": "customer@example.com" } ``` **Campos** * `score` *(integer, obligatorio)*: De 1 a 5. * `csatToolId` *(string, obligatorio)*: CSAT Tool que responde la encuesta. * `clientEmail` *(string, opcional)*: Si no se entrega, la respuesta queda anónima. * `anonymous` *(boolean, opcional)*. * `responseChannel` *(string, opcional, máx 48)*: Canal por el que llegó la respuesta. Valores canónicos: `whatsapp`, `email`, `review-app`, `widget-web`, `mobile-sdk`, `api`. También puedes enviar tu propio valor personalizado, que reemplaza el valor por defecto. Por defecto `api`. **Respuestas** * `201 Created`: Devuelve `csatId` y el objeto de la respuesta. * `400 Bad Request`: Validación fallida. * `403 Forbidden`: El CSAT Tool no pertenece a tu empresa. * `409 Conflict`: La herramienta acepta una respuesta por cliente y este cliente ya respondió (`code: "ALREADY_RESPONDED"`). ### Agregar un comentario a una respuesta CSAT **Endpoints** ``` POST /v1/csat/:id/textnotes POST /v1/csat/:id/voicemails ``` * **Texto**: body JSON `{ "description": "..." }`, máximo 3000 caracteres. * **Audio**: `multipart/form-data` con el archivo en el campo `file` (m4a, aac o mp4). La transcripción se genera en el servidor. **Respuestas** * `201 Created`: Comentario aceptado. * `403 Forbidden`: La respuesta pertenece a otra empresa. * `404 Not Found`: No existe la respuesta CSAT. ### Consultar tools y respuestas CSAT * `GET /v1/csat-tools`: Lista paginada de los CSAT Tools de tu empresa. * `GET /v1/csat-tool/:id`: Definición de un CSAT Tool (para construir la encuesta). * `GET /v1/csat`: Respuestas paginadas, con los filtros `csatToolId`, `from`, `to` y `withFeedback`. * `GET /v1/csat/:id`: Una respuesta individual. Cada respuesta incluye `responseChannel`: el canal por el que llegó (`whatsapp`, `email`, `review-app`, `widget-web`, `mobile-sdk`, `api`, o un valor personalizado definido por ti); es `null` en respuestas históricas. La familia CES expone exactamente los mismos endpoints: `POST /v1/ces`, `POST /v1/ces/:id/textnotes`, `POST /v1/ces/:id/voicemails`, `GET /v1/ces-tools`, `GET /v1/ces-tool/:id`, `GET /v1/ces` y `GET /v1/ces/:id`. ### Ajustes de respuesta de NPS, CSAT y CES `POST /v1/{nps,csat,ces}-tools` y `PATCH /v1/{nps,csat,ces}-tools/:id` aceptan dos ajustes, y cada herramienta los devuelve: * `anonymousDisabled` *(boolean)*: solo se aceptan respuestas identificadas (correo o teléfono). * `onlyOneResponsePerClient` *(boolean)*: cada cliente identificado responde una sola vez. Una segunda respuesta recibe `409 Conflict` con `code: "ALREADY_RESPONDED"`. Las respuestas anónimas no cuentan. Los dos se pueden cambiar aunque la herramienta ya tenga respuestas. En ese caso el `PATCH` debe traer solo estos campos, porque el texto de la encuesta queda fijo. ## Formularios Consulta y captura de **formularios** desde tus propios sistemas: renderiza el formulario con su definición, envía respuestas y extrae los resultados. ### Listar los formularios de la empresa **Endpoint** ``` GET /v1/forms ``` **Query params** * `page` *(number, opcional)*. * `limit` *(number, opcional)*. **Respuestas** * `200 OK`: Lista paginada de formularios. * `403 Forbidden`: Clave inválida. ### Obtener la definición de un formulario Devuelve el formulario activo (campos, configuración, contenido localizado) junto con el branding de la empresa, para renderizarlo en tu propia interfaz. **Endpoint** ``` GET /v1/forms/:id ``` **Respuestas** * `200 OK`: Definición del formulario. * `403 Forbidden`: El formulario pertenece a otra empresa. * `404 Not Found`: No existe o está inactivo. ### Enviar una respuesta de formulario **Endpoint** ``` POST /v1/forms/:id/responses ``` **Body** ```json theme={null} { "anonymous": false, "email": "respondent@example.com", "answers": { "field-uuid-1": "John Doe", "field-uuid-2": 5 } } ``` **Campos** * `anonymous` *(boolean, obligatorio)*. * `email` / `phone` *(string, opcional)*: Requerido según cómo identifica clientes el formulario, cuando la respuesta no es anónima. * `answers` *(object, obligatorio)*: Respuestas por id de campo. Se validan contra la definición del formulario. * `responseChannel` *(string, opcional, máx 48)*: Canal por el que llegó la respuesta. Valores canónicos: `whatsapp`, `email`, `review-app`, `widget-web`, `mobile-sdk`, `api`. También puedes enviar tu propio valor personalizado, que reemplaza el valor por defecto. Por defecto `api`. **Respuestas** * `201 Created`: Respuesta registrada. * `400 Bad Request`: Validación fallida o el formulario está cerrado. * `403 Forbidden`: El formulario pertenece a otra empresa. * `404 Not Found`: No existe o está inactivo. * `429 Too Many Requests`: El respondente está en cuarentena. ### Listar las respuestas de un formulario Paginadas, de la más reciente a la más antigua. Las respuestas exponen los valores por id de campo y nunca incluyen datos de contacto del cliente, solo `clientId`. Cada respuesta incluye `responseChannel`: el canal por el que llegó (`whatsapp`, `email`, `review-app`, `widget-web`, `mobile-sdk`, `api`, o un valor personalizado definido por ti); es `null` en respuestas históricas. **Endpoint** ``` GET /v1/forms/:id/responses ``` **Respuestas** * `200 OK`: Lista paginada de respuestas. * `403 Forbidden`: El formulario pertenece a otra empresa. * `404 Not Found`: No existe el formulario. ## Flows Un flow encadena pasos ordenados, cada uno un woku o una herramienta NPS, CSAT o CES, en una secuencia de encuesta. Es distinto de [Viajes del cliente](../core-concepts/journeys), que evalúa momentos del negocio y puede avanzar con esperas o webhooks. Con los datos del flow puedes renderizar su secuencia en tu aplicación y capturar con los endpoints existentes (`POST /v1/wokus/:id/textnotes`, `POST /v1/nps`, `POST /v1/csat`, etc.). Un flow no vive dentro de carpetas. * `GET /v1/flows`: Lista paginada de los flows de tu empresa, cada uno con sus `steps`. * `GET /v1/flows/:id`: Datos del flow: pasos en orden con sus herramientas, branding y NPS vinculado. * `POST /v1/flows`: Crea un flow con `name` y de 1 a 20 `steps`. Acepta `X-Woku-Idempotency-Key`. * `PATCH /v1/flows/:id`: Cambia el `name` o reemplaza la lista completa de `steps`. * `DELETE /v1/flows/:id`: Elimina el flow. Sus herramientas y respuestas se conservan. Cada paso es `{ "type": "woku" | "nps" | "csat" | "ces", "toolId": "" }`. Una herramienta aparece una sola vez, todas deben ser de tu empresa y un woku cerrado o de una reseña por cliente no puede ser un paso. Para un paso `nps`, el id de tu empresa como `toolId` es el NPS de la empresa. ```json theme={null} { "name": "Posventa", "steps": [ { "type": "nps", "toolId": "" }, { "type": "csat", "toolId": "" }, { "type": "woku", "toolId": "" } ] } ``` **Respuestas** * `200 OK` o `201 Created`: Datos del flow o lista paginada. * `400 Bad Request`: Pasos inválidos (repetidos, demasiados o una herramienta no permitida). * `403 Forbidden`: El flow pertenece a otra empresa. * `404 Not Found`: No existe el flow o una herramienta de los pasos. ## Invitaciones Familia homogénea de endpoints para enviar encuestas por **correo** o **WhatsApp** a una lista de hasta 100 destinatarios. Los envíos son asíncronos: la API responde de inmediato con el detalle por destinatario. **Endpoints** ``` POST /v1/nps/invitations POST /v1/csat/invitations POST /v1/ces/invitations POST /v1/forms/:id/invitations POST /v1/wokus/:id/invitations ``` **Body** ```json theme={null} { "channel": "whatsapp", "recipients": ["56912345678"], "language": "es" } ``` **Campos** * `channel` *(string, obligatorio)*: `email` o `whatsapp`. * `recipients` *(string\[], obligatorio, máx 100)*: Correos para el canal `email`; números con código de país (por ejemplo `56912345678`) para `whatsapp`. * `language` *(string, opcional)*: `es` o `en`. * `npsToolId` *(string, opcional, solo NPS)*: Si se omite, se envía la encuesta NPS a nivel de compañía. * `csatToolId` / `cesToolId` *(string, obligatorio en CSAT y CES)*. **Respuestas** * `202 Accepted`: Resumen por destinatario: `accepted` (despachados o encolados) y `rejected` con el motivo (`invalid_recipient`, `quarantined`, `insufficient_credits_or_blocked`, `send_failed`). * `400 Bad Request`: Validación fallida, o el formulario o woku está cerrado. * `403 Forbidden`: La herramienta no pertenece a tu empresa. * `404 Not Found`: No existe el formulario o el woku. > [!TIP] > > Los destinatarios mal formados no hacen fallar la solicitud completa: se reportan individualmente en `rejected` con el motivo `invalid_recipient`. ## Carpetas y herramientas Un mismo árbol de carpetas reúne wokus y herramientas NPS, CSAT y CES. La guía [Carpetas y herramientas](/docs/guides/folders-and-tools) explica el modelo; esta sección resume los endpoints. Todos usan tu Clave de Compañía. ### Carpetas * `GET /v1/folders`: lista todas las carpetas, o solo las subcarpetas de `parentFolderId`. Acepta `q` para buscar por nombre. * `POST /v1/folders`: crea una carpeta (`name`, y opcionalmente `parentFolderId` y `color`). Acepta `X-Woku-Idempotency-Key`. * `GET /v1/folders/:id`: una carpeta con su ruta, su `origin` (y `integrationProvider` en las carpetas de integración) y las estadísticas de su subárbol. * `PATCH /v1/folders/:id`: cambia `name`, `color` (`null` quita el color) o `whatsappAlertRecipients` (reemplaza los números de WhatsApp que reciben el aviso de mejoras de la carpeta, o de todas las reseñas con `allReviews: true`; `[]` los quita). * `PATCH /v1/folders/:id/move`: mueve la carpeta bajo `parentFolderId`, o a la raíz con `null`. * `DELETE /v1/folders/:id`: elimina la carpeta. Su contenido sube a la carpeta padre; no se elimina nada. * `GET /v1/folders/:id/report`: reporte con IA sobre todas las herramientas de la carpeta y sus subcarpetas (`regenerate`, `lang`). * `GET /v1/folders/:id/metrics`: cifras de cada herramienta de la carpeta y sus subcarpetas en un periodo (`days`: 7, 30, 90 o 0 para todo el historial) frente al periodo anterior, con las sumas diarias y el histograma de notas. * `GET /v1/folders/:id/csv`: CSV con una fila por respuesta, o solo las de un período con `from` y `to` (ISO 8601, `to` excluido). * `GET /v1/folders/:id/pdf`: reporte de la carpeta en PDF, con un desglose por tipo (`lang`). ### Herramientas * `GET /v1/tools`: carpetas y herramientas de todos los tipos en una lista paginada por cursor, con búsqueda (`q`), filtros (`types`, `folderId`, `scope`, fechas, `trackers`), orden (`sort`, también por la última respuesta con `lastResponse`) y conteos por tipo. `foldersLimit` y `foldersCursor` paginan las carpetas ("ver más"; la respuesta trae `foldersNextCursor`). * `GET /v1/tools/stats`: cifras por tipo en su escala nativa, para la empresa o una carpeta (`folderId`) y un periodo (`from`, `to`). * `POST /v1/tools/move`: mueve hasta 200 elementos de tipos mezclados a una carpeta (`folderId`) o a la raíz (`null`). * `folderId` al crear en `POST /v1/nps-tools`, `POST /v1/csat-tools` y `POST /v1/ces-tools`, y `PATCH /v1/{nps,csat,ces}-tools/:id/move` para moverlas. ### Participantes de una carpeta La lista de personas que deben responder las herramientas de la carpeta y quiénes ya lo hicieron. Detalle en [Participantes de una carpeta](/docs/guides/folders-and-tools#participantes-de-una-carpeta). * `GET /v1/folders/:id/participants`: la lista y, por herramienta, `responded`, `missing`, `repeated`, `outsideList` y `anonymousAllowed`. * `PUT /v1/folders/:id/participants` y `POST /v1/folders/:id/participants`: reemplazan la lista o le agregan personas (`text`, una persona por línea, hasta 500). * `DELETE /v1/folders/:id/participants/:participantId` y `DELETE /v1/folders/:id/participants`: quitan a una persona o eliminan la lista. * `POST /v1/folders/:id/participants/resend`: reenvía una herramienta a quienes faltan, por correo o WhatsApp. ### Envíos programados de reportes El reporte PDF de una carpeta o de una herramienta por correo, cada mes, quincena o semana, o una sola vez. Detalle en [Envíos programados de reportes](/docs/reports/scheduled-reports). * `GET /v1/report-subscriptions` y `POST /v1/report-subscriptions`: lista y crea envíos programados. * `PATCH /v1/report-subscriptions/:id`: edita, pausa o reanuda uno recurrente. * `DELETE /v1/report-subscriptions/:id`: lo elimina. * `POST /v1/report-subscriptions/:id/send`: lo envía ahora. ### Viajes en carpetas * `GET /v1/journey-folders`: estado de la organización de los viajes en carpetas (`enabled`, `organizing`, `pending`). * `POST /v1/journey-folders/organize`: la activa y ejecuta una pasada única en segundo plano (`202`; `409` si ya está en curso). * `folderId` y `momentFolders` en `GET /v1/journeys` y `GET /v1/journeys/:id`, y `origin` en las carpetas de `GET /v1/folders` y `GET /v1/tools`. ```bash theme={null} curl "https://clientapi.woku.app/v1/tools?types=csat,nps&q=entrega&limit=20" \ --header "Authorization: Bearer $WOKU_API_KEY" ``` ## Reportes NPS Si tu empresa usa la herramienta **NPS**, puedes consultar los reportes agregados directamente desde la API para integrarlos en tus propios dashboards. ### Reporte NPS de la compañía Devuelve el reporte agregado de **todos los NPS** registrados para tu empresa. **Endpoint** ``` GET /v1/reports/company-nps ``` **Headers** * `Authorization: Bearer ` **Respuestas** * `200 OK`: Reporte con distribución de promotores, pasivos y detractores, y el puntaje NPS resultante. * `403 Forbidden`: Clave inválida. ### Reporte NPS de una herramienta Devuelve el reporte de un **NPS Tool** específico (por ejemplo, "NPS post-evento" o "NPS post-compra"). **Endpoint** ``` GET /v1/reports/nps-tool/:id ``` **Headers** * `Authorization: Bearer ` **Path params** * `id` *(string, obligatorio)*: Identificador del NPS Tool. **Respuestas** * `200 OK`: Reporte del NPS Tool. * `400 Bad Request`: `id` mal formado. * `403 Forbidden`: Clave inválida. * `404 Not Found`: El NPS Tool no existe o no pertenece a tu empresa. ## Trackers Externos Los **trackers externos** te permiten asociar identificadores de tus sistemas (CRM, ERP, ticketing, OMS) a tus herramientas de feedback (wokus, NPS, CSAT, CES, formularios y flows) para luego buscarlas cruzadas. Por ejemplo: vincular un woku al `transaction_id` de tu CRM o al `order_id` de tu ERP. ### Modelo * **Tracker definition**: Una entrada de catálogo a nivel de empresa, como `{ name: "trr", system: "crm interno", description: "..." }`. Se define en el panel administrativo de woku, en la sección Empresa. * **Tracker value**: Un valor string ligado a un par `(herramienta, Tracker)`. Varias herramientas pueden compartir el mismo valor. ### Listar trackers activos de la empresa **Endpoint** ``` GET /v1/external-trackers ``` **Query params** * `page` *(number, opcional)*. * `limit` *(number, opcional)*. **Respuestas** * `200 OK`: Lista paginada de definiciones de trackers. * `403 Forbidden`: Clave inválida. ### Listar trackers asignados a un woku **Endpoint** ``` GET /v1/external-trackers/wokus/:id ``` **Respuestas** * `200 OK`: Trackers asignados al woku. * `403 Forbidden`: Clave inválida. ### Asignar un valor de tracker a un woku Crea o actualiza (upsert) el valor de un tracker en un woku. **Endpoint** ``` POST /v1/external-trackers/wokus/:id ``` **Body** ```json theme={null} { "name": "trr", "value": "TX-2026-00043" } ``` **Campos** * `name` *(string, obligatorio, máx 60)*: Nombre del tracker definido en tu empresa. * `value` *(string, obligatorio, máx 500)*: Valor del identificador externo (siempre se almacena como string). **Respuestas** * `201 Created`: Valor asignado o actualizado. * `400 Bad Request`: Validación fallida. * `403 Forbidden`: Clave inválida. * `404 Not Found`: El woku o el tracker no existen. ### Eliminar un valor de tracker de un woku **Endpoint** ``` DELETE /v1/external-trackers/wokus/:id/:trackerName ``` **Respuestas** * `200 OK`: Eliminado. * `403 Forbidden`: Clave inválida. * `404 Not Found`: El woku o el tracker no existen. ### Buscar wokus por tracker Encuentra todos los wokus que tienen un determinado `(name, value)`. Útil para volver desde tu CRM al woku correspondiente. **Endpoint** ``` GET /v1/external-trackers/search?name=&value= ``` **Query params** * `name` *(string, obligatorio)*: Nombre del tracker. * `value` *(string, obligatorio)*: Valor a buscar. * `page` *(number, opcional)*. * `limit` *(number, opcional)*. **Respuestas** * `200 OK`: Lista paginada de wokus con sus tracker values. * `403 Forbidden`: Clave inválida. * `404 Not Found`: No existen coincidencias. ### Trackers en herramientas VoC (NPS, CSAT, CES, formularios, flows) Además de los wokus, puedes asignar trackers a las demás herramientas de feedback. El tipo de herramienta va en la ruta como `:entityType`, con uno de estos valores: `nps`, `csat`, `ces`, `form`, `flow`. El `:id` es el id de la herramienta (por ejemplo `npsToolId`, `csatToolId`, `cesToolId`, `formId` o `flowId`). En la versión 2 de la API estos endpoints y los de wokus se unificarán en un único recurso polimórfico. #### Listar trackers asignados a una herramienta **Endpoint** ``` GET /v1/external-trackers/:entityType/:id ``` Ejemplo: `GET /v1/external-trackers/nps/671000000000000000000001`. **Respuestas** * `200 OK`: Trackers asignados a la herramienta. * `400 Bad Request`: Tipo de herramienta no soportado. * `403 Forbidden`: Clave inválida. #### Asignar un valor de tracker a una herramienta Crea o actualiza (upsert) el valor de un tracker en la herramienta. **Endpoint** ``` POST /v1/external-trackers/:entityType/:id ``` **Body** ```json theme={null} { "name": "trr", "value": "TX-2026-00043" } ``` **Campos** * `name` *(string, obligatorio, máx 60)*: Nombre del tracker definido en tu empresa. * `value` *(string, obligatorio, máx 500)*: Valor del identificador externo (siempre se almacena como string). **Respuestas** * `201 Created`: Valor asignado o actualizado. * `400 Bad Request`: Tipo no soportado, tracker inactivo o validación fallida. * `403 Forbidden`: La herramienta pertenece a otra empresa. * `404 Not Found`: La herramienta o el tracker no existen. #### Eliminar un valor de tracker de una herramienta **Endpoint** ``` DELETE /v1/external-trackers/:entityType/:id/:trackerName ``` **Respuestas** * `200 OK`: Eliminado. * `404 Not Found`: El tracker o la asignación no existen. ## Destinos de tickets Los **destinos de tickets** definen a dónde llegan los tickets de soporte que genera la IA de woku: Zendesk, un servicio HTTP propio o una lista de correos. Cada destino tiene reglas de enrutamiento basadas en tus trackers externos que deciden qué tickets le llegan. ### Modelo * `kind` *(obligatorio)*: `zendesk`, `custom` o `email`. * `config` *(obligatorio)*: configuración no sensible, específica de cada `kind`. * `zendesk`: `{ connectionId, groupId? }`. `connectionId` es el id de tu Integración de Zendesk conectada en el panel administrativo; `groupId` es el grupo de agentes, opcional. * `custom`: `{ url, method, headers? }`. `method` es `POST` o `PUT`; `headers` son cabeceras extra no sensibles. * `email`: `{ emails }`. Hasta 20 destinatarios. * `credentials` *(obligatorio, de solo escritura)*: nunca se devuelve en las respuestas, solo su `credentialsHint` (últimos 4 caracteres enmascarados). Zendesk se autentica con la Integración conectada de tu empresa, así que envías `{}`. Custom usa `{ authType, ... }`, con `authType` `none`, `basic` (agrega `username`, `password`), `bearer` (agrega `token`) o `api-key-header` (agrega `headerName`, `headerValue`). Email tampoco usa credenciales, envías `{}`. * `routingConditions` *(opcional, hasta 20 filas)*: condiciones sobre tus trackers externos. Cada fila usa el operador `equals` (el tracker debe tener un valor exacto en `value`) o `any` (cualquier valor del tracker, se omite `value`). `relationToPrevious` une una fila con la anterior (`AND` mismo grupo, `OR` grupo nuevo); la primera fila no lo incluye. El destino recibe el ticket cuando algún grupo OR se cumple completo. ### Listar los destinos de tickets **Endpoint** ``` GET /v1/ticket-destinations ``` **Respuestas** * `200 OK`: Lista de destinos (sin credenciales). * `403 Forbidden`: Clave inválida. ### Obtener un destino de tickets **Endpoint** ``` GET /v1/ticket-destinations/:id ``` **Respuestas** * `200 OK`: Destino. * `403 Forbidden`: Clave inválida. * `404 Not Found`: No existe el destino. ### Crear un destino de tickets **Endpoint** ``` POST /v1/ticket-destinations ``` **Headers** * `Content-Type: application/json` * `Authorization: Bearer ` **Body (ejemplo con Zendesk, enrutado por cualquier valor de un tracker)** ```json theme={null} { "name": "Zendesk Soporte", "kind": "zendesk", "config": { "connectionId": "671000000000000000000010" }, "credentials": {}, "routingConditions": [ { "trackerId": "671000000000000000000011", "operator": "any" } ] } ``` **Campos** * `name` *(string, obligatorio, máx 120)*. * `kind`, `config`, `credentials`, `routingConditions`: ver la sección Modelo de este apartado. * `aiContext` *(string, opcional, máx 2000)*: contexto adicional para el triage de IA de este destino. * `template` *(object, opcional, solo `kind: "custom"`)*: `{ preset, body? }`. Sin `body`, se envía el sobre canónico del ticket. **Respuestas** * `201 Created`: Destino creado. * `400 Bad Request`: Validación fallida. * `403 Forbidden`: Clave inválida. ### Actualizar un destino de tickets **Endpoint** ``` PATCH /v1/ticket-destinations/:id ``` Todos los campos son opcionales; solo se cambian los que envías. Enviar `credentials` rota el secreto guardado. Enviar `kind` cambia el proveedor: `config` y `credentials` se validan contra el nuevo `kind`. **Body (ejemplo: deshabilitar)** ```json theme={null} { "enabled": false } ``` **Respuestas** * `200 OK`: Destino actualizado. * `400 Bad Request`: Validación fallida. * `403 Forbidden`: Clave inválida. * `404 Not Found`: No existe el destino. ### Eliminar un destino de tickets **Endpoint** ``` DELETE /v1/ticket-destinations/:id ``` Sus condiciones de enrutamiento viven en el destino y desaparecen con él. **Respuestas** * `200 OK`: `{ "deleted": true }`. * `403 Forbidden`: Clave inválida. * `404 Not Found`: No existe el destino. ## Grupos de planes de acción Un **grupo de plan de acción** define qué feedback (por condiciones de trackers) genera un plan de mejora y quiénes son los responsables. Cuando el contador de comentarios nuevos de tipo mejora alcanza el `threshold` del grupo, woku redacta un plan con IA para sus miembros. ### Modelo * `conditions` *(obligatorio, mínimo 1 fila, hasta 20)*: mismas reglas que `routingConditions` de los destinos de tickets (operador `equals` o `any`, `relationToPrevious` para armar AND/OR). * `members` *(obligatorio, mínimo 1)*: cada uno con `userId` y `role` (`admin` aprueba y envía planes, `assignee` trabaja las tareas). Un grupo necesita al menos un `admin` y un `assignee`. * `threshold` *(integer, opcional, mínimo 1, por defecto 300)*: comentarios nuevos de tipo mejora que disparan un borrador. * `enabled`: un grupo deshabilitado deja de contar feedback y de generar borradores, pero conserva su historial y estadísticas. ### Listar los grupos de planes de acción **Endpoint** ``` GET /v1/action-plan-groups ``` **Query params** * `search` *(string, opcional)*: búsqueda libre por nombre, descripción y valores de condición. **Respuestas** * `200 OK`: Lista de grupos. * `403 Forbidden`: Clave inválida. ### Obtener un grupo de planes de acción **Endpoint** ``` GET /v1/action-plan-groups/:id ``` **Respuestas** * `200 OK`: Grupo. * `403 Forbidden`: Clave inválida. * `404 Not Found`: No existe el grupo. ### Crear un grupo de planes de acción **Endpoint** ``` POST /v1/action-plan-groups ``` **Headers** * `Content-Type: application/json` * `Authorization: Bearer ` **Body** ```json theme={null} { "name": "Atención en tienda", "description": "Reclamos sobre la experiencia en tienda física.", "conditions": [ { "trackerId": "671000000000000000000011", "operator": "any" } ], "members": [ { "userId": "671000000000000000000020", "role": "admin" }, { "userId": "671000000000000000000021", "role": "assignee" } ], "threshold": 300 } ``` **Campos**: ver la sección Modelo de este apartado, más `name` *(string, obligatorio, máx 120)* y `description` *(string, opcional, máx 500)*. **Respuestas** * `201 Created`: Grupo creado. * `400 Bad Request`: Validación fallida. * `403 Forbidden`: Clave inválida. ### Actualizar un grupo de planes de acción **Endpoint** ``` PATCH /v1/action-plan-groups/:id ``` Todos los campos son opcionales; enviar `description: ""` la limpia. **Respuestas** * `200 OK`: Grupo actualizado. * `400 Bad Request`: Validación fallida. * `403 Forbidden`: Clave inválida. * `404 Not Found`: No existe el grupo. ### Habilitar o deshabilitar un grupo **Endpoint** ``` PATCH /v1/action-plan-groups/:id/enabled ``` **Body** ```json theme={null} { "enabled": false } ``` **Respuestas** * `200 OK`: Grupo actualizado. * `403 Forbidden`: Clave inválida. * `404 Not Found`: No existe el grupo. ### Eliminar un grupo de planes de acción **Endpoint** ``` DELETE /v1/action-plan-groups/:id ``` Los planes ya generados conservan su propio detalle congelado y solo referencian al grupo por id. **Respuestas** * `200 OK`: `{ "deleted": true }`. * `403 Forbidden`: Clave inválida. * `404 Not Found`: No existe el grupo. ## Planes de acción Los **planes de acción** son planes de mejora redactados por IA a partir del feedback de un grupo. Un plan nace en estado `draft`, se aprueba, y desde ahí se trabaja dentro de woku con el proveedor `internal` ("Gestionar en woku", un kanban interno). ### Modelo * `status`: `draft`, `approved`, `sent`, `canceled`, `delivery_error`, `in_progress` (gestionado dentro de woku) o `completed`. * `priority`: `high`, `medium` o `low`, calculada por woku (nunca la define la IA). * `evidence`: el recorte de feedback congelado al momento de generar el plan; sus números nunca se recalculan. * `tasks`: lista de tareas del plan. En un plan gestionado (`in_progress`) cada tarea además tiene `status` (`todo`, `in_progress`, `done`) y `assigneeId`. ### Listar los planes de acción **Endpoint** ``` GET /v1/action-plans ``` **Query params** * `groupId`, `status`, `source` (`woku`, `nps`, `csat` o `ces`), `priority`, `from`, `to`, `search`, `page`, `limit`: todos opcionales. **Respuestas** * `200 OK`: `{ "data": [...], "total": 42 }`. A diferencia de otros listados de esta API, esta respuesta no repite `page` ni `limit`. * `403 Forbidden`: Clave inválida. ### Obtener un plan de acción **Endpoint** ``` GET /v1/action-plans/:id ``` Devuelve el plan completo, incluyendo el detalle de evidencia congelada y el estado de envío. **Respuestas** * `200 OK`: Plan. * `403 Forbidden`: Clave inválida. * `404 Not Found`: No existe el plan. ### Gestionar un plan dentro de woku **Endpoint** ``` POST /v1/action-plans/:id/send ``` El plan debe estar `approved` (o `delivery_error` para reintentar). Con `provider: "internal"` el plan se gestiona dentro de woku: no lleva `target` y aplica de inmediato (el plan pasa a `in_progress`). **Body** ```json theme={null} { "provider": "internal" } ``` **Campos** * `provider` *(string, obligatorio)*: `internal` (gestionar el plan dentro de woku). Es el único proveedor disponible en la API pública. * `resourceLabel` *(string, opcional, máx 300)*: descripción legible del destino. **Respuestas** * `202 Accepted`: `{ "status": "managed" }`. * `403 Forbidden`: Clave inválida. * `404 Not Found`: No existe el plan. * `409 Conflict`: El plan no está en un estado válido para esta transición, o ya hay un envío en curso. ### Tareas de un plan Disponibles mientras el plan está en `draft` o `in_progress` (gestionado). El `status` y el `assigneeId` de una tarea solo se editan en un plan gestionado. **Endpoints** ``` POST /v1/action-plans/:id/tasks PATCH /v1/action-plans/:id/tasks/reorder PATCH /v1/action-plans/:id/tasks/:taskId DELETE /v1/action-plans/:id/tasks/:taskId ``` * **Agregar** (`POST .../tasks`): body `{ "text": "..." }`, máximo 160 caracteres, hasta 100 tareas por plan. * **Reordenar** (`PATCH .../tasks/reorder`): body `{ "orderedTaskIds": [...] }` con TODOS los ids de tareas del plan, en el orden deseado. * **Editar** (`PATCH .../tasks/:taskId`): body con al menos uno de `text`, `status` o `assigneeId`. * **Eliminar** (`DELETE .../tasks/:taskId`): sin body. Las cuatro devuelven el plan completo actualizado. **Respuestas** * `200 OK` (`201 Created` al agregar): Plan actualizado. * `400 Bad Request`: Validación fallida. * `403 Forbidden`: Clave inválida. * `404 Not Found`: No existe el plan o la tarea. * `409 Conflict`: El plan no está en `draft` ni `in_progress`, o se envió `status`/`assigneeId` en un plan no gestionado. ### Cambiar el estado de un plan **Endpoints** ``` POST /v1/action-plans/:id/approve POST /v1/action-plans/:id/reopen POST /v1/action-plans/:id/cancel POST /v1/action-plans/:id/complete POST /v1/action-plans/:id/resume ``` Sin body. Cada acción exige que el plan esté en un estado de origen específico: | Acción | Desde | Hacia | | - | - | - | | `approve` | `draft` | `approved` | | `reopen` | `approved`, `delivery_error` | `draft` | | `cancel` | `draft`, `approved`, `delivery_error`, `in_progress` | `canceled` | | `complete` | `in_progress` | `completed` | | `resume` | `completed` | `in_progress` | **Respuestas** * `200 OK`: Plan actualizado. * `403 Forbidden`: Clave inválida. * `404 Not Found`: No existe el plan. * `409 Conflict`: El plan no está en el estado de origen requerido para esa acción. ## Límites de ingesta y extracción La API REST está documentada de forma interactiva en la pestaña **API Reference** y aplica **límites de tasa y de volumen** tanto para la **ingesta** (creación de wokus, reseñas, NPS, asignación de trackers) como para la **extracción** (consulta de wokus, reportes y búsquedas). Los límites cubren los dos modos de operación: **por evento** (una llamada por registro) y **por lote** (cargas batch). Los límites se aplican por **Clave de Compañía**: | Operación | Modo | Límite | | - | - | - | | Ingesta por evento | Evento | 600 solicitudes/minuto · hasta 50 eventos/seg | | Ingesta por lote | Lote | Hasta 5.000 registros por lote · 60 lotes/minuto | | Volumen diario de ingesta | Evento + lote | 1.000.000 registros/día | | Extracción (lectura) | Evento | 300 solicitudes/minuto | | Extracción paginada | Lote | Hasta 200 registros por página | > [!NOTE] > > Estos son los límites por defecto del plan **Corporate**. Si tu integración > necesita ventanas mayores (picos estacionales, migraciones masivas), > escríbenos para ampliarlos. ### Manejo de 429 (Too Many Requests) Cuando superas un límite de tasa, la API responde con `429 Too Many Requests` e incluye encabezados que te indican cuándo reintentar: * `Retry-After`: segundos a esperar antes del siguiente intento. * `X-RateLimit-Limit`: tope de la ventana actual. * `X-RateLimit-Remaining`: solicitudes restantes en la ventana. * `X-RateLimit-Reset`: marca de tiempo en que se reinicia la ventana. Implementa **reintentos con backoff exponencial** respetando `Retry-After`. Para cargas batch, divide los lotes que excedan el máximo de registros en lugar de reintentar el lote completo. ### Paginación en la extracción Los endpoints de extracción que devuelven colecciones son **paginados**. Controla la página con los query params `page` y `limit` (por ejemplo, en `GET /v1/external-trackers` o `GET /v1/external-trackers/search`). Para extraer grandes volúmenes, recorre las páginas de forma secuencial respetando el límite de extracción por minuto y el máximo de registros por página. ``` GET /v1/external-trackers/search?name=trr&value=TX-2026-00043&page=1&limit=200 ``` ## Errores comunes ### URL de archivo inaccesible Si usas `POST /v1/wokus` con `fileUrl`, asegúrate de que la URL sea **públicamente accesible**. Nuestro servicio descarga el archivo antes de crear el woku. ### Clave secundaria duplicada `folderSecondaryKey` se usa para identificar una carpeta dentro de tu empresa. **No pueden existir dos carpetas con la misma clave** en una misma empresa. Si necesitas reutilizar una clave, primero elimina la carpeta existente desde el panel administrativo. ### 403 en todas las llamadas Casi siempre significa que la clave es incorrecta, está caducada o pertenece a otra empresa. Vuelve a obtener la clave desde [admin.woku.app](https://admin.woku.app) → Información de la empresa → **Obtener Clave**. ## Contacto y soporte * Diego Orrego Brito, CTO de woku. * Correo: [diego@woku.app](mailto:diego@woku.app) (incluye el nombre de la empresa en el asunto y menciona que se trata de la API). ## Procedencia y seguimiento Las capturas aceptan `collectionKind: "standalone" | "flow"` y `flowId` en capturas JSON y multipart. Los productores nuevos declaran `standalone`; una respuesta de Flow declara `flow` y su ID desde el primer intento. Esto aplica a `POST /v1/captures`, texto/audio Woku y la creación de NPS/CSAT/CES. Los adjuntos posteriores heredan la procedencia ya persistida. Omitir ambos campos identifica un contrato antiguo con contexto desconocido; no convierte una respuesta en individual. No existe un parámetro público para omitir el agente. La API valida la combinación y la pertenencia a empresa e instrumento. El ID y el cuerpo de un reintento deben conservarse. La API de gestión expone `followUp` en respuestas y tickets, `contentVersion` en el ticket y `GET /v1/follow-ups/:id` para el hilo autorizado, con respuesta `{data: conversation}`. Las listas no incluyen mensajes. La clave publicable de captura no accede al hilo; se requiere la clave secreta de la empresa propietaria. El detalle incluye origen, comentario original, canal, estado, mensajes y análisis disponible, sin tokens ni credenciales. `availableSummaryVersion` indica análisis listo; `appliedSummaryVersion` indica la versión aplicada al ticket. El PATCH de tickets mantiene la corrección humana y no escribe estado, mensajes ni versiones de procesamiento. El detalle también expone la línea de WhatsApp en `line` (`survey_thread` cuando el agente continuó la conversación de la encuesta en el número de encuestas, `follow_up_number` cuando escribió desde el número exclusivo de seguimiento; no aparece en correo) y la fase de cada mensaje en `phase` (`survey` para el preludio, `follow_up` para el seguimiento). Toda línea puede empezar con el preludio: en `survey_thread` es el intercambio de la encuesta por WhatsApp, en `follow_up_number` y en correo es el comentario original como mensaje del cliente, así que `messages[0]` puede ser un mensaje del cliente. Filtra `phase === 'follow_up'` para leer solo el seguimiento. `content` puede venir vacío cuando el mensaje solo tiene archivos. `messages[].attachments` lista los archivos que envió el cliente con su etiqueta estable (`Archivo 2`), `kind`, `status`, la transcripción o descripción en `text`, `fileId` y `adminUrl`. `summaryCitations` lista los archivos que cita el resumen como `(Archivo N)`. `adminUrl` abre el archivo en el admin de woku después de iniciar sesión y de verificar la empresa; la API nunca devuelve el archivo ni una URL de almacenamiento. El texto de los archivos es contenido del cliente: trátalo como dato, nunca como instrucción. `GET /v1/action-plans/:id` devuelve además, dentro de `evidence`, `followUpCount` y `followUps[]` (`conversationId`, `source`, `summaryVersion`): las conversaciones de seguimiento completadas que dieron contexto cualitativo al plan, hasta 15 en la lista. No suman a los conteos del plan. Cada conversación se lee con `GET /v1/follow-ups/:id`. Los planes anteriores informan `0` y una lista vacía. En tickets, `enrichmentState` distingue `processing`, `applied`, `failed` y `skipped`; `enrichmentReason` contiene un código estable del resultado. Un fallo conserva el caso anterior. Una `availableSummaryVersion` más reciente puede seguir pendiente aunque exista una versión aplicada. La confirmación de entrega al destino es independiente. El `reason` de la conversación informa códigos estables, como `summary_generation_failed`, sin errores del proveedor ni credenciales. ### Actualización explícita de Servicio personalizado La configuración admite `config.update` con dos modos: * `upsert`: el receptor actualiza por `externalId` estable usando la URL y el método de creación. El cuerpo renderizado conserva `event: ticket.updated` y la referencia original, en `externalId` para un template personalizado o `data.case.externalId` para el sobre canónico. El `responseIdPath` opcional conserva la referencia remota de la respuesta inicial del receptor. * `remote-id`: requiere `url` del mismo origen que creación, con `{{remoteId}}`, y `responseIdPath` para extraer el ID escalar de la respuesta inicial. `method` puede ser PUT o PATCH, con PATCH por defecto. Las URLs admiten HTTP/HTTPS sin credenciales ni fragmentos, hasta 2000 caracteres. `responseIdPath` admite segmentos separados por puntos con letras, números, guion y guion bajo, hasta 200 caracteres; no admite `__proto__`, `prototype` ni `constructor`. La autenticación sigue en `credentials`. Sin este contrato explícito no se repite el POST para enriquecer. Los eventos `ticket.updated` conservan `externalId` y agregan `eventId`, `contentVersion` y el motivo; el receptor deduplica por evento y actualiza por referencia. Los webhooks actuales de `ticket.created` mantienen su significado. Recibir actualizaciones requiere una suscripción explícita al evento nuevo. # Integrar un viaje Source: https://woku.app/docs/development/journey-integration Configura cuatro momentos con API o MCP, contenido dinámico y webhooks independientes Este ejemplo evalúa compra con CSAT, entrega con Woku, uso con CES y recomendación con NPS. Cada momento tiene una herramienta. La entrega puede evaluar varias cosas en un solo Woku; no se divide en una encuesta por pregunta. Necesitas Node.js 18 o posterior, una [Clave de Compañía](/docs/development/api), una imagen subida y el secreto real que te entregue el sistema emisor. La API de administración continúa en `/v1`. Las URLs entrantes las devuelve la configuración del momento; usa esas URLs como destinos del emisor. ## 1. Preparar media y credenciales ```bash theme={null} export WOKU_API_BASE="https://clientapi.woku.app" export WOKU_API_KEY="" export SENDER_SECRET="" curl -sS "$WOKU_API_BASE/v1/woku-media" \ -H "Authorization: Bearer $WOKU_API_KEY" \ -F "file=@producto.webp" ``` La subida devuelve `fileId`, `filename` y `type`. Guarda el `fileId` como `WOKU_FILE_ID`. La clave secreta y el secreto del emisor pertenecen a la configuración del servidor. ```bash theme={null} export WOKU_FILE_ID="" export START_MODE="operator" # También admite response o webhook. ``` ## 2. Crear cuatro momentos Guarda el siguiente código en `journey.mjs`. Crea un viaje apagado y configura dos URLs con token generado por woku y dos momentos con firma del emisor. Puedes generar una URL para cada momento aunque normalmente avance por espera. Ejecuta `node journey.mjs` para crear y revisar el borrador. El ejemplo deja tickets y planes apagados; en un programa real puedes habilitar cada acción por separado con `recipients.ticketsEnabled` y `recipients.plansEnabled`. Tickets usan `ticketEmails`; planes usan `planMembers` con usuarios de la empresa y roles `admin` o `assignee`. El creador permanece como administrador del grupo. | Momento | Contenido | Avance | | - | - | - | | Compra | CSAT compartido con variables estáticas | Inscripción, primera respuesta o webhook, según el inicio | | Entrega | Woku por evaluación, descripción condicional, imagen, carpetas y trackers | Webhook del emisor; espera secundaria de 10 días | | Uso | CES compartido | Una hora después de Entrega, o su webhook si llega antes | | Recomendación | NPS por evaluación con variables condicionales | Webhook del emisor | `contentMode` define de dónde sale el contenido, independientemente de `trigger`. JavaScript es un cuerpo de función que recibe `payload` y devuelve un string. No tiene imports, red ni acceso a archivos. El schema acotado valida el payload antes de ejecutar el contenido. Las rutas no admiten `constructor`, `prototype` ni `__proto__`. La imagen dinámica de Woku debe ser una URL HTTPS pública. Si configuraste una espera secundaria y el webhook nunca llega, el momento usa su nombre, variables y media estáticos; por eso el ejemplo conserva `toolSpec.fileId`. Las carpetas se crean si no existen. Los nombres son opcionales y usan la clave cuando faltan, respetando los límites de nombres de carpeta. Esas carpetas son las que `GET /v1/journeys/:id` expone en `momentFolders`; para ordenar además las herramientas de cada momento en **Viajes > viaje > momento**, usa `POST /v1/journey-folders/organize` (consulta [Carpetas y herramientas](/docs/guides/folders-and-tools#viajes-en-carpetas)). ## 3. Previsualizar y activar Añade estos pasos al mismo archivo, después de la definición de `sendMoment`. Reemplaza el email por una dirección de prueba autorizada. ```javascript theme={null} const sample = { order: { id: 'order-demo-123', deliveryMode: 'pickup', store: 'store-demo', image: journey.moments[1].toolSpec.imageUrl }, customer: { email: process.env.TEST_CUSTOMER_EMAIL, tier: 'gold' }, }; if (!sample.customer.email) throw new Error('Set TEST_CUSTOMER_EMAIL'); const preview = await api(`/journeys/${journey.id}/moments/delivery/preview`, { payload: sample }); console.log(preview.preview.title, preview.preview.folder); await api(`/journeys/${journey.id}`, { enabled: true }, 'PATCH'); ``` El preview devuelve `200`, interpreta el JavaScript con el payload enviado y muestra la pregunta compuesta de CSAT/CES/NPS cuando corresponde y no inscribe ni envía. Cambia `deliveryMode` para probar otra rama. No verifica firmas: compruébalas enviando un evento real después de activar. En un viaje nuevo v2, cada momento tiene un envío inicial y un recordatorio al día siguiente por defecto. El ejemplo lo declara explícitamente en `sequence`. Una espera de cero días significa una hora. Puedes cambiar los intentos y ventanas; las definiciones anteriores conservan sus valores. ## 4. Enviar eventos con una referencia estable Si `START_MODE=operator`, inscribe el caso y después emite sus confirmaciones: ```javascript theme={null} await api(`/journeys/${journey.id}/enrollments`, { subjectKey: sample.order.id, contact: { email: sample.customer.email }, }); await sendMoment('sale', sample, 'sale-demo-123'); await sendMoment('delivery', sample, 'delivery-demo-123'); await sendMoment('use', sample, 'use-demo-123'); await sendMoment('loyalty', sample, 'loyalty-demo-123'); ``` Con `START_MODE=webhook`, omite la inscripción. El webhook de Compra inicia el caso. En ambos recorridos, todos los emisores usan el mismo `order.id`; el email identifica al contacto, y la referencia enlaza los eventos del caso. Un evento posterior puede llegar adelantado y esperar su condición anterior. El webhook adelanta un momento temporal y cancela su espera; un evento tardío no repite una herramienta que ya se envió. La exclusión de ejecución no depende solo de `X-Woku-Event-Id`. | Autenticación | Lo que recibe el emisor | | - | - | | `url_token` | La URL completa generada por woku; generar otra reemplaza la anterior | | `sender_hmac` | Su secreto real, header, encoding, prefix y bytes firmados, según su protocolo | | `woku_signature` legacy | El `webhookSecret` global de creación o rotación, con el protocolo de firma legacy | No intercambies estos secretos. Las lecturas de conexión devuelven la URL sin credencial y su estado de configuración, nunca el token guardado ni el secreto del emisor. ## 5. Inicio por primera respuesta Esta es una alternativa a la inscripción del paso 4. Ejecuta la configuración con `START_MODE=response` para un viaje nuevo o usa un caso nuevo antes de enviar sus eventos. El acceso por QR o enlace también está disponible en viajes v2 con inicio operator. Obtener o preparar la entrada no inicia el recorrido. No prepares otra entrada para un caso que ya está en curso. ```javascript theme={null} const entry = await api(`/journey-entries/${journey.id}`, { requestId: randomUUID(), reference: sample.order.id, email: sample.customer.email, }); await api('/csat', { csatToolId: entry.toolId, score: 5, clientEmail: sample.customer.email, dispatchToken: entry.token, }); ``` Este ejemplo tiene CSAT primero. Para otra primera herramienta, usa su ruta pública de captura y pasa el token como `dispatchToken`; en Woku usa un comentario o audio identificado. Guarda la respuesta válida primero; esa respuesta confirma el inicio una sola vez. La entrada preparada aparece pendiente y no manda una nueva invitación a la primera herramienta. ## 6. Seguimiento, reintentos y detención ```javascript theme={null} const page = await api(`/journeys/${journey.id}/enrollments?limit=20`, undefined, 'GET'); console.log(page.items.map(({ id, lifecycle, next }) => ({ id, lifecycle, next }))); // When nextCursor is present, request the next page with ?limit=20&cursor=... const caseId = page.items[0]?.id; // To stop only this case: POST /v1/journeys/{id}/enrollments/{caseId}/stop // with { reason: 'Order cancelled' }. ``` La página devuelve hasta 100 casos, 20 por defecto. `nextCursor` aparece solo si hay otra página. Cada caso conserva su versión, historial y próximo paso. Editar el viaje crea una versión para casos futuros y conserva las credenciales separadas; una participación en curso usa su snapshot anterior. El ciclo se completa al responder la última herramienta o 30 días desde su primer envío. Una inscripción manual puede reutilizar la misma clave cuando el ciclo previo haya completado o terminado su detención. Detener cancela esperas y recordatorios del caso exacto, conserva feedback y otros casos, y no retira entregas ya aceptadas por un proveedor. | Resultado | Qué hacer | | - | - | | `200` con `accepted`, `duplicate` o `ignored` del webhook | Darlo por atendido; un evento no coincidente puede ser ignorado | | `400` | Corregir configuración, schema o datos antes de reintentar | | `401` del webhook | Corregir token o firma, incluido su timestamp | | `403` del API | Revisar la clave, empresa y acceso | | `404` | Revisar viaje, momento o participación | | `409` | Esperar o resolver el ciclo en curso; no inventar otra identidad para evitar el conflicto | | `429` o fallo transitorio | Reintentar con backoff y el mismo ID de evento | En POST de administración que admiten `X-Woku-Idempotency-Key`, usa una clave nueva para una operación nueva y conserva la anterior para sus reintentos. Reutilizarla con otro cuerpo reproduce la respuesta original; usarla en otra operación devuelve `422`. ## El mismo contrato en MCP y SDKs En MCP, pide `woku_guide` con `topic=customer_journeys`. `create_journey` y `update_journey` usan los mismos momentos avanzados, pero llaman `cadence` a `sequence`. Usa `preview_journey_moment`, `get_journey_connections`, `mint_journey_moment_url` y `set_journey_sender_secret` para conectar. Las mutaciones de credenciales y la detención requieren confirmación explícita; las escrituras necesitan `mcp:write`. Los SDKs JavaScript y Python conservan la API `/v1`, tienen tipos generados de los momentos y no activan un viaje al crearlo. [Consulta la referencia MCP](/docs/mcp/tools) y los [conceptos del viaje](/docs/core-concepts/journeys). ### Volver desde el mismo QR o enlace Conserva requestId mientras preparas o reintentas la misma primera herramienta. Si la API devuelve HTTP 409 con código `journey_entry_closed`, identificó un ciclo completado o detenido. Para un nuevo ciclo sin referencia externa, vuelve a preparar con un requestId nuevo. No renueves el ID por timeout, error de red ni conflicto con una evaluación activa. Una referencia de compra explícita sigue identificando ese mismo caso y debe cambiar para una compra distinta. # Entorno sandbox Source: https://woku.app/docs/development/sandbox Un entorno aislado que replica tu configuración de producción para probar captura de respuestas e integraciones antes de publicarlas > [!NOTE] > > **Disponible en el plan Corporate.** Esta funcionalidad forma parte de las capacidades empresariales de woku. [Conversa con nuestro equipo comercial](https://woku.app/pricing). woku incluye un **entorno sandbox**: un espacio aislado donde puedes probar funcionalidades y configuraciones **antes de llevarlas a producción**. El sandbox **replica la configuración de producción**, de modo que lo que validas ahí se comporta igual cuando lo promueves, pero sin tocar tus datos ni a tus clientes reales. > [!NOTE] > > El entorno sandbox está disponible en el plan **Corporate**. Cada empresa > tiene su propio sandbox, aislado de su entorno de producción. ## Qué aísla el sandbox El sandbox es un entorno paralelo que **no comparte estado** con producción. Quedan separados: | Recurso | Producción | Sandbox | | - | - | - | | **Datos** (wokus, reseñas, NPS) | Datos reales de clientes | Datos de prueba, descartables | | **Encuestas y herramientas** | Las que ven tus clientes | Copias para experimentar | | **Integraciones** | Conectadas a tus sistemas reales | Apuntan a endpoints de prueba | | **Claves de API** | Clave de producción | Clave de sandbox independiente | | **Pipelines de ingesta** | En vivo | Aislados, sin afectar reportes reales | Nada de lo que hagas en sandbox impacta los reportes ni los datos de producción. Puedes borrar y recrear datos de prueba con total libertad. ## Cambiar de entorno Cada entorno tiene su **propia clave**. Para apuntar tu integración al sandbox, basta con usar la clave de sandbox en lugar de la de producción; la URL base es la misma. **1. Obtén la clave de sandbox** En la aplicación administrativa, ve a **Empresa → Información** y abre la pestaña de **Sandbox** para copiar la **Clave de Sandbox**. Es independiente de tu clave de producción. **2. Configura tu integración** Usa esa clave en el header `Authorization` de tus llamadas. La empresa y sus datos quedan resueltos por la clave, así que el mismo código funciona contra sandbox o producción solo cambiando la clave. ``` Authorization: Bearer ``` **3. Promueve a producción** Cuando la configuración funcione como esperas, replícala en producción cambiando de vuelta a la clave de producción. Como el sandbox refleja la misma configuración, no hay sorpresas al promover. > [!TIP] > > Si usas el [SDK de React Native](/docs/development/sdk-react-native), basta con > inicializarlo con la `publicKey` de sandbox para enviar todas las capturas al > entorno de pruebas. ## Refleja la configuración de producción El sandbox **espeja la configuración de producción**: mismas estructuras de carpetas, mismos esquemas de ingesta, mismas definiciones de trackers, encuestas y reglas. Esto te permite reproducir un escenario real y confiar en que lo validado se comportará igual al promoverlo. Puedes sincronizar la configuración de producción hacia el sandbox cuando quieras partir de un estado limpio y representativo. ## Pruebas de captura e integraciones El sandbox permite probar la captura de respuestas y consultar resultados sin afectar los datos de producción. > [!WARNING] > > Los datos del sandbox son de prueba y pueden purgarse. No uses el sandbox > como respaldo ni almacenes ahí información que necesites conservar. # Versionado y política de deprecación Source: https://woku.app/docs/development/versioning Cómo woku versiona su API pública y cómo comunica cambios y deprecaciones, para que tus integraciones y agentes de IA se mantengan estables. woku publica una API pública versionada para que puedas integrar con confianza y para que los agentes de IA sepan contra qué superficie construir. ## Versionado La versión vive en la ruta de cada endpoint, con el prefijo `/v1/`. Una versión mayor es un contrato estable: mientras uses `/v1/`, woku no introduce cambios que rompan integraciones existentes. * **Cambios compatibles** (no rompen y no cambian de versión): agregar endpoints nuevos, agregar campos opcionales a una respuesta, agregar valores nuevos a un enumerado o agregar parámetros opcionales. Tu integración debe ignorar los campos que no conoce. * **Cambios incompatibles** (rompen): quitar o renombrar un campo o endpoint, cambiar un tipo o cambiar el comportamiento por defecto. Estos solo ocurren en una versión mayor nueva (por ejemplo `/v2/`), nunca dentro de `/v1/`. La referencia siempre describe la versión vigente. La API v0 es una versión previa que se mantiene por compatibilidad y no recibe funcionalidades nuevas. ## Deprecación Cuando un endpoint o una versión se marca para retiro, woku lo comunica de forma explícita y con anticipación: * **Encabezados de respuesta**: las respuestas de un endpoint deprecado incluyen `Deprecation: true` y un encabezado `Sunset` con la fecha a partir de la cual dejará de responder (RFC 8594). * **Aviso previo**: publicamos la deprecación en la documentación antes de la fecha de retiro, con una ruta de migración a la versión vigente. * **Sin sorpresas**: no retiramos una versión mayor sin aviso y sin un reemplazo disponible. ## Recomendación para integraciones y agentes * Construí contra `/v1/` y tratá los campos desconocidos como opcionales. * Revisá los encabezados `Deprecation` y `Sunset` en cada respuesta y agendá tu migración antes de la fecha indicada. * Ante la duda, la [referencia de la API](/docs/development/api) describe la superficie vigente. # Problema Source: https://woku.app/docs/fundamentals/problem Por qué las encuestas tradicionales ya no funcionan Las encuestas son una herramienta muy usada en las empresas, sobre todo para medir qué tan contentos están los clientes. Sin embargo, cada vez funcionan menos bien. ¿Por qué? * Los clientes están cansados de responder tantas encuestas. * Muchas encuestas están mal diseñadas y no obtienen información útil. * Las empresas no saben usar bien los resultados para tomar decisiones importantes. Estos problemas hacen que las empresas necesiten encontrar nuevas formas de escuchar lo que sus clientes piensan y sienten. ## Fatiga de Encuesta La gente está cansada de responder encuestas. Esto se nota en varios aspectos: 1. **Menos gente responde**: * En encuestas por teléfono, solo responde un 30% de las personas en promedio. * Puede variar entre un 4% y un 70% (Holbrook et al., 2008). 2. **Las encuestas largas cansan más**: * Si duran menos de 10 minutos, el 68.2% las termina. * Si duran 30 minutos, solo el 46.8% las termina (Galesic & Bosnjak, 2009). 3. **La calidad de las respuestas baja con el tiempo**: * Al principio, la gente tarda unos 120 segundos por pregunta. * Al final, solo tardan 105 segundos (Galesic & Bosnjak, 2009). * Las respuestas a preguntas abiertas se hacen más cortas y menos variadas. 4. **La gente busca terminar rápido**: * Cuando las preguntas son difíciles o la encuesta es larga, la gente tiende a dar respuestas "suficientes" en lugar de pensar mucho. * A veces eligen siempre la misma opción para terminar más rápido (Krosnick, 1991). Estos problemas hacen que las encuestas sean menos útiles para las empresas, porque no obtienen información de calidad. ## Diseño de Encuesta Crear una encuesta efectiva es un proceso complejo que va mucho más allá de formular preguntas. Una mala formulación no solo puede confundir, sino también generar datos inútiles que conduzcan a decisiones erróneas. ### El proceso de creación de una encuesta efectiva Según Hinkin (1998), crear una encuesta efectiva involucra varios pasos críticos: 1. **Desarrollo de una base teórica sólida**: * Requiere una comprensión profunda del tema a investigar. * Implica una revisión exhaustiva de la literatura existente. 2. **Generación de ítems**: * Creación cuidadosa de preguntas que reflejen los constructos a medir. * Puede involucrar técnicas deductivas (basadas en definiciones) o inductivas (basadas en respuestas de los participantes). 3. **Evaluación de la validez de contenido**: * Revisión por expertos para asegurar que las preguntas miden lo que deben medir. * Puede requerir múltiples rondas de revisión y ajuste. 4. **Administración del cuestionario**: * Selección cuidadosa de la muestra. * Implementación del cuestionario, que puede requerir recursos significativos. 5. **Evaluación de las propiedades psicométricas**: * Análisis factorial para identificar la estructura subyacente de los ítems. * Evaluación de la confiabilidad interna. 6. **Refinamiento y validación**: * Posible eliminación o modificación de ítems basada en los análisis. * Repetición del proceso con nuevas muestras para confirmar la estructura. ### Reflexión: ¿Por qué esto es un problema? Ahora que entendemos lo que implica crear una encuesta efectiva, podemos ver por qué esto representa un desafío significativo para las empresas: 1. **Demanda de expertise**: El proceso requiere conocimientos especializados en estadística, psicometría y diseño de investigación que muchas empresas no poseen internamente. 2. **Inversión de tiempo**: Cada paso del proceso puede tomar semanas o incluso meses, lo que puede no ser compatible con la necesidad de tomar decisiones rápidas en el entorno empresarial actual. 3. **Costos elevados**: Ya sea que se realice internamente o se contrate a expertos externos, el proceso implica una inversión significativa de recursos financieros. 4. **Inflexibilidad**: Una vez diseñada, modificar una encuesta para adaptarse a nuevas necesidades o cambios en el mercado implica repetir gran parte del proceso. 5. **Riesgo de datos poco fiables**: Si se omiten o se realizan apresuradamente algunos pasos para ahorrar tiempo o dinero, se corre el riesgo de obtener datos poco confiables o inválidos. 6. **Brecha entre teoría y práctica**: Mientras que el proceso académico enfatiza el rigor, las empresas a menudo necesitan soluciones más ágiles y prácticas. Estas realidades plantean preguntas importantes: * ¿Pueden las empresas, especialmente las más pequeñas, permitirse este nivel de inversión en el diseño de encuestas? * ¿Es sostenible depender de un método que requiere tanto tiempo y recursos en un entorno empresarial que demanda agilidad? * ¿Existen alternativas más eficientes para obtener información valiosa de los clientes y del mercado? La complejidad y el costo del diseño efectivo de encuestas sugieren que, aunque las encuestas pueden ser valiosas, las empresas necesitan explorar métodos complementarios o alternativos para recopilar información de manera más ágil y económica, sin comprometer la calidad de los datos obtenidos. ## Toma de Decisiones Un estudio de McKinsey & Company, en colaboración con AlphaSights y Gerson Lehrman Group, reveló que aunque el 93% de los más de 260 líderes de CX utilizan encuestas como principal herramienta, solo el 15% está satisfecho con ellas y apenas el 6% cree que son útiles para decisiones estratégicas (Diebner et al., 2021). ### ¿Qué está fallando en las encuestas? El informe de McKinsey destaca cuatro problemas clave: * **Limitadas**: Solo capturan una fracción de la experiencia del cliente. * **Reactivas**: Responden a los problemas cuando ya es demasiado tarde. * **Ambiguas**: No explican las causas raíz de los problemas. * **Desenfocadas**: No están conectadas al retorno de inversión (ROI), lo que debilita su valor estratégico. Estas limitaciones hacen evidente la necesidad de nuevas formas de capturar la voz del cliente y obtener datos accionables que realmente guíen decisiones empresariales. ### Mirando hacia el futuro A medida que las encuestas tradicionales pierden relevancia en la medición de la experiencia del cliente, surge una oportunidad única para innovar en la forma en que las empresas capturan y analizan la voz de sus clientes. La necesidad de soluciones que aborden los problemas de participación, precisión y acción es más urgente que nunca. El futuro pertenece a aquellas herramientas que puedan superar las limitaciones actuales, permitiendo a las empresas tomar decisiones basadas en datos más auténticos, inmediatos y significativos. La evolución hacia métodos más ágiles, precisos y conectados a resultados estratégicos abrirá un panorama alentador en la gestión de la experiencia del cliente. Las herramientas del futuro no solo medirán mejor, sino que transformarán la manera en que las empresas comprenden y responden a las expectativas de sus clientes. ### Referencias‍ * Diebner,R., Malfara, D., Neher, K., Thompson, M., & Vancauwenberghe, M. (2021). Predicción: El futuro de la experiencia delcliente. *McKinsey & Company*. [https://www.mckinsey.com/capabilities/growth-marketing-and-sales/our-insights/prediction-the-future-of-cx/es-CL#/](https://www.mckinsey.com/capabilities/growth-marketing-and-sales/our-insights/prediction-the-future-of-cx/es-CL#/) * Galesic,M., & Bosnjak, M. (2009). Effects of questionnaire length onparticipation and indicators of response quality in a websurvey. *Publicopinion quarterly*, *73*(2),349-360. * Hinkin,T. R. (1998). A brief tutorial on the development of measures for usein survey questionnaires. *Organizationalresearch methods*, *1*(1),104-121. * Holbrook,A. L., Krosnick, J. A., & Pfent, A. (2008).The causes and consequences of response rates in surveys by the newsmedia and government contractor survey research firms. *Advancesin telephone survey methodology*,499-528. * Krosnick,J. A. (1991). Response strategies for coping with the cognitivedemands of attitude measures in surveys. *Appliedcognitive psychology*, *5*(3),213-236. # Plataforma autoservicio Source: https://woku.app/docs/fundamentals/self-service-platform Crea viajes, escucha a tus clientes y administra tu equipo desde woku Tu equipo configura la escucha desde el panel de woku: crea viajes, elige qué evaluar en cada momento y comparte las herramientas por enlace, QR, email o WhatsApp. ## Viajes y herramientas Empieza por [crear tu primer viaje](/docs/core-concepts/journeys). Cada momento usa una herramienta: Woku para entender varias facetas, CSAT para satisfacción, CES para esfuerzo y NPS para recomendación. Puedes configurar esperas y conectar el webhook de cada momento. También puedes crear herramientas independientes y [formularios](/docs/core-concepts/forms) para recopilar datos estructurados. Con el [agente de follow up](/docs/core-concepts/follow-up-agent), un agente de inteligencia artificial conversa por WhatsApp o correo con cada cliente que deja un comentario de mejora. ## Clientes y contexto Los clientes reúnen su identidad y respuestas. Los trackers permiten segmentar por viaje, momento, tienda u otro contexto del negocio. La [API pública](/docs/development/api) permite integrar la escucha con tus sistemas. ## Análisis Consulta las estadísticas y reportes propios de las herramientas, el [análisis de texto](/docs/reports/text-analysis) y el [espacio de reseñas](/docs/reports/reviews-space). [Estudio de datos](/docs/reports/data-studio) está disponible en Corporate. ## Acción Configura grupos de [planes de acción](/docs/action-plans/create-plan) para trabajar sobre señales recurrentes. Los [tickets de soporte](/docs/guides/support-tickets), disponibles en Corporate, permiten atender casos individuales. ## Equipo y seguridad Administra usuarios, roles y accesos de tu empresa. Revisa [autenticación y permisos](/docs/security/authentication) para configurar tu operación. # Solución Source: https://woku.app/docs/fundamentals/solution Cómo woku resuelve el problema: escucha breve, contextual y a lo largo del journey Si el problema es que las encuestas tradicionales son largas, tardías y poco accionables, la solución no es hacer "una encuesta más bonita". Es cambiar la arquitectura de la escucha. woku convierte la voz del cliente en una **capa distribuida de micro-medición**: en lugar de una única encuesta al final, mide cada momento importante del recorrido con una herramienta breve, cercana al evento y enfocada en una sola pregunta relevante. ## La idea central La experiencia del cliente no ocurre en un solo instante. Se forma a lo largo de múltiples puntos de contacto, en distintos canales y momentos (Lemon & Verhoef, 2016). Medirla con una sola foto al final simplifica en exceso un fenómeno que sucede por episodios (Voorhees et al., 2017). Por eso woku no pregunta "todo, al final". Pregunta **poco, cerca del momento y solo donde importa**. La evidencia de McKinsey muestra que el desempeño sobre *journeys* completos predice mejor los resultados de negocio (recompra, churn, recomendación) que el desempeño en touchpoints aislados (Duncan, Jones & Rawson, 2013). > [!NOTE] > > El objetivo no es medir **más**, sino medir **mejor** los tramos que realmente organizan la percepción total de la experiencia. ## Medir en el momento de verdad Cada etapa del recorrido tiene una pregunta distinta, con drivers distintos y equipos responsables distintos. woku asigna a cada momento la herramienta cuya señal tiene más valor operativo ahí. | Momento | Qué se juega | Se mide con | | - | - | - | | **Venta** | El cliente decide y compra | **CSAT** (satisfacción) | | **Entrega** | Recibe el producto o servicio | **woku** (escuchar y actuar) | | **Soporte** | Contacta a la empresa | **CES** (esfuerzo) | | **Postventa** | Usa y da seguimiento | **woku** (escuchar y actuar) | | **Fidelización** | Vuelve a comprar y recomienda | **NPS** (recomendación) | Medir cerca del evento reduce el sesgo de recuerdo y preserva el contexto de la experiencia (Shiffman, Stone & Hufford, 2008). No tiene sentido preguntar por el esfuerzo de un contacto de soporte semanas después, ni agotar al cliente con una batería larga cuando la experiencia ya se compuso de episodios separados. ## Por qué varias herramientas y no una sola No existe una métrica superior para todo el journey. Analizando 93 empresas en 18 industrias, de Haan, Verhoef y Wiesel concluyen que el poder predictivo depende del sector y del nivel de análisis, y que **combinar métricas predice mejor que apostar a un único número** (de Haan, Verhoef & Wiesel, 2015). Deloitte llega a un marco similar: una buena medición de experiencia requiere combinar niveles (relación, journey e interacción), no depender de uno solo. Cada herramienta responde una pregunta diferente: * **CSAT** para la satisfacción puntual después de un momento clave. Incluso escalas simples y cortas bastan para fines prácticos (Mittal et al., 2023). * **CES** para la fricción y el esfuerzo en interacciones donde el cliente necesita "lograr algo". Reducir esfuerzo es más importante para la lealtad en servicio que sorprender o deleitar (Dixon, Freeman & Toman, 2010). * **NPS** para la recomendación y la salud relacional de la marca, especialmente en etapas de lealtad (Bain & Company, n.d.). * **woku** para el feedback amplio y visual sobre un momento concreto, con el "por qué" en la reseña. ## El comentario abierto: de la señal a la causa El número dice *qué* pasó. El comentario abierto dice *por qué*. Es lo que vuelve accionable a toda la medición: captura feedback auténtico e inesperado y conecta la señal cuantitativa con la causa raíz (Ordenes et al., 2014). En woku, toda herramienta permite acompañar el puntaje con una reseña corta en texto o audio, justo en el momento en que el contexto todavía está fresco. En CSAT, CES y NPS la reseña es opcional; en un woku es obligatoria. ## Dos advertencias honestas > [!WARNING] > > **Fragmentar no es saturar.** Dividir la escucha en momentos mejora la calidad, pero solo si se dispara en experiencias realmente relevantes y con reglas de frecuencia claras (Bain & Company, n.d.; Andreadis & Kartsounidou, 2020). Demasiadas solicitudes cansan al cliente igual que una encuesta larga. > [!WARNING] > > **El comentario abierto necesita cierre de loop.** Sin un sistema para analizar el texto y actuar, la escucha se convierte en un buzón sin aprendizaje (Ordenes et al., 2014). woku no pretende reemplazar toda investigación relacional o de marca. Resuelve mejor lo que las encuestas tradicionales hacen peor: la captura continua, contextual y accionable de la voz del cliente en la operación de todos los días. ### Referencias * Andreadis, I., & Kartsounidou, E. (2020). The impact of splitting a long online questionnaire on data quality. *Survey Research Methods, 14*(1). * Bain & Company. (n.d.). *Three types of Net Promoter Scores*. Net Promoter System. * de Haan, E., Verhoef, P. C., & Wiesel, T. (2015). The predictive ability of different customer feedback metrics for retention. *International Journal of Research in Marketing, 32*(2), 195-206. * Dixon, M., Freeman, K., & Toman, N. (2010). Stop trying to delight your customers. *Harvard Business Review, 88*(7/8), 116-122. * Duncan, E., Jones, C., & Rawson, A. (2013). *The truth about customer experience*. McKinsey & Company. * Lemon, K. N., & Verhoef, P. C. (2016). Understanding customer experience throughout the customer journey. *Journal of Marketing, 80*(6), 69-96. * Mittal, V., Han, K., Frennea, C., Blut, M., Shaik, M., Bosukonda, N., & Sridhar, S. (2023). Customer satisfaction, loyalty behaviors, and firm financial performance: What 40 years of research tells us. *Marketing Letters, 34*, 171-187. * Ordenes, F. V., Theodoulidis, B., Burton, J., Gruber, T., & Zaki, M. (2014). Analyzing customer experience feedback using text mining. *Journal of Service Research, 17*(3), 278-295. * Shiffman, S., Stone, A. A., & Hufford, M. R. (2008). Ecological momentary assessment. *Annual Review of Clinical Psychology, 4*, 1-32. * Voorhees, C. M., Fombelle, P. W., Gregoire, Y., Bone, S., Gustafsson, A., Sousa, R., & Walkowiak, T. (2017). Service encounters, experiences and the customer journey. *Journal of Business Research, 79*, 269-280. # Herramientas Source: https://woku.app/docs/fundamentals/tools Las herramientas de woku para medir la experiencia: woku, NPS, CSAT, CES, Flow y Forms woku no es una sola herramienta, sino un conjunto de instrumentos breves que comparten la misma filosofía: rápido, visual, sin fricción y con el "por qué" en un comentario. Cada uno responde una pregunta distinta y se ubica en el momento del recorrido donde su señal vale más. | Herramienta | Qué mide | Escala | Cuándo usarla | | - | - | - | - | | **woku** | Opinión sobre un momento | 1 a 5 estrellas + reseña | Feedback amplio de un evento, producto o interacción | | **CSAT** | Satisfacción | 1 a 5 | Justo después de un momento clave (ej. la compra) | | **CES** | Esfuerzo / facilidad | 1 a 5 | Interacciones donde el cliente debe "lograr algo" (soporte, postventa) | | **NPS** | Recomendación | 0 a 10 | Lealtad y salud relacional de la marca | | **Flow** | Varios momentos en una sesión | No aplica | Experiencias con varias etapas | | **Forms** | Datos estructurados | No aplica | Datos concretos y verificables | ## woku Un **woku** es una representación visual de un producto, servicio o proceso para captar la opinión del cliente de forma rápida. El cliente califica de **1 a 5 estrellas** y deja una **reseña en texto o audio**, sin preguntas largas de por medio. ![Demostración de un woku en un iPhone: el usuario califica con 5 estrellas, deja un comentario, ingresa su correo y envía la reseña, seguido de una animación de agradecimiento.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/review-iphone.gif?s=57478f7aaec4ac9d20fb4f8058ca74b1) **Calificación de un woku en la interfaz de celular.** Su fuerza es integrarse en momentos clave del recorrido y capturar retroalimentación en tiempo real. El cliente tarda menos de dos minutos, frente a los 15 o más de una encuesta tradicional. En un woku el **comentario es el corazón**: siempre acompaña a la estrella para explicar el porqué. ## NPS El **NPS** (Net Promoter Score) mide la **lealtad y la recomendación**. Se basa en una sola pregunta: *¿qué tan probable es que recomiendes esta empresa, producto o servicio?* El cliente responde en una escala de **0 a 10** y queda clasificado: * **Detractores** (0 a 6): insatisfechos que pueden frenar tu crecimiento. * **Pasivos** (7 a 8): satisfechos pero no comprometidos. * **Promotores** (9 a 10): leales que recomiendan activamente. El puntaje se calcula restando el % de detractores al % de promotores: un número entre -100 y 100. A diferencia de otras herramientas NPS, en woku el cliente puede acompañar su puntaje con una **reseña en texto o audio**, identificada o anónima. Así obtienes el número y el porqué. ## CSAT El **CSAT** (Customer Satisfaction) mide **qué tan satisfecho** quedó el cliente después de un momento concreto. La pregunta es fija y solo defines el sujeto a evaluar: *"En una escala de 1 a 5, ¿qué tan satisfecho estás con \{sujeto}?"*. * **Escala de 1 a 5.** El puntaje es **obligatorio**; el comentario (texto o audio) es **opcional**. * **Métrica principal:** el **promedio** de los puntajes. También verás el **top-2-box**: el porcentaje de respuestas con 4 o 5, y la distribución satisfecho / neutral / insatisfecho. * Se responde de forma **identificada (por email) o anónima**. Es ideal para el momento de la venta o cualquier punto donde la pregunta relevante es simplemente *"¿quedaste contento?"*. ## CES El **CES** (Customer Effort Score) mide el **esfuerzo**: qué tan fácil le resultó al cliente lograr lo que venía a hacer. La pregunta es fija y solo defines la acción: *"¿qué tan fácil fue ?"*. * **Escala de 1 a 5** (5 = muy fácil). Puntaje **obligatorio**, comentario **opcional**. * Misma métrica que CSAT: **promedio**, **top-2-box** y distribución. * Identificado por email o anónimo. CES brilla en **soporte, postventa, onboarding, devoluciones o trámites**: episodios donde reducir la fricción importa más que sorprender. > [!NOTE] > > CSAT y CES son espejo: misma escala (1-5), misma lógica de puntaje obligatorio y comentario opcional, mismas métricas. Cambian solo la pregunta y lo que miden: **satisfacción** (CSAT) vs **esfuerzo** (CES). ## Flow Un **Flow** encadena varios wokus en una sola sesión, opcionalmente precedidos por un **NPS** como primer paso. Sirve para experiencias con varios momentos relevantes que no caben en una sola pregunta: un evento (convocatoria, contenido, expositores, organización), una compra en tienda o una capacitación. El cliente abre un solo enlace y avanza con una barra de progreso ("1 de 4"). Si el Flow incluye NPS, ese es el primer paso, para capturar una lectura limpia antes de evaluar momentos puntuales. El email se pide una sola vez y se reutiliza en todos los pasos. ```mermaid theme={null} flowchart LR A[NPS opcional] --> B[Woku 1] --> C[Woku 2] --> D[Woku 3] --> E[Gracias] ``` Cada respuesta se guarda en su herramienta correspondiente (el NPS en su NPS, cada woku en el suyo), así tus reportes individuales siguen funcionando, con el contexto extra de que vinieron del mismo cliente en la misma sesión. ## Forms **Forms** captura **datos estructurados**, no opiniones. Mientras un woku mide con estrellas y reseña, un Form hace preguntas concretas con respuestas guardadas en campos definidos: texto, número, fecha, email, teléfono, selección única o múltiple. Úsalo cuando necesites datos puntuales y verificables: nombre de empresa, tipo de cliente, fecha de la experiencia, servicio contratado, inscripciones a un evento. El administrador elige los campos, su orden y cuáles son obligatorios, y define tres reglas: si permite respuestas anónimas, si el cliente se identifica por email o teléfono, y si puede responder solo una vez. La respuesta queda disponible para descargar como CSV o consumir desde tu sistema. ```mermaid theme={null} flowchart LR A[Diseñar formulario] --> B[Configurar reglas] --> C[Compartir enlace o QR] --> D[Cliente completa] --> E[Respuesta guardada] ``` Forms hereda lo que hace fácil a woku: mismo flujo para crear, compartir (QR, enlace, envío masivo) y revisar, misma experiencia limpia para el cliente y los mismos reportes. # Primera medición Source: https://woku.app/docs/getting-started/first-measurement Crea y comparte tu primera medición con cada herramienta: woku, CSAT, CES, NPS, Flow y Forms Todas las herramientas de woku siguen el mismo ritmo: **crear → compartir → responder**. Creas la medición desde el panel, la compartes por QR, enlace o correo, y el cliente responde en menos de dos minutos sin iniciar sesión. Abajo, el primer paso con cada una. ## woku Un woku captura una opinión visual sobre un momento: **1 a 5 estrellas** más una reseña en texto o audio. **Crear.** En el menú principal presiona **"+ Crear woku"**, elige una imagen o video que represente lo que quieres evaluar y dale un nombre claro. ![Interfaz de creación de un woku, con una imagen de una actividad de trabajo en equipo y campos para el nombre, la carpeta y la empresa asociada.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/primer-woku-creacion.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=a614b39f9be9213466febfa539c939fe) **Vista de creación de un woku.** **Compartir.** Entra al woku y presiona **"Compartir"**: código QR, enlace o envío masivo por correo. **Responder.** El cliente ve la imagen y el nombre, califica de 1 a 5 estrellas y deja una reseña en texto o audio, identificado o anónimo. La reseña es obligatoria: el botón de enviar se habilita con al menos 4 caracteres de texto o una grabación de audio. ![Interfaz móvil donde el cliente califica un woku del 1 al 5 estrellas, con la leyenda 'Califica aquí, del 1 al 5'.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/evaluar-calificacion.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=21b27731b92694623f15ab67f78407d4) **Calificación de un woku en el celular.** ## CSAT Un CSAT mide **satisfacción** en escala de **1 a 5** tras un momento clave, como la compra. **Crear.** Entra a la sección **CSAT** y presiona **"+ Crear CSAT"**. Define: 1. **Nombre**: identifica la herramienta. Por ejemplo, "CSAT post compra". 2. **Sujeto a evaluar**: completa la pregunta fija *"¿Qué tan satisfecho estás con \{sujeto}?"*, por ejemplo "tu compra". 3. **Audiencia**: a quién está dirigido. **Compartir.** Mismas opciones: QR, enlace o envío masivo por correo. **Responder.** El cliente califica de 1 a 5 (puntaje obligatorio) y puede dejar un comentario opcional en texto o audio, identificado por email o anónimo. **Resultados.** El reporte muestra el **promedio**, el **top-2-box** (% de respuestas con 4 o 5) y la distribución satisfecho / neutral / insatisfecho. ## CES Un CES mide el **esfuerzo**: qué tan fácil le resultó al cliente lograr algo. Es el gemelo del CSAT, con la misma escala de **1 a 5** y las mismas métricas. Ideal para soporte y postventa. **Crear.** Entra a la sección **CES** y presiona **"+ Crear CES"**. Define: 1. **Nombre**: por ejemplo, "CES atención de soporte". 2. **Acción a evaluar**: completa la pregunta fija *"¿Qué tan fácil fue ?"*, por ejemplo "resolver tu problema". 3. **Audiencia**. **Compartir** y **responder** funcionan igual que en CSAT: puntaje 1 a 5 obligatorio, comentario opcional en texto o audio, identificado o anónimo. **Resultados.** Promedio, top-2-box y distribución, igual que CSAT. ## NPS Un NPS mide **recomendación** en escala de **0 a 10**. **Crear.** Entra a la sección **NPS** y presiona **"+ Crear NPS"**. Define: 1. **Nombre**: por ejemplo, "NPS post evento Q1". 2. **Mensaje**: la pregunta que verá el cliente, por ejemplo "¿Qué tan probable es que recomiendes este evento a un colega?". 3. **Audiencia**. **Compartir.** QR, enlace o envío masivo por correo. **Responder.** El cliente califica de 0 a 10, con comentario opcional en texto o audio, identificado o anónimo. **Resultados.** El reporte muestra el puntaje NPS en tiempo real y el conteo de promotores, pasivos y detractores. ## Flow Un Flow encadena **varios wokus** en una sola sesión, con un **NPS opcional** al inicio. Se arma a partir de wokus que ya existen: si aún no los tienes, créalos primero. **Crear.** Entra a la sección **Flows** y presiona **"+ Crear Flow"**. Define: 1. **Nombre**: por ejemplo, "Recorrido evento Q1". 2. **NPS opcional**: elige una herramienta NPS para iniciar el recorrido, o déjalo sin NPS. 3. **Wokus**: selecciona uno o más en el orden en que aparecerán. **Compartir.** El cliente recibe **un solo enlace**, no uno por woku. **Responder.** Avanza con una barra de progreso ("Paso 2 de 4"): responde el NPS si existe y luego cada woku. El email se pide una sola vez. **Resultados.** Cada respuesta se guarda en su woku y NPS correspondiente; en la vista del Flow ves cuántos iniciaron y terminaron el recorrido. ## Forms Un Form captura **datos estructurados** (texto, número, fecha, email, teléfono, selección) en lugar de una opinión. **Crear.** Entra a la sección **Forms** y presiona **"+ Crear Form"**. Define: 1. **Nombre**: por ejemplo, "Inscripción Capacitación Excel". 2. **Campos**: agrégalos con su tipo, etiqueta, obligatoriedad y opciones cuando aplique. 3. **Ajustes**: respuestas anónimas, identificación por email o teléfono, y si se limita a una respuesta por persona. **Compartir.** QR, enlace o envío masivo por correo. **Responder.** El cliente completa los campos; los obligatorios no permiten avanzar vacíos. Si pides email, verifica su correo y la respuesta queda registrada. **Resultados.** Ves la cantidad de respuestas, el detalle por campo y la exportación a CSV. # Instalación Source: https://woku.app/docs/getting-started/installation Instala woku como aplicación web progresiva en tu computadora o celular woku es una aplicación web progresiva, lo que significa que puedes descargarla directamente desde tu navegador, tanto en tu computadora como en tu celular. Así, siempre la tendrás a mano y podrás acceder a ella cuando lo necesites. ## Computadora Para descargar la aplicación, ingresa a [https://woku.app](https://woku.app/) desde el navegador de Google Chrome o Microsoft Edge. Luego, haz clic en el botón de **"Iniciar sesión"**. En la barra de direcciones, en la esquina superior derecha, verás el ícono de "Instalar" en Google Chrome o el ícono de "Aplicaciones" en Microsoft Edge, que te permitirá instalar la aplicación. ![Vista parcial de la barra de direcciones en Google Chrome, mostrando opciones como el botón para instalar aplicaciones web (resaltado), el ícono de traducción, el botón de agregar a favoritos, el ícono del perfil del usuario y el menú desplegable.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/chrome-install-icon.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=1976e2375ac79e0a651977f6bea191e8) **Ícono de "Instalar" en Google Chrome** ![Vista parcial de la barra de direcciones del navegador Microsoft Edge. Se muestran varias opciones: el ícono de 'Instalar' para aplicaciones web (resaltado en un círculo azul), el ícono para traducción de páginas, el ícono para agregar a favoritos, un botón de pestañas, el botón para ver varias pestañas a la vez, un ícono de reloj con historial o colecciones, el ícono del perfil del usuario, y el menú desplegable con más opciones, junto con el logo de Microsoft Edge.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/edge-install-icon.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=43a8f7166884c0a9de4ad3193b5fa578) **Ícono de "Aplicaciones" en Microsoft Edge** Haz clic en él, y cuando aparezca el mensaje, simplemente presiona **"Instalar"**. ¡Y listo! Ya tendrás woku en tu computadora para usarlo cuando quieras. ## Celular Para descargar la aplicación, ingresa a [https://woku.app](https://woku.app/) desde tu navegador. Si tienes un iPhone, usa Safari, y si usas un dispositivo Android, abre Google Chrome. Una vez ahí, haz clic en el botón **"Iniciar sesión"**. ### Para Apple Desde Safari, presiona el ícono de "Compartir" en el menú, justo debajo de la barra de navegación. ![Interfaz de la pantalla de inicio de sesión de woku en un dispositivo iPhone, visualizada en el navegador Safari. En la barra de direcciones se muestra la URL 'admin.woku.app'. El formulario de inicio de sesión pide el nombre de usuario o email y la contraseña, con un botón para recuperar la contraseña si se ha olvidado. El botón principal dice 'Ingresa tus datos' acompañado de un ícono de dedo apuntando. Debajo se ofrece la opción de registrarse si no se tiene una cuenta. En la parte inferior, se ven íconos de redes sociales como TikTok, Instagram, LinkedIn y Facebook. Además, en la barra de herramientas de Safari se resalta el ícono para compartir la página.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/apple-safari-login.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=7e1107940fa8ca0025edaa10428e02b0) **Pantalla de inicio de sesión de woku en un iPhone usando Safari** Luego, desplázate hacia abajo entre las opciones hasta encontrar **"Agregar a Inicio"**. ![Botón 'Agregar a Inicio' para instalar la aplicación web en el iPhone](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/apple-add-to-home.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=9449e687bb20efef2ff2fdff2852f596) **Botón "Agregar a Inicio" para instalar la aplicación web en el iPhone** Finalmente, haz clic en **"Agregar"**. ¡Listo! Ahora tienes woku instalado en tu celular. ![Pantalla en un iPhone mostrando la opción para agregar woku a la pantalla de inicio desde Safari. El usuario puede personalizar el nombre del ícono que aparecerá en su pantalla de inicio, en este caso 'woku', con la dirección 'https://admin.woku.app'. El botón 'Agregar' está resaltado en la parte superior derecha, listo para completar la acción.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/apple-confirm-add.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=32ee67b0b9fb91a34984c19383a5dab3) **Botón "Agregar" para añadir la aplicación de woku a la pantalla de inicio en iPhone** ### Para Android Desde Google Chrome, presiona el ícono de "Menú de opciones" en el menú, en de la barra de direcciones. ![Pantalla de inicio de sesión en woku desde un dispositivo Android utilizando el navegador Google Chrome. En la barra de direcciones se muestra 'admin.woku.app/auth', con el ícono de los tres puntos (menú de opciones) resaltado en la parte superior derecha. La pantalla de inicio de sesión pide el nombre de usuario o email y la contraseña, con un botón de 'Olvidé mi contraseña' y otro botón para ingresar los datos. En la parte inferior, se encuentran enlaces a redes sociales como TikTok, Instagram, LinkedIn y Facebook, y un enlace para registrarse si no se tiene cuenta.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/android-chrome-login.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=eed1730d49cce45611fa352e355bb1d7) **Interfaz de inicio de sesión en woku desde un dispositivo Android con el menú de opciones de Google Chrome resaltado** Una vez en el menú, desplaza hacia abajo y selecciona la opción "**Agregar a pantalla principal**". ![Pantalla en un dispositivo Android mostrando el menú de opciones de Google Chrome, donde se ha desplegado el menú tras seleccionar los tres puntos en la parte superior derecha. Está resaltada la opción 'Agregar a la pantalla principal', que permite crear un acceso directo a la aplicación web. Otras opciones visibles en el menú incluyen 'Nueva pestaña', 'Historial', 'Descargas', 'Favoritos', 'Buscar en la página', y 'Configuración'.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/android-menu.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=5d755ff6e6728b02b7815504cc3b7cb1) **Opción "Agregar a la pantalla principal" resaltada en el menú de opciones de Google Chrome en Android** Luego, en la hoja inferior (bottom sheet), selecciona la opción "**Instalar**". ![Pantalla en un dispositivo Android mostrando una hoja inferior (bottom sheet) en la parte inferior con dos opciones: 'Instalar', que permite agregar woku a la pantalla principal del dispositivo, y 'Crear accesos directos', que crea accesos abiertos en Google Chrome. La opción 'Instalar' está seleccionada y resaltada, permitiendo agregar la aplicación web de woku a la pantalla de inicio.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/android-bottom-sheet.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=681db8adfb950da5c55934a8cee46f0f) **Opción "Instalar" seleccionada para agregar woku a la pantalla principal en Android** Finalmente, en el modal, selecciona "**Instalar**". ![Pantalla en un dispositivo Android mostrando un modal emergente para instalar la aplicación web de woku desde Google Chrome. El modal contiene dos opciones: 'Cancelar' para salir del proceso de instalación y 'Instalar' para agregar woku como aplicación a la pantalla principal del dispositivo. La opción 'Instalar' está resaltada, permitiendo proceder con la instalación. El nombre de la aplicación es 'woku' y la URL correspondiente es 'admin.woku.app'.](https://mintcdn.com/woku/4zVAR1XAPSMsEpMD/images/android-install-modal.png?fit=max\&auto=format\&n=4zVAR1XAPSMsEpMD\&q=85\&s=056c016457534746815b28ae520c60c7) **Modal de instalación de woku en Android desde Google Chrome** # Carpetas y herramientas Source: https://woku.app/docs/guides/folders-and-tools Organiza wokus y herramientas NPS, CSAT y CES en un solo árbol de carpetas: busca, compara cifras por tipo, mueve en lote y obtén el reporte y el CSV de una carpeta por API, SDK o MCP Una **carpeta** agrupa wokus y herramientas NPS, CSAT y CES **en un mismo árbol**. Puedes anidar carpetas dentro de carpetas, mover cualquier herramienta entre ellas y mirar una carpeta completa como una sola unidad: sus cifras, su reporte y un CSV con todas sus respuestas. Esta guía cubre cómo lo haces desde la API v1, los SDK oficiales y el servidor MCP. Los tres usan el mismo modelo. ## Cómo funciona * Una **carpeta** tiene un nombre, un color opcional y, si está anidada, una carpeta padre. La **raíz** es el nivel sin carpeta. * Cada **herramienta** (woku, NPS, CSAT o CES) vive en una sola carpeta o en la raíz. Las herramientas existentes siguen en la raíz hasta que las muevas. * Al **eliminar una carpeta** no se elimina nada de lo que contiene: sus subcarpetas, wokus y herramientas suben a la carpeta padre (o a la raíz). * Mover es siempre reversible y no cambia las respuestas ni los enlaces públicos de una herramienta. > [!NOTE] > > Los cuatro tipos usan escalas distintas (estrellas de 1 a 5, NPS de 0 a 10, CSAT y CES de 1 a 5), por eso woku **nunca los promedia entre sí**. Cada tipo muestra su cifra principal en su escala nativa. ## En la aplicación En woku, la vista **Herramientas** muestra el mismo árbol: carpetas arriba y, debajo, wokus y herramientas NPS, CSAT y CES con su cifra principal. Se puede ver en **Rejilla** o en **Lista**, filtrar por tipo y buscar en toda la empresa (también por **trackers**, ver más abajo). Puedes crear carpetas con color, arrastrar herramientas a una carpeta o usar **Mover a...**, y cada carpeta tiene su menú para editarla, eliminarla, configurar sus alertas y su acceso por WhatsApp, ver sus **Participantes** y abrir su reporte. La vista se puede **ordenar** por nombre, por herramientas creadas recientemente o por reseñas recientes. El **reporte de una carpeta** tiene dos pestañas: * **Análisis de texto** (la principal): el análisis con IA de todos los comentarios de la carpeta y sus subcarpetas, con la misma forma que el reporte de un woku (reconocimientos, oportunidades de mejora, nube de palabras y resumen). Mientras se genera, una barra de avance muestra que el reporte sigue en camino. * **Métricas por herramienta**: cuatro tarjetas (una por tipo, cada una en su escala) con el cambio frente al periodo anterior, la evolución del resultado en el tiempo, la distribución de notas, de dónde vienen las respuestas y las herramientas que conviene atender primero. Se puede ver el historial completo o los últimos 7, 30 o 90 días. El período elegido en el reporte también acota el CSV, y **Programar envío** manda el reporte por correo cada mes, quincena o semana, o una sola vez (ver [Envíos programados de reportes](/docs/reports/scheduled-reports)). Todo lo que ves en la aplicación está disponible también por API, SDK y MCP, salvo el acceso por WhatsApp de una carpeta, que por ahora se configura solo desde la aplicación. ## Carpetas Usa `/v1/folders` para administrar el árbol. | Operación | Endpoint | | - | - | | Listar carpetas (todas, o las subcarpetas de una) | `GET /v1/folders` | | Crear una carpeta | `POST /v1/folders` | | Obtener una carpeta con sus estadísticas | `GET /v1/folders/:id` | | Renombrar, cambiar el color o definir los números de alerta de WhatsApp | `PATCH /v1/folders/:id` | | Mover una carpeta (o enviarla a la raíz) | `PATCH /v1/folders/:id/move` | | Eliminar una carpeta (su contenido sube al padre) | `DELETE /v1/folders/:id` | Cada carpeta incluye su ruta (`path`, por ejemplo `Posventa > Entrega`) y las estadísticas de su subárbol: cuántas herramientas hay de cada tipo, cuántas subcarpetas y cuántas reseñas. ```bash theme={null} curl --request POST https://clientapi.woku.app/v1/folders \ --header "Authorization: Bearer $WOKU_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "name": "Posventa", "color": "#3498db" }' ``` Para anidar una carpeta, envía `parentFolderId`. Para mover una carpeta a la raíz, usa `PATCH /v1/folders/:id/move` con `{ "parentFolderId": null }`. Una carpeta no puede moverse dentro de sí misma ni de una de sus subcarpetas. ## Crear una herramienta dentro de una carpeta Las creaciones de NPS, CSAT y CES aceptan `folderId` (los wokus siguen usando su propio flujo de creación y se mueven con `PATCH /v1/wokus/:id/move`). La carpeta debe ser de tu empresa; si no, la respuesta es `404`. ```bash theme={null} curl --request POST https://clientapi.woku.app/v1/csat-tools \ --header "Authorization: Bearer $WOKU_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "name": "Entrega", "question": "¿Qué tan satisfecho/a estás con la entrega?", "folderId": "" }' ``` Para mover una herramienta que ya existe: `PATCH /v1/nps-tools/:id/move`, `PATCH /v1/csat-tools/:id/move` o `PATCH /v1/ces-tools/:id/move`, con `{ "folderId": "" }` o `{ "folderId": null }` para la raíz. Todas las herramientas devuelven su `folderId` (`null` en la raíz). ## Buscar y listar herramientas `GET /v1/tools` devuelve en una sola lista las carpetas y las herramientas de **todos los tipos**, paginadas por cursor. | Parámetro | Qué hace | | - | - | | `folderId` | Lista el contenido directo de esa carpeta. Sin él, lista la raíz. | | `scope=company` | Lista todas las herramientas de la empresa en una lista plana. | | `q` | Busca en nombres y preguntas, sin distinguir mayúsculas ni acentos. La búsqueda abarca toda la empresa y también devuelve las carpetas que coinciden. | | `types` | Filtra por tipo: `woku`, `nps`, `csat`, `ces` (separados por coma). | | `sort` | `name` (por defecto), `-name`, `created`, `-created`, `lastResponse` o `-lastResponse` (fecha de la última respuesta; las herramientas sin respuestas quedan como las más antiguas). | | `createdFrom`, `createdTo` | Rango de fechas de creación. | | `trackers` | Chips de trackers, repetibles (`?trackers=TRR:00482&trackers=OC:2024`). Una herramienta coincide cuando tiene **todos**: el nombre del tracker se compara exacto y el valor de forma parcial y sin distinguir mayúsculas (`482` también coincide con `00482`). Máximo 10 chips. Como una búsqueda, abarca toda la empresa y no lista carpetas. Un tracker que la empresa no tiene no coincide con nada, y un chip sin nombre o sin valor responde `400`. | | `limit`, `cursor` | Tamaño de página (hasta 100) y cursor de la página siguiente (`nextCursor`). | | `foldersLimit`, `foldersCursor` | "Ver más" de carpetas: `foldersLimit` (1 a 100) pagina las carpetas del nivel; sin él se devuelven todas. Con `foldersCursor` (el `foldersNextCursor` anterior) se devuelve solo esa página de carpetas, sin herramientas. | La respuesta trae `folders`, `foldersNextCursor`, `tools`, `nextCursor` y `facets` (cuántas herramientas hay de cada tipo con los filtros aplicados). Cada herramienta incluye `type`, `name`, `folderId`, `reviewCount`, `lastResponseAt` y su cifra principal en escala nativa (`headline`). ## Cifras por tipo `GET /v1/tools/stats` entrega, para toda la empresa o para una carpeta y sus subcarpetas (`folderId`), las reseñas y la cifra principal de cada tipo, opcionalmente dentro de un periodo (`from`, `to`): | Tipo | Cifra principal | | - | - | | Woku | Promedio de estrellas (1 a 5) | | NPS | Puntaje NPS (de -100 a 100), con promotores, pasivos y detractores | | CSAT | Porcentaje de satisfechos (puntajes 4 y 5) | | CES | Promedio de esfuerzo (1 a 5) | Un tipo sin respuestas devuelve `null` como cifra. Si un tipo falla al calcularse, informa `{ "error": true }` y los demás siguen siendo válidos. ## Métricas por herramienta de una carpeta `GET /v1/folders/:id/metrics` entrega, para una carpeta y sus subcarpetas, las cifras de **cada** herramienta (woku, NPS, CSAT y CES) en un periodo, comparadas con el periodo anterior de la misma duración. | Parámetro | Qué hace | | - | - | | `days` | Periodo en días: `7`, `30` (por defecto) o `90`. Con `0` se calcula todo el historial y `previous` viene vacío (`count: 0` y cifras `null`). | La respuesta trae: * `tools`: una fila por herramienta con `type`, `id`, `name`, `totalResponses`, `lastResponseAt` y dos ventanas, `current` y `previous`, cada una con `count`, `headline` (la cifra en su escala nativa), `positive` y `negative` (porcentaje de respuestas positivas y negativas: 4 y 5 o 1 y 2, o promotores y detractores en NPS) y los conteos crudos `positiveCount`, `negativeCount` y `scoreSum` para combinar herramientas sin error de redondeo. * `daily`: las sumas diarias (en UTC) de ambos periodos por tipo (`count`, `scoreSum` y los conteos `positive` y `negative`), para dibujar una tendencia con cualquier agrupación. Las ventanas son días calendario UTC que terminan hoy, así que sumar `daily` del periodo da `current.count`. * `distribution`: cuántas respuestas hubo por nota en el periodo. En NPS la posición 0 es la nota 0 (11 posiciones); en el resto la posición 0 es la nota 1 (5 posiciones). Las escalas nunca se mezclan entre tipos. Una herramienta sin respuestas devuelve `null` como cifra. En el MCP, `get_folder_tools_metrics` devuelve `toolCount` y las herramientas con más respuestas (`limit`, 50 por defecto), y las sumas diarias solo con `includeDaily`. ```bash theme={null} curl "https://clientapi.woku.app/v1/folders/FOLDER_ID/metrics?days=30" \ --header "Authorization: Bearer $WOKU_API_KEY" ``` ## Mover en lote `POST /v1/tools/move` mueve hasta 200 elementos de tipos mezclados en una sola llamada. Es idempotente: mover elementos adonde ya están funciona sin error. Si falta un elemento o la carpeta de destino, no se mueve nada. ```json theme={null} { "items": [ { "type": "csat", "id": "" }, { "type": "woku", "id": "" }, { "type": "folder", "id": "" } ], "folderId": null } ``` Usa `"folderId": null` para enviar los elementos a la raíz. ## Reporte, PDF y CSV de una carpeta * `GET /v1/folders/:id/report` genera (y guarda) un reporte con IA sobre **todas** las herramientas de la carpeta y sus subcarpetas: reconocimientos, oportunidades de mejora, nube de palabras y resumen. Cada cita conserva el contexto de su herramienta. Como las escalas son distintas, el reporte no incluye una distribución de puntajes. Un reporte ya generado se reutiliza mientras no cambie la cantidad de reseñas; usa `regenerate=true` para forzar uno nuevo y `lang=es` o `lang=en` para el idioma. Una carpeta sin herramientas, o con menos de dos respuestas con comentario, devuelve un reporte vacío, no un error. * `GET /v1/folders/:id/pdf` descarga el reporte en un archivo PDF (`lang=es` o `lang=en`), con un desglose por tipo de herramienta (cantidad, respuestas y cifra principal en su escala nativa). No incluye distribución de puntajes. Es un archivo binario: está en la API y los SDK, y no en el servidor MCP. * `GET /v1/folders/:id/csv` descarga un archivo CSV con **una fila por respuesta** de todas las herramientas de la carpeta y sus subcarpetas: carpeta y ruta, tipo y nombre de la herramienta, puntaje con su escala, comentario, tipo de comentario (texto o audio), clasificación (reconocimiento o mejora), correo del cliente, canal y fecha. Un cliente que ya no existe deja la celda vacía, y una respuesta anónima aparece como `Anónimo`. La última columna es el teléfono del cliente. Con `from` y `to` (ISO 8601, `from` incluido y `to` excluido) trae solo las respuestas de ese período. ## Alertas de WhatsApp por carpeta Una carpeta puede avisar por WhatsApp cuando llega un comentario clasificado como **oportunidad de mejora** en cualquiera de sus herramientas: wokus, NPS, CSAT o CES. Los destinatarios son los números configurados en la carpeta. ```bash theme={null} curl --request PATCH https://clientapi.woku.app/v1/folders/FOLDER_ID \ --header "Authorization: Bearer $WOKU_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "whatsappAlertRecipients": [{ "whatsappId": "56912345678", "name": "Ana" }] }' ``` * `whatsappAlertRecipients` **reemplaza** la lista anterior (máximo 10); envía `[]` para quitar todos los números. El número va en formato E.164 sin el `+`. * Cada número puede llevar `sources` (`woku`, `nps`, `csat`, `ces`): los tipos de comentario que lo avisan. Si no lo envías, avisa por los cuatro. Los números que ya existían antes de esta función siguen recibiendo solo alertas de wokus. * Cada número puede llevar `allReviews`. Con `true` recibe **todas las reseñas** de esos tipos, también los reconocimientos, siempre en el mismo mensaje (empresa, herramienta, cliente, calificación y comentario) y en lugar del aviso de mejora; sin el campo o con `false` recibe solo las oportunidades de mejora. En el admin se elige al agregar el número en **Alertas por WhatsApp**, con el interruptor **Todas las reseñas** (apagado por defecto), y la lista muestra qué recibe cada número. Si un número está en una carpeta y en una de sus subcarpetas, manda la configuración de la carpeta más cercana a la herramienta. * Un número de una carpeta también recibe los avisos de las herramientas de sus subcarpetas, una sola vez aunque esté en varias. * Cada carpeta devuelve la lista en `whatsappAlertRecipients`. * Para que un viaje que crea una herramienta por pedido no sature a nadie, cada número recibe como máximo **5 avisos de herramientas (NPS, CSAT y CES) por hora**; los siguientes se descartan. Los reconocimientos de un número con `allReviews` tienen su propio cupo de 5 por hora, así que nunca le quitan espacio a las oportunidades de mejora. * El aviso se envía **una sola vez por respuesta** y cuenta como una notificación de WhatsApp de tu plan. Incluye la empresa, la herramienta con su carpeta, el cliente, el comentario y el puntaje en su escala. * En el MCP, `update_folder` acepta el mismo campo. ## Viajes en carpetas Cada viaje del cliente crea sus propias herramientas CSAT, CES y NPS, y miles de ellas si el viaje crea una por pedido. Para que no queden sueltas en la raíz, woku puede ordenarlas solas en el árbol **Viajes > viaje > momento**. * La organización es **opcional por empresa**. Se activa una vez y desde entonces las herramientas nuevas de cada momento se ubican en la carpeta de su momento. * Al activarla, una **pasada única en segundo plano** mueve las herramientas de los viajes existentes que aún no tienen carpeta. Es repetible sin efectos: no toca lo que ya tiene carpeta y una segunda corrida no cambia nada. * Si mueves una herramienta a otra carpeta, **no vuelve sola** a su sitio. Mover o renombrar las carpetas del árbol nunca rompe un viaje: el siguiente caso sigue creando su herramienta en la carpeta de su momento, donde esté ahora. * Las integraciones ordenan sus propias carpetas de la misma manera (por ejemplo, Shopify y Pancake). | Operación | Endpoint | | - | - | | Ver el estado (si está activa, si está en curso y cuánto falta) | `GET /v1/journey-folders` | | Activar y ejecutar la pasada única (responde `202`; `409` si ya está en curso) | `POST /v1/journey-folders/organize` | El estado incluye `enabled`, `enabledAt`, `organizedAt`, `organizing` y `pending` (viajes y herramientas que siguen sin carpeta). Consúltalo de vez en cuando mientras `organizing` sea `true`. ```bash theme={null} curl --request POST https://clientapi.woku.app/v1/journey-folders/organize \ --header "Authorization: Bearer $WOKU_API_KEY" ``` `GET /v1/journeys` y `GET /v1/journeys/:id` devuelven `folderId` (la carpeta del viaje) y `momentFolders` (la carpeta de cada momento, por su clave). Antes de organizar, `folderId` es `null` y `momentFolders` es `{}`. Las carpetas que crea woku (la raíz `Viajes`, cada viaje, cada momento y las de integraciones) informan su `origin` en `GET /v1/folders` y `GET /v1/tools`: `journeys-root`, `journey`, `journey-moment` o `integration`. Las carpetas de integraciones informan además `integrationProvider` (por ejemplo `shopify` o `pancake`). Tus propias carpetas tienen `origin: null`. ```ts theme={null} const status = await woku.journeyFolders.status(); if (!status.enabled) await woku.journeyFolders.organize(); const journey = await woku.journeys.get(journeyId); console.log(journey.folderId, journey.momentFolders); ``` En el servidor MCP, `get_journey_folders_status` y `organize_journey_folders` hacen lo mismo, y `get_journey` y `list_journeys` incluyen `folderId` y `momentFolders`. ## Participantes de una carpeta Cuando una carpeta reúne las herramientas de un programa con inscritos conocidos (un curso, una feria, una capacitación), puedes cargar la **lista de participantes** y ver, en cada herramienta de la carpeta y sus subcarpetas, quiénes **respondieron**, quiénes **faltan** y quiénes respondieron **más de una vez**. * La lista se carga pegando texto o subiendo un CSV: una persona por línea, con nombre, correo y/o teléfono (con código de país), separados por comas, punto y coma o tabulaciones. Se omite la fila de encabezado y las personas repetidas. Hasta 500 personas. Los contactos se guardan cifrados. * La lista se puede **editar**: agregar personas (las que ya están se omiten), quitar una por una o reemplazarla completa. * El cruce usa el correo y el teléfono de la persona contra los clientes que respondieron. Una respuesta **anónima** no se puede cruzar, por eso cada herramienta indica si acepta anónimos. Para un seguimiento completo, desactiva las respuestas anónimas en esa herramienta. * **Reenviar a quienes faltan** manda la herramienta de nuevo, por correo o WhatsApp, a quienes no han respondido. Antes de enviar se indica cuántas personas no tienen contacto para el canal elegido. Los reenvíos cuentan en [Envíos](/docs/configuration/sends). En la aplicación está en el menú de la carpeta, **Participantes**. Por API: * `GET /v1/folders/:id/participants`: la lista (cada persona con su `id`) y, por herramienta, los índices de `responded`, `missing` y `repeated`, más `outsideList` (respuestas anónimas o de personas fuera de la lista) y `anonymousAllowed`. * `PUT /v1/folders/:id/participants`: reemplaza la lista (`text`). * `POST /v1/folders/:id/participants`: agrega personas (`text`). * `DELETE /v1/folders/:id/participants/:participantId`: quita a una persona. * `DELETE /v1/folders/:id/participants`: elimina la lista. Las respuestas no se tocan. * `POST /v1/folders/:id/participants/resend`: reenvía una herramienta (`toolType`, `toolId`) por `channel` (`email` o `whatsapp`) a quienes faltan. ## SDK y MCP ```ts JavaScript theme={null} const folder = await woku.folders.create({ name: 'Posventa' }); await woku.csatTools.create({ name: 'Entrega', question: '¿Qué tan satisfecho/a estás?', folderId: folder.id }); for await (const tool of await woku.tools.list({ folderId: folder.id, types: ['csat', 'nps'] })) { console.log(tool.type, tool.name, tool.headline.value); } const stats = await woku.tools.stats({ folderId: folder.id }); await woku.tools.move({ items: [{ type: 'csat', id: toolId }], folderId: null }); const csv = await woku.folders.csv(folder.id, { from: '2026-09-01T00:00:00Z', to: '2026-10-01T00:00:00Z' }); const pdf = await woku.folders.pdf(folder.id, { lang: 'es' }); // Uint8Array const metrics = await woku.folders.metrics(folder.id, { days: 30 }); // por herramienta, frente al periodo anterior const tagged = await woku.tools.list({ trackers: ['TRR:00482'] }); const recent = await woku.tools.list({ sort: '-lastResponse' }); await woku.folderParticipants.replace(folder.id, 'Ana, ana@empresa.com'); const { participants, tools } = await woku.folderParticipants.get(folder.id); ``` ```python Python theme={null} folder = woku.folders.create({"name": "Posventa"}) woku.csat_tools.create({"name": "Entrega", "question": "¿Qué tan satisfecho/a estás?", "folderId": folder["id"]}) for tool in woku.tools.list({"folderId": folder["id"], "types": ["csat", "nps"]}): print(tool["type"], tool["name"], tool["headline"]["value"]) stats = woku.tools.stats({"folderId": folder["id"]}) woku.tools.move({"items": [{"type": "csat", "id": tool_id}], "folderId": None}) csv_text = woku.folders.csv(folder["id"], {"from": "2026-09-01T00:00:00Z", "to": "2026-10-01T00:00:00Z"}) pdf_bytes = woku.folders.pdf(folder["id"], {"lang": "es"}) metrics = woku.folders.metrics(folder["id"], {"days": 30}) # por herramienta, frente al periodo anterior tagged = woku.tools.list({"trackers": ["TRR:00482"]}) recent = woku.tools.list({"sort": "-lastResponse"}) woku.folder_participants.replace(folder["id"], "Ana, ana@empresa.com") participation = woku.folder_participants.get(folder["id"]) ``` Referencia completa en [SDK de JavaScript](/docs/development/sdk-javascript) y [SDK de Python](/docs/development/sdk-python). En el servidor MCP, un agente cuenta con `search_voc_tools` (con `trackers`), `get_voc_tools_stats`, `get_folder_tools_metrics`, `move_voc_tools`, `create_folder`, `update_folder`, `move_folder` y `delete_folder`. `get_folder_report` acepta `scope: "all"` para el reporte mixto y `format: "csv"` para las respuestas (también con `from` y `to`), `get_folder_participants`, `set_folder_participants`, `remove_folder_participant` y `resend_to_missing_participants` manejan los participantes, y `create_nps_tool`, `create_csat_tool` y `create_ces_tool` aceptan `folderId`. El playbook `organize_listening` de `woku_guide` guía el proceso. Consulta [Herramientas del MCP](/docs/mcp/tools). # Encuestas multi-idioma Source: https://woku.app/docs/guides/multilanguage-surveys Una sola encuesta con múltiples idiomas y selección automática según la preferencia del usuario o del navegador > [!NOTE] > > **Disponible en el plan Corporate.** Esta funcionalidad forma parte de las capacidades empresariales de woku. [Conversa con nuestro equipo comercial](https://woku.app/pricing). Las **encuestas multi-idioma** permiten **traducir una encuesta** y mantener **una sola encuesta con más de un idioma posible**. En lugar de duplicar la encuesta por cada idioma, defines un único formulario y agregas traducciones para cada idioma. El respondente ve la encuesta en su idioma sin que tengas que enviarle un enlace distinto. > [!NOTE] > > Una encuesta, varios idiomas. Los resultados de todos los idiomas se > consolidan en la misma encuesta: las respuestas son comparables y los > reportes no se fragmentan por idioma. ## Una sola encuesta, varios idiomas * Defines el contenido base de la encuesta (preguntas, opciones, textos de ayuda, mensajes de cierre) en su idioma principal. * Para cada idioma adicional, puedes agregar las **traducciones** de los mismos elementos. En los Forms, puedes escribirlas manualmente o dejar que woku las genere con IA. Después puedes revisarlas o modificarlas desde la configuración. La estructura de la encuesta es única; solo cambian los textos. * Si una traducción falta para algún elemento, se muestra el texto del **idioma principal** como respaldo, de modo que el respondente nunca ve un campo en blanco. **1. Crea la encuesta en su idioma principal** Construye las preguntas y textos como lo harías normalmente. **2. Agrega los idiomas** Selecciona los idiomas adicionales que quieres habilitar para la encuesta. **3. Traduce los textos** Completa la traducción de cada elemento (preguntas, opciones, mensajes) para cada idioma habilitado. **4. Publica** La encuesta queda disponible en todos los idiomas habilitados bajo el mismo enlace. ## Selección automática de idioma Cuando un respondente abre la encuesta, el idioma se elige **automáticamente** según: 1. La **preferencia explícita** del usuario, si está disponible (por ejemplo, el idioma asociado a su perfil o al contexto desde el que se le invitó). 2. La **preferencia del navegador** (`Accept-Language`), cuando no hay una preferencia explícita. 3. El **idioma principal** de la encuesta, como respaldo, si ninguno de los anteriores coincide con un idioma habilitado. El respondente también puede **cambiar el idioma manualmente** desde la propia pantalla de la encuesta cuando hay más de uno habilitado. ## Idiomas soportados Actualmente la plataforma soporta: | Idioma | Código | | - | - | | Español | `es` | | Inglés | `en` | > [!NOTE] > > La **arquitectura multi-idioma ya está implementada**: incorporar un > idioma adicional es un trabajo acotado, con un plazo estimado de **10 días** > desde su solicitud. Una vez incorporado, habilitarlo y traducir los textos > de una encuesta es autoservicio desde la interfaz. ## Garantías * **Una sola encuesta**: las respuestas de todos los idiomas se consolidan en el mismo formulario y son comparables en los reportes. * **Sin enlaces duplicados**: el mismo enlace sirve para todos los idiomas; la selección es automática. * **Respaldo seguro**: si falta una traducción, se muestra el idioma principal y nunca un campo vacío. # Tickets a SAC Source: https://woku.app/docs/guides/support-tickets woku evalúa cada opinión negativa y, cuando amerita atención, crea un ticket de soporte con IA y lo envía a tu plataforma de atención al cliente El módulo **Soporte** conecta la voz del cliente con tu equipo de atención. woku evalúa cada respuesta negativa que recibe y, si detecta un caso que amerita atención, construye un **ticket de soporte completo** y lo envía a la plataforma de atención al cliente (SAC) que hayas configurado. Tu equipo recibe el caso ya armado: qué pasó, qué pide el cliente y qué acción se sugiere, sin que nadie tenga que leer y transcribir la opinión original. ## Qué respuestas generan tickets Una respuesta entra al motor de tickets cuando cumple todas estas condiciones: * Está clasificada como **mejora** (requiere acción). Ver [Accionabilidad y sentimiento](/docs/core-concepts/actionability-and-sentiment). * El cliente está **identificado** y no eligió responder de forma anónima. * Es una respuesta de **producción**. Las respuestas de sandbox no generan tickets. * Existe al menos un **destino habilitado** en el módulo Soporte. Generan tickets las respuestas de **wokus, NPS, CSAT y CES** con comentario clasificado. Los formularios no generan tickets, pero sus respuestas sí forman parte del historial del cliente que la IA usa como contexto. ## Enrutamiento por trackers Antes de pasar por la IA, la respuesta se enruta a un destino según sus **trackers**, los atributos externos que acompañan a cada opinión (por ejemplo país, tienda o línea de negocio). * Cada destino define en qué casos recibe tickets mediante condiciones sobre trackers, agrupadas con **Y además** y **O si**: el destino coincide cuando algún grupo **O** tiene todas sus filas **Y** verdaderas. * Cada condición usa el operador **es igual a** (un valor exacto) o **es cualquier valor** (todos los valores del tracker, sin escribir uno por uno). Para escuchar varios trackers completos, agrega una condición **es cualquier valor** por cada tracker, unidas con **O si**. Hay un máximo de 20 condiciones por destino. * El ticket pertenece al **primer destino habilitado** cuyas condiciones coinciden con los trackers de la respuesta. * Si ninguna condición coincide, **no se crea ticket**. No existe un destino por defecto. ## Triage con IA Con el destino resuelto, la IA decide si el caso amerita escalar. Para eso recibe el **historial completo del cliente** (sus respuestas por herramienta, cuántas fueron negativas y desde cuándo es cliente) y el **Contexto para la IA** definido en el destino. Si escala, la IA construye el caso: título, severidad (**alta**, **media** o **baja**), resumen, descripción, hitos del historial, qué pide el cliente, acción sugerida, riesgo de fuga e idioma. Todo el contenido queda marcado como **Generado por IA**. > [!NOTE] > > La identidad del cliente (nombre, correo, teléfono) se agrega al ticket > de forma determinística y nunca pasa por el modelo de IA. ## Entrega al destino El envío es asíncrono y con **reintentos automáticos**: hasta 5 intentos con espera creciente entre cada uno. El timeline del ticket registra **Enviado al equipo de soporte** solo cuando el destino confirma la recepción. En Zendesk, además, se guarda el enlace al ticket remoto, visible como **Ver en el SAC**. Un destino de tipo email registra el envío al equipo, pero no guarda un enlace remoto porque el ticket viaja como correo. ## Destinos disponibles ### Zendesk Requiere una conexión Zendesk activa en **Empresa → Integraciones**. Al crear el destino eliges la cuenta conectada y, de forma opcional, un **Group ID** de Zendesk para que los tickets lleguen a un grupo específico. Revisa cómo conectar tu cuenta en [Conector Zendesk](/docs/integrations/zendesk). ### Servicio personalizado Envía los tickets por HTTP a cualquier sistema propio. Configuras: * **URL** y **método** de la petición. * **Autenticación**: ninguna, usuario y contraseña, token Bearer o clave API en un encabezado. La credencial se guarda cifrada y no se vuelve a mostrar. * **Template JSON** del cuerpo, con placeholders `{{...}}` que se reemplazan con los campos del caso. ### Email Envía el ticket a una o más direcciones de correo, sin depender de una integración externa. Al crear el destino agregas la lista de correos, hasta 20 direcciones. woku envía un correo con el resumen del caso, prioridad, cliente, comentario, qué necesita el cliente y un enlace para ver el ticket en woku. No requiere conexión ni credenciales. ## Configurar un destino Desde **Soporte → Nuevo destino** defines el destino en una sola pantalla: 1. **Destino**: el tipo de plataforma y un nombre descriptivo, por ejemplo `SAC Chile`. 2. **Conexión**: los datos de conexión según el tipo elegido. 3. **Contexto para la IA**: texto libre de hasta 2000 caracteres que la IA usa al decidir y redactar. Mientras más claro sea el contexto (qué cubre este destino, qué casos son críticos), mejor decide la IA. 4. **Qué tickets van a este destino**: las condiciones de enrutamiento por trackers, con una vista previa en lenguaje natural de la regla que estás armando. Las condiciones requieren trackers con datos, que se administran en **Empresa → Trackers**. Antes de guardar puedes usar **Probar conexión** para validar las credenciales contra el destino real. Los destinos se pueden **activar y desactivar** en cualquier momento. Un destino inactivo no recibe tickets nuevos. ## Seguimiento La vista principal de **Soporte** muestra la operación por período (día, semana, mes, año o histórico): tarjetas con los tickets creados y su severidad, y una tarjeta por destino con su estado. Al entrar a un destino ves su detalle y una tabla de tickets con nombre, herramienta, puntaje, severidad, resumen de la IA y fecha, con búsqueda y filtros. ## Detalle de un ticket Cada ticket muestra el origen de la opinión, el puntaje, el comentario original (con transcripción si fue audio), la categoría, el resumen, el caso construido por la IA, el riesgo de fuga, el historial y los datos del cliente, y el timeline con el estado de envío al destino. Puedes editar el **título**, la **severidad**, el **resumen** y la **categoría** del ticket antes o después del envío, por ejemplo para ajustar la prioridad que asignó la IA. ## Más información > **[Conector Zendesk](/docs/integrations/zendesk)** > > Conecta tu cuenta de Zendesk con un API token para alimentar los > destinos de tickets. ## Seguimiento con el agente de IA Un comentario de mejora, escrito o transcrito, de Woku, NPS, CSAT o CES inicia una conversación fuera de un Flow (ver [Agente de follow up](/docs/core-concepts/follow-up-agent)). Un puntaje solo no activa el agente. Las respuestas de Flow quedan excluidas, incluso con un solo paso o respuesta parcial, pero conservan su evaluación normal para tickets. Un instrumento individual de un Viaje sigue siendo elegible si su captura es standalone. El ticket inicial se procesa inmediatamente. Si el agente está esperando datos, el correo inicial lo indica en rojo. Al finalizar la conversación con al menos una respuesta del cliente, también por inactividad posterior a esa respuesta, el mismo ticket se enriquece con esa evidencia. Se conserva el ID interno y el caso externo; un segundo correo muestra el aviso verde y el destino habilitado actualiza su recurso original. Sin respuesta del cliente no hay segunda entrega. API y SDKs de gestión muestran `followUp` y `contentVersion`. `completed` solo indica cierre; `appliedSummaryVersion >= 1` indica evidencia aplicada. Las listas son ligeras y el hilo se consulta con clave secreta en `GET /v1/follow-ups/:id`, sin tokens de respuesta ni credenciales de transporte. MCP ofrece la lectura `get_follow_up`. Los registros históricos pueden omitir seguimiento. En tickets, `enrichmentState` distingue `processing`, `applied`, `failed` y `skipped`; `enrichmentReason` contiene un código estable del resultado. Un fallo conserva el caso anterior. Una `availableSummaryVersion` más reciente puede seguir pendiente aunque exista una versión aplicada. La confirmación de entrega al destino es independiente. El `reason` de la conversación informa códigos estables, como `summary_generation_failed`, sin errores del proveedor ni credenciales. # Inactivación automática de usuarios Source: https://woku.app/docs/guides/user-deactivation Inactivación de cuentas sin actividad con aviso previo y reactivación por administradores > [!NOTE] > > **Disponible en el plan Corporate.** Esta funcionalidad forma parte de las capacidades empresariales de woku. [Conversa con nuestro equipo comercial](https://woku.app/pricing). Para cumplir los requerimientos de gestión de accesos, Woku **inactiva automáticamente** a los miembros **sin actividad reciente** durante un período definido, con un aviso previo. El período es un **parámetro configurable** por empresa. ## Configuración En la configuración de la empresa, el campo **días hasta inactivación automática** define la ventana de inactividad permitida: * Es un **parámetro configurable** por empresa. * Valor por defecto: **90 días**. * **0 deshabilita** la inactivación automática. * Mínimo recomendado: 7 días. > [!NOTE] > > **Dónde se configura.** El parámetro de días hasta la inactivación > automática se administra como autoservicio desde la interfaz, en > **Empresa → Configuración**, ajustando el campo de días hasta > inactivación automática. > > Cualquier valor que definas (incluido `0` para deshabilitar) toma efecto > en la siguiente revisión diaria. ## Cómo funciona * En cada inicio de sesión exitoso se registra la fecha de último acceso del usuario. * Un proceso diario revisa, por empresa con la función habilitada, a los miembros activos: * **7 días antes** de cumplirse la ventana se envía un **aviso**. * Al **cumplirse** la ventana, el miembro pasa a estado **inactivo**. * Un miembro inactivo queda **bloqueado** para esa empresa hasta que un administrador o dueño lo reactive. * Las cuentas recién creadas no se inactivan de inmediato: la ventana se cuenta desde el último acceso o, si nunca ha ingresado, desde la fecha de alta. > [!NOTE] > > El aviso previo y la inactivación se notifican al miembro **dentro de la > aplicación** y **por correo electrónico**. ## Reactivar un usuario Un administrador o dueño puede reactivar a un miembro inactivo, lo que restablece su estado a activo y le devuelve el acceso. # Bienvenido a woku Source: https://woku.app/docs/index Documentación completa de woku, la plataforma para capturar la opinión de tus clientes ## ¿Qué es woku? **woku** es una plataforma diseñada para simplificar la forma en que las empresas capturan la opinión de sus clientes. A diferencia de las encuestas tradicionales, que pueden ser tediosas y largas, woku permite obtener retroalimentación rápida y efectiva en tiempo real. El corazón de la plataforma es la herramienta **woku**, una experiencia visual sin preguntas complejas que se integra sin fricciones en el recorrido del cliente. Sobre ese cimiento, woku ofrece más herramientas para cubrir distintos tipos de feedback: **NPS**, **CSAT**, **CES**, **Flow** y **Forms**. ## Las herramientas > **[woku](/docs/fundamentals/tools#woku)** > > Captura opiniones visuales con calificación de 1 a 5 estrellas y reseña en texto o audio. > **[NPS](/docs/fundamentals/tools#nps)** > > Mide la recomendación y la lealtad de tus clientes en escala de 0 a 10. > **[CSAT](/docs/fundamentals/tools#csat)** > > Mide la satisfacción tras un momento clave, en escala de 1 a 5. > **[CES](/docs/fundamentals/tools#ces)** > > Mide el esfuerzo del cliente en interacciones como soporte o postventa. > **[Flow](/docs/fundamentals/tools#flow)** > > Encadena varios wokus y un NPS opcional al inicio en una sola experiencia guiada. > **[Forms](/docs/fundamentals/tools#forms)** > > Captura datos estructurados con campos como texto, fecha, email y opciones de selección. ## Empezar rápidamente > **[Instalación](/docs/getting-started/installation)** > > Instala woku como aplicación web progresiva en tu computadora o celular. > **[Primera medición](/docs/getting-started/first-measurement)** > > Crea y comparte tu primera medición con cada herramienta: woku, CSAT, CES, NPS, Flow y Forms. ## Fundamentos > **[El problema](/docs/fundamentals/problem)** > > Entiende por qué las encuestas tradicionales ya no funcionan y cómo woku > ofrece una solución. ## Desarrollo > **[Guía de Integración API](/docs/development/api)** > > Integra woku en tus aplicaciones con la API v1: wokus, reportes NPS y trackers > externos. > **[SDK de React Native](/docs/development/sdk-react-native)** > > Captura calificaciones woku y NPS (texto y audio) desde tu app React Native, > con buffer offline. ## Seguridad > **[Seguridad](/docs/security/index)** > > Conoce los controles de seguridad y autenticación de woku: MFA, sesiones, > audit log, anti brute force, headers y CSP, y allowlist de IPs. ## Configuración ## Planes de acción > **[Crear un plan de acción](/docs/action-plans/create-plan)** > > Convierte un hallazgo en un seguimiento accionable: pasos, responsables, > fechas límite y notificaciones de vencimiento. > **[Tablero Kanban](/docs/action-plans/kanban)** > > Mueve los planes entre estados arrastrando tarjetas y sigue el avance de > pasos en tiempo real. ## Reportes y analítica > **[Data Studio (agente de IA)](/docs/reports/data-studio)** > > Describe lo que necesitas y un agente de IA genera un dashboard interactivo > y publicable sobre tus datos. ## Operación y usuarios > **[Inactivación de usuarios](/docs/guides/user-deactivation)** > > Inactivación automática de cuentas sin actividad, con aviso previo y > reactivación por administradores. # Conector Pancake Source: https://woku.app/docs/integrations/pancake Conecta Pancake POS y tu inbox de Pancake con woku y acompaña a cada cliente con un viaje de 5 etapas: preventa, venta, entrega, posventa y lealtad, sin escribir código El **conector Pancake de woku** convierte cada conversación y cada pedido de tu operación en Pancake en un **viaje de cliente** de hasta cinco etapas: la **preventa** (la conversación que no terminó en venta), la **venta**, la **entrega**, la **posventa** de los productos y la **lealtad**. Tú decides qué etapas se activan, cuándo se envía cada una, por qué canal y con qué mensaje. woku invita al cliente por **WhatsApp o email**, gestiona los recordatorios y organiza todo en carpetas por tienda. No modifica tu operación en Pancake: solo lee las conversaciones etiquetadas y los pedidos para crear las evaluaciones. ## Qué productos de Pancake usa | Producto | Qué aporta al viaje | | - | - | | **Inbox de Pancake** (pancake.vn, tus páginas de WhatsApp, Facebook, Instagram) | La señal de **preventa**: una conversación que tu equipo etiqueta como cerrada sin venta | | **Pancake POS** (pos.pages.fm) | Las señales de **venta**, **entrega** (estado Recibido) y **cancelación** de cada pedido | | **Skydropx** (opcional) | La señal de **entrega** cuando el paquete llega. Se conecta una sola vez desde **Empresa → Integraciones → Skydropx** (su propia tarjeta) y woku correlaciona cada entrega con el pedido de Pancake por la referencia | > [!NOTE] > > En Latinoamérica el inbox de Pancake se comercializa a veces como "Pancake CRM". Este conector > trabaja con el inbox (las conversaciones y sus etiquetas) y con Pancake POS (los pedidos). El > producto crm.pancake.vn no es necesario. ## Las 5 etapas del viaje | Etapa | Qué mide | Cuándo se dispara | | - | - | - | | **Preventa** | Experiencia de la atención por chat (reseña woku) | Cuando una conversación del inbox recibe la **etiqueta de preventa** que configuraste. Se envía **al día siguiente**, dentro de un horario, y se **cancela** si ese cliente compra antes | | **Venta** | Satisfacción con la compra (encuesta CSAT) | Cuando el pedido pasa a **Confirmado** en POS (o al estado que elijas) | | **Entrega** | Experiencia de entrega (reseña woku) | Cuando el pedido pasa a **Recibido** en POS o cuando Skydropx informa la entrega | | **Posventa** | Evaluación de los **productos** del pedido (reseña woku o Flow) | Unos días **después de la entrega** | | **Lealtad** | Recomendación (encuesta NPS) | Unos días **después de la entrega**, después de la posventa | Cada etapa es independiente: la activas o desactivas, ajustas su timing, su canal y su mensaje desde la configuración en woku. Las respuestas llegan como cualquier otra reseña o encuesta: alimentan tus métricas y reportes, además de los **tickets de soporte** y los **planes de acción** que la integración deja configurados (ver "Tickets de soporte y planes de acción" más abajo). > [!NOTE] > > La etapa de **entrega** necesita una señal de entrega. Puede venir de POS (cuando tu equipo marca > el pedido como **Recibido**) o de **Skydropx** (cuando el paquete llega). Skydropx se conecta una > sola vez desde **Empresa → Integraciones → Skydropx** y woku correlaciona la entrega con el pedido > de Pancake por la referencia. Si ninguna señal llega, la etapa se omite y la **posventa** corre > igual usando un **plazo tope** desde la venta (por defecto **35 días**, editable). ## Cómo funciona 1. Tu equipo conversa con un cliente en el inbox. Si la conversación se cierra sin venta, la etiqueta con la **etiqueta de preventa** (por ejemplo "Sin compra"). woku programa la reseña de preventa para el **día siguiente**, dentro del horario configurado (por defecto 9 a 18 h). 2. Si el cliente compra antes de ese envío, el pedido en POS llega con la misma conversación y woku **cancela** la reseña de preventa: el cliente solo recibe el viaje de compra. 3. **Venta**: cuando el pedido se confirma en POS, woku envía la encuesta de satisfacción. 4. **Entrega**: cuando el pedido se marca como Recibido en POS, o Skydropx informa la entrega, woku envía la reseña de entrega. Si no llega ninguna señal dentro del plazo tope, esta etapa se omite. 5. **Posventa**: unos días después de la entrega (o del plazo tope), woku invita a evaluar los **productos** de ese pedido. 6. **Lealtad**: unos días después, woku envía una encuesta **NPS**. Puedes desactivar esta etapa si prefieres gestionar la fidelización desde Pancake. 7. En cada etapa woku invita por **WhatsApp** y, si no hay respuesta, escala a **email**; cuando el cliente responde, los recordatorios de esa etapa se detienen. Si el pedido se **cancela** o se **devuelve**, las etapas pendientes se cancelan. ## Cómo conectar **1. Crea una API key en Pancake POS** En Pancake POS ve a **Ajustes > Avanzado > Conexión de terceros > Webhook/API** y crea una **API key**. Esta clave da acceso completo a tu tienda: guárdala como un secreto. **2. Valida la clave en woku** En **Empresa → Integraciones → Pancake**, pega la API key y presiona **Validar clave**. woku lista las tiendas a las que accede la clave: elige la tuya, el país (por defecto Colombia) y el idioma de las invitaciones, y presiona **Conectar Pancake**. Al conectar, woku también crea el destino de soporte y el grupo de planes de acción de la integración. **3. Configura el webhook de pedidos en POS** Al conectar, woku te muestra **una sola vez** la URL del webhook de POS, el nombre de una cabecera y su valor secreto. En Pancake POS (**Ajustes > Avanzado > Conexión de terceros > Webhook**) pega la URL, activa el tipo **pedidos** y agrega la cabecera con ese valor. Si lo prefieres, marca **Configurar el webhook automáticamente** al conectar y woku lo hace por ti. **4. Conecta tus páginas del inbox (preventa)** Por cada página (WhatsApp, Facebook, Instagram) agrega su **ID** y su **page access token** (Ajustes > Herramientas de la página en el inbox). Luego presiona **Elegir etiquetas de preventa** y marca las etiquetas que tu equipo usa para una conversación cerrada sin venta. **5. Habilita el webhook del inbox** Pide a soporte de Pancake que habilite los webhooks para tu página y pega la **URL del webhook del inbox** que woku te mostró al conectar (o al rotarla) en **Ajustes > Herramientas > Webhook** del inbox. > [!WARNING] > > Los secretos del webhook se muestran **una sola vez**. Si los pierdes, presiona **Rotar** en la > sección Webhooks de la integración: woku genera un secreto nuevo y el anterior deja de funcionar. ## Qué configuras en woku ### Datos de conexión | Configuración | Descripción | | - | - | | Idioma de las invitaciones | `Español` o `English`. Las evaluaciones se crean en ambos idiomas. | | País | Código ISO de dos letras (por defecto `CO`). woku lo usa para normalizar los teléfonos locales de los pedidos al formato internacional de WhatsApp. | | La venta se cuenta desde el estado | Qué estado del pedido en POS dispara la etapa de venta: **Confirmado** (por defecto), Esperando recogida, Enviado o Recibido. | | Días máximo sin entrega | Si no llega la señal de entrega, cuántos días después de la venta se dispara igual la posventa (por defecto **35**). | | Días de espera de la preventa y horario | Cuánto espera woku después de la etiqueta (por defecto **1 día**) y entre qué horas envía (por defecto **9 a 18**, hora local de la tienda). | | Las ventas en mostrador omiten la entrega | Un pedido marcado como retirado en tienda no tiene etapa de entrega. | | Anotar cada respuesta en el cliente del inbox | Lleva la calificación y el comentario de cada etapa como una nota al cliente en el inbox de Pancake. | | Modo prueba | Crea las evaluaciones pero **no envía invitaciones**. | ### El viaje En **Viaje** ves una tarjeta por cada etapa (preventa, venta, entrega, posventa y lealtad). En cada una puedes activarla o desactivarla, ajustar los **días de espera** (y el **horario** en la preventa), elegir el **canal**, editar el **mensaje** en español e inglés y subir una **imagen** en las etapas que la muestran. En la etapa de **entrega**, woku muestra la **fuente de entrega**: la(s) cuenta(s) de **Skydropx** conectadas. Con una sola cuenta, woku la usa directamente; si operas en más de un país (por ejemplo Colombia y México, cada uno con su conexión), eliges ahí cuál(es) alimenta(n) la entrega. La correlación sigue siendo por **referencia** (el número del pedido de POS), y el estado **Recibido** de POS actúa como segunda señal. > [!NOTE] > > La definición del viaje es **tuya**: una vez que guardas tus cambios, woku deja de sobrescribirla > con los valores por defecto. Puedes volver a ajustarla cuando quieras. ## La experiencia del cliente En cada etapa activa woku invita al cliente con esta secuencia: * **Hasta 3 envíos**: el primero al dispararse la etapa, y recordatorios a las **8 horas** y a las **16 horas** si no hay respuesta. * Con el canal **WhatsApp y luego email**, los dos primeros envíos van por **WhatsApp** (si hay teléfono) y el tercero escala a **email**. Con el canal **solo email**, todos van por email. * En cuanto el cliente **responde**, los recordatorios de esa etapa se detienen. * Si a las **24 horas** no hay respuesta, la invitación de esa etapa expira. ### La etapa de posventa (productos) La posventa evalúa los **productos de ese pedido**: un producto crea una reseña; varios se agrupan en un **Flow**. Cada instrumento se etiqueta con el pedido, la tienda, la conversación y el producto, para que puedas filtrar y agrupar por cualquiera de esos ejes. ## Qué datos usa woku * **Del pedido en POS**: identificador, estado, teléfono y email de facturación o de envío, productos (nombre e imagen), conversación de origen y vendedor asignado. Quedan como trackers consultables en woku: `pancake_order_id`, `pancake_shop_id`, `pancake_conversation_id`, `pancake_page_id`, `pancake_product_id` y `pancake_seller_id`. * **De la conversación del inbox**: las etiquetas, la versión de la conversación y, al disparar la preventa, el teléfono y el email del cliente leídos por API con el token de la página. > [!WARNING] > > El conector requiere que el pedido o la conversación tengan **al menos un dato de contacto**. Sin > teléfono ni email, la evaluación se crea igualmente en woku pero no se envía ninguna invitación. ## Organización en carpetas ``` 📁 Mi Tienda (carpeta de la tienda) ├── 📁 Preventa (reseñas de la atención por chat) ├── 📁 Entrega (reseñas de entrega) └── 📁 Posventa (reseñas de producto por pedido) ``` ## Tickets de soporte y planes de acción Al conectar Pancake, woku también deja configurado qué pasa con lo que responden tus clientes. Crea **una sola vez** dos recursos llamados **Integración Pancake (nombre de tu tienda)**: | Recurso | Qué hace | | - | - | | **Destino de soporte** (tipo email) | Recibe los [tickets a SAC](/docs/guides/support-tickets) que woku crea cuando una respuesta negativa de cualquier etapa del viaje amerita atención. Los tickets llegan al email de la persona que conectó Pancake. | | **Grupo de planes de acción** | Escucha el feedback de todas las etapas y, cuando acumula **100 oportunidades de mejora** nuevas, genera un [borrador de plan de acción](/docs/action-plans/create-plan). La persona que conectó Pancake queda como **Administrador** del grupo. | Los dos escuchan todo lo que crea la integración con condiciones **es cualquier valor** sobre los trackers `pancake_order_id` y `pancake_conversation_id`, unidas con **O si**. Así cubren también las conversaciones y los pedidos que lleguen después. > [!NOTE] > > El destino y el grupo son **tuyos**: puedes editarlos (sumar correos o encargados, cambiar el > umbral), desactivarlos o eliminarlos desde **Soporte** y **Planes de acción**. woku no los vuelve a > crear ni los modifica, aunque desconectes y reconectes Pancake. ## Preguntas frecuentes > **¿Cuándo se cuenta un pedido como venta?** > > Por defecto, cuando pasa a **Confirmado** en POS. Puedes exigir un estado posterior (por > ejemplo **Enviado**) desde la configuración. Los pedidos en **Nuevo** o **Pendiente de > confirmación** no disparan nada. > **¿Qué pasa si mi equipo no marca los pedidos como Recibidos?** > > Conecta **Skydropx** para que la entrega llegue por el webhook de la paquetería, o confía en > el plazo tope: pasado ese plazo desde la venta, la posventa se envía igual. > **¿Cómo se correlaciona la entrega de Skydropx con el pedido?** > > Skydropx se conecta una sola vez desde **Empresa → Integraciones → Skydropx**, con su propia > tarjeta. En la etapa de **entrega** de Pancake eliges cuál(es) de tus cuentas de Skydropx > alimenta(n) la entrega; woku no crea ni modifica nada en tu cuenta de Skydropx. Cuando crees tus > órdenes en Skydropx, usa como **referencia** el número del pedido de POS. Al entregar el paquete, > Skydropx avisa a woku por webhook y woku correlaciona esa entrega con tu pedido por esa > referencia. woku solo escucha la entrega. > **¿Se puede duplicar una invitación por el mismo pedido?** > > No. woku controla que cada etapa del viaje se dispare **una sola vez** por pedido o > conversación, aunque Pancake reintente su notificación. Además, como respaldo, woku revisa > los pedidos actualizados cada cinco minutos por si un webhook no llegó. > **¿Cómo pruebo la integración sin contactar clientes?** > > Activa el **Modo prueba**: los pedidos y conversaciones siguen generando sus evaluaciones en > woku, pero no se envía ninguna invitación. La sección **Estado** muestra el último webhook de > POS, la última revisión y el último error, si lo hubo. > **¿Cómo desconecto Pancake?** > > En **Empresa → Integraciones → Pancake → Desconectar**. Se eliminan la conexión y sus > credenciales; los wokus, las respuestas, el destino de soporte y el grupo de planes de acción ya > creados **se conservan**. Recuerda quitar la URL > del webhook en Pancake. # Conector Shopify Source: https://woku.app/docs/integrations/shopify Conecta tu tienda Shopify con woku y acompaña a cada comprador con un viaje de 4 etapas post-compra (compra, entrega, posventa y lealtad), sin escribir código El **conector Shopify de woku** convierte cada pedido pagado de tu tienda en un **viaje post-compra** de hasta cuatro etapas: la **compra**, la **entrega**, la **posventa** de los productos y la **lealtad**. Tú decides qué etapas se activan, cuándo se envía cada una, por qué canal y con qué mensaje. woku invita al comprador por **WhatsApp o email**, gestiona los recordatorios y organiza todo en carpetas por tienda. No modifica tu storefront ni tu checkout: solo lee los pedidos y el catálogo para crear las evaluaciones. ## Las 4 etapas del viaje | Etapa | Qué mide | Cuándo se dispara | | - | - | - | | **Compra** | Satisfacción con la compra (encuesta CSAT) | Al marcarse el pedido como **pagado** | | **Entrega** | Experiencia de entrega (reseña woku) | Al **entregarse** el pedido (evento de entrega) | | **Posventa** | Evaluación de los **productos** del pedido (reseña woku o Flow) | Unos días **después de la entrega** | | **Lealtad** | Recomendación (encuesta NPS) | Unos días **después del envío de la posventa** | Cada etapa es independiente: la activas o desactivas, ajustas su timing, su canal y su mensaje desde la configuración en woku. Las respuestas llegan como cualquier otra reseña o encuesta: alimentan tus métricas y reportes, además de los **tickets de soporte** y los **planes de acción** que la integración deja configurados (ver "Tickets de soporte y planes de acción" más abajo). > [!NOTE] > > La etapa de **entrega** necesita una señal de entrega. Hoy esa señal llega desde el conector de > paquetería **Skydropx**. Skydropx se conecta desde **Empresa → Integraciones → Skydropx** (una > cuenta por país) y woku correlaciona cada entrega con el pedido de Shopify automáticamente. Si tu > tienda no tiene una fuente de entrega conectada, la etapa de entrega no se dispara y la > **posventa** corre igual usando un **plazo tope** desde la compra (ver "Días tope sin entrega" > más abajo). ## Cómo funciona 1. El comprador paga un pedido en tu tienda. Shopify notifica a woku que el pedido quedó **pagado** y arranca el viaje. 2. **Compra**: woku envía una encuesta de satisfacción (CSAT) sobre la compra. 3. **Entrega**: cuando el pedido se entrega, woku envía una reseña sobre la experiencia de entrega. Si no llega la señal de entrega dentro del plazo tope, esta etapa se omite. 4. **Posventa**: unos días después de la entrega (o del plazo tope), woku invita a evaluar los **productos** de ese pedido. 5. **Lealtad**: unos días después de haber enviado la posventa, woku envía una encuesta **NPS**. 6. En cada etapa woku invita por **WhatsApp** y, si no hay respuesta, escala a **email**; cuando el comprador responde, los recordatorios de esa etapa se detienen. ## Cómo conectar tu tienda > [!NOTE] > > El conector no está publicado en el Shopify App Store: no se instala buscándolo ahí. La única > forma de conectarlo es desde woku, como se describe abajo. **1. Inicia la conexión desde woku** En **Empresa → Integraciones → Shopify**, ingresa el dominio de tu tienda (por ejemplo `mitienda.myshopify.com`) y presiona **Continuar a Shopify**. **2. Autoriza en Shopify** Shopify te muestra la pantalla de autorización con los permisos que usa el conector: lectura de pedidos, de productos y de clientes. Al autorizar, te redirige de vuelta a [admin.woku.app](https://admin.woku.app). **3. Conecta la tienda a tu empresa** woku detecta la instalación pendiente y te muestra el aviso **Tienda de Shopify detectada** con el dominio de tu tienda. Presiona **Conectar** para vincularla. En ese momento woku registra la suscripción a los pedidos pagados, crea el destino de soporte y el grupo de planes de acción de la integración, y la integración queda activa. ## Qué configuras en woku Una vez conectada la tienda, en **Empresa → Integraciones → Shopify** ajustas dos cosas: los **datos de conexión** (comunes a todo el viaje) y el **viaje post-compra** (etapa por etapa). ### Datos de conexión | Configuración | Descripción | | - | - | | Idioma de las invitaciones | `Español` o `English`. Las evaluaciones se crean en ambos idiomas y este es el idioma por defecto de los envíos. | | Modo prueba | Crea las evaluaciones de cada pedido pero **no envía invitaciones**. Útil para validar la integración antes de contactar clientes reales. | | Agrupar wokus por | Cómo se organizan las evaluaciones de producto en carpetas: por **colección** o por **tipo de producto**. | ### El viaje post-compra En **Viaje post-compra** ves una tarjeta por cada etapa (compra, entrega, posventa y lealtad). En cada una puedes: * **Activar o desactivar** la etapa. * Ajustar el **timing**: los **días de espera** de la etapa (por ejemplo, cuántos días después de la entrega se envía la posventa). * Elegir el **canal**: **WhatsApp y luego email**, o **solo email**. * Editar el **mensaje** de la invitación en **español e inglés**. Si lo dejas vacío, woku usa un texto por defecto. * Subir una **imagen** propia para la etapa de **entrega**. Es opcional: si no subes ninguna, woku usa el logo de tu empresa, y puedes quitar la que subiste para volver al logo. La **posventa** no lleva imagen propia: usa la imagen de cada producto. Además, la etapa de **entrega** tiene un ajuste propio: | Configuración | Descripción | | - | - | | Días tope sin entrega | Si no llega la señal de entrega, cuántos días después de la compra se dispara igual la posventa (0 a 90, por defecto **20**). Evita que un pedido sin aviso de entrega deje el viaje a medias. | En esa misma etapa de **entrega**, woku muestra la **fuente de entrega**: la(s) cuenta(s) de **Skydropx** conectadas. Con una sola cuenta, woku la usa directamente; si operas en más de un país (por ejemplo Colombia y México, cada uno con su conexión), eliges ahí cuál(es) alimenta(n) la entrega de esta tienda. En Shopify la correlación es **automática**: la app Skydropx-Shopify identifica el pedido, así que no configuras nada más. > [!NOTE] > > La definición del viaje es **tuya**: una vez que guardas tus cambios, woku deja de sobrescribirla > con los valores por defecto. Puedes volver a ajustarla cuando quieras. ## La experiencia del comprador > [!NOTE] > > Si el pedido trae teléfono, antes de enviar la invitación woku registra al comprador como > **cliente** de tu empresa (y, si el pedido también trae email, vincula el teléfono al cliente de > ese email). Así, cuando el comprador responde por WhatsApp, woku lo reconoce de inmediato sin > pedirle su email, y sus respuestas quedan asociadas a su historial como cliente. ### Cadencia de cada etapa En cada etapa activa woku invita al comprador con esta secuencia: * **Hasta 3 envíos**: el primero al dispararse la etapa, y recordatorios a las **8 horas** y a las **16 horas** si no hay respuesta. * Con el canal **WhatsApp y luego email**, los dos primeros envíos van por **WhatsApp** (si hay teléfono) y el tercero escala a **email**. Con el canal **solo email**, todos van por email. * Si el pedido **no tiene teléfono**, todos los envíos van por email. Si un envío por WhatsApp no puede salir, woku usa el email como respaldo en ese intento. * En cuanto el comprador **responde**, los recordatorios de esa etapa se detienen. * Si a las **24 horas** no hay respuesta, la invitación de esa etapa expira y no se insiste más. > [!NOTE] > > woku envía **una invitación a la vez por comprador** dentro de cada etapa. Si un mismo cliente > tiene varios pedidos en curso, las invitaciones se encolan y se envían de forma secuencial, en > lugar de llegarle todas juntas. ### La etapa de posventa (productos) La posventa evalúa los **productos de ese pedido**: * Si el pedido tiene **un solo producto**, woku crea una reseña de ese producto. * Si tiene **más de un producto distinto**, woku agrupa las evaluaciones en un **Flow** (una sola invitación que recorre todos los productos), enviado por email. * El instrumento se etiqueta con el pedido, la tienda y el producto, para que puedas filtrar y agrupar por cualquiera de esos ejes. ## Qué datos del pedido usa woku Para crear y enviar las evaluaciones, woku consulta el pedido en Shopify y usa: * **Identificación del pedido**: número e identificador, para vincular cada evaluación con su pedido (quedan como trackers consultables en woku: `shopify_order_id`, `shopify_shop_domain` y `shopify_product_id`). * **Contacto del comprador**: el email y el teléfono asociados al pedido y a sus direcciones. Si el pedido no trae un contacto directo, woku usa el del perfil del comprador en la tienda, de ahí el permiso de lectura de clientes. El teléfono se normaliza a formato internacional para WhatsApp. * **Productos comprados**: nombre, imagen (la de la variante comprada o, en su defecto, la imagen destacada del producto), colección y tipo de producto, para crear las evaluaciones de producto y organizarlas en carpetas. * **Zona horaria de la tienda**, para respetar la ventana de envío de las etapas programadas. > [!WARNING] > > El conector requiere que el pedido tenga **al menos un dato de contacto**. Si el pedido no tiene > teléfono ni email, la evaluación se crea igualmente en woku pero no se envía ninguna invitación. ## Organización en carpetas woku crea automáticamente esta estructura en tu empresa: ``` 📁 Mi Tienda (carpeta de la tienda) ├── 📁 Experiencia de Compra (evaluaciones de compra y entrega) ├── 📁 Colección A (evaluaciones de producto, según agrupación) ├── 📁 Colección B └── 📁 Otros productos (productos sin colección ni tipo) ``` La carpeta raíz toma el nombre de tu tienda. Las subcarpetas de productos siguen la estrategia configurada (**colección** o **tipo de producto**); si un producto no tiene ninguna de las dos, va a **Otros productos**. Las carpetas se reutilizan entre pedidos: no se duplican. ## Tickets de soporte y planes de acción Al conectar la tienda, woku también deja configurado qué pasa con lo que responden tus compradores. Crea **una sola vez** dos recursos llamados **Integración Shopify (nombre de tu tienda)**: | Recurso | Qué hace | | - | - | | **Destino de soporte** (tipo email) | Recibe los [tickets a SAC](/docs/guides/support-tickets) que woku crea cuando una respuesta negativa de cualquier etapa del viaje amerita atención. Los tickets llegan al email de la persona que conectó la tienda. | | **Grupo de planes de acción** | Escucha el feedback de todas las etapas y, cuando acumula **100 oportunidades de mejora** nuevas, genera un [borrador de plan de acción](/docs/action-plans/create-plan). La persona que conectó la tienda queda como **Administrador** del grupo. | Los dos escuchan todo lo que crea la integración con condiciones **es cualquier valor** sobre los trackers `shopify_order_id` y `shopify_product_id`, unidas con **O si**. Así cubren también las evaluaciones de los pedidos que lleguen después. > [!NOTE] > > El destino y el grupo son **tuyos**: puedes editarlos (sumar correos o encargados, cambiar el > umbral), desactivarlos o eliminarlos desde **Soporte** y **Planes de acción**. woku no los vuelve a > crear ni los modifica, aunque desconectes y reconectes la tienda. ## Preguntas frecuentes > **¿Qué pasa si no tengo una fuente de entrega conectada?** > > La etapa de **entrega** no se dispara, pero el viaje no se detiene: la **posventa** se envía > igual pasado el plazo **Días tope sin entrega** (por defecto 20 días desde la compra). Cuando > conectes una fuente de entrega, la posventa pasará a contarse desde la entrega real. > **¿Cómo desconecto mi tienda?** > > Tienes dos caminos y ambos eliminan la conexión y sus credenciales: > > * En woku: **Empresa → Integraciones → Shopify → Desconectar**. > * En Shopify: desinstala la app desde el admin de tu tienda. Shopify notifica a woku y la > conexión se elimina automáticamente. > > En ambos casos, los wokus, las respuestas, el destino de soporte y el grupo de planes de acción > ya creados **se conservan** en tu cuenta. > **¿Puedo reconectar mi tienda después de desconectarla?** > > Sí. Repite el flujo de conexión desde **Empresa → Integraciones → Shopify** ingresando el > dominio de tu tienda. Las carpetas y los wokus existentes se reutilizan: los nuevos pedidos se > suman donde estaban. > **¿Qué pasa con los pedidos sin teléfono?** > > Todos los envíos de ese pedido van por **email**, incluidos los recordatorios. WhatsApp solo > se usa cuando el pedido tiene un teléfono utilizable. > **¿Se puede duplicar una invitación por el mismo pedido?** > > No. woku controla que cada etapa del viaje se dispare **una sola vez** por pedido, aunque > Shopify o la fuente de entrega reintenten su notificación. > **¿Cómo pruebo la integración sin contactar clientes?** > > Activa el **Modo prueba** en la configuración: los pedidos siguen generando sus evaluaciones > en woku, pero no se envía ninguna invitación. También puedes revisar la sección **Estado** de > la integración, que muestra la última notificación recibida desde Shopify y el último error, > si lo hubo. > **¿En qué idioma le llega la invitación al comprador?** > > En el idioma configurado en la integración (español o inglés). Las evaluaciones se crean con > contenido en ambos idiomas, así el comprador puede cambiar de idioma al responder. # Webhooks Source: https://woku.app/docs/integrations/webhooks Recibe eventos de woku en tu sistema en tiempo real, con firma HMAC para verificar la autenticidad y reintentos automáticos Los **webhooks** te permiten recibir notificaciones HTTP en tu propio servidor cada vez que ocurre un evento relevante en woku: una nueva reseña **woku**, una respuesta **NPS** o la respuesta de un **formulario**. woku hace un `POST` con un cuerpo JSON a la URL que configures. ## Configuración Los webhooks se administran desde la aplicación administrativa, no por API pública. **1. Abre la configuración de integraciones** En el panel, entra a **Empresa → Integraciones → Webhooks**. **2. Crea un webhook** Presiona **Nuevo webhook** e ingresa un **nombre**, la **URL** de tu endpoint y los **eventos** a los que te suscribes. Opcionalmente puedes agregar **headers personalizados** (por ejemplo, un token propio) y activar o desactivar el webhook en cualquier momento. **3. Guarda el secret** Al crear el webhook, woku muestra el **secret** una sola vez. Cópialo y guárdalo de forma segura: lo necesitarás para verificar la firma de cada evento. > [!WARNING] > > El secret se muestra **una única vez** al crear o rotar el webhook. woku > lo guarda cifrado y no puede volver a mostrártelo. Si lo pierdes, rótalo > desde el panel para generar uno nuevo. ## Eventos disponibles woku emite estos eventos: | Evento | Cuándo se emite | | - | - | | `qualification.created` | Se registró una nueva reseña woku (calificación 1-5). | | `nps_submission.created` | Se registró una nueva respuesta NPS (puntaje 0-10). | | `form_submission.created` | Se completó una respuesta de formulario. | ### Estructura común Todos los payloads comparten esta envoltura: | Campo | Descripción | | - | - | | `event` | Nombre del evento (ver tabla anterior). | | `timestamp` | Fecha y hora de emisión (ISO 8601, UTC). | | `companyId` | Empresa a la que pertenece el evento. | | `data` | Datos específicos del evento. | ### Ejemplos de payload > [!NOTE] > > Los payloads no incluyen datos de contacto del cliente. ```json qualification.created theme={null} { "event": "qualification.created", "timestamp": "2026-05-26T15:30:00Z", "companyId": "64a1b2c3d4e5f6a7b8c9d0e1", "data": { "clientId": "64f1a2b3c4d5e6f7a8b9c0d1", "wokuId": "64d4e5f6a7b8c9d0e1f2a3b4", "qualification": 5, "responseChannel": "review-app" } } ``` ```json nps_submission.created theme={null} { "event": "nps_submission.created", "timestamp": "2026-05-26T15:30:00Z", "companyId": "64a1b2c3d4e5f6a7b8c9d0e1", "data": { "npsId": "64b2c3d4e5f6a7b8c9d0e1f2", "npsToolId": "64c3d4e5f6a7b8c9d0e1f2a3", "responseChannel": "whatsapp" } } ``` ```json form_submission.created theme={null} { "event": "form_submission.created", "timestamp": "2026-05-26T15:30:00Z", "companyId": "64a1b2c3d4e5f6a7b8c9d0e1", "data": { "formResponseId": "64b2c3d4e5f6a7b8c9d0e1f2", "formId": "64c3d4e5f6a7b8c9d0e1f2a3", "responseChannel": "api" } } ``` ## Verificación de firma (HMAC) Cada entrega incluye el header `X-Woku-Signature` con una firma **HMAC-SHA256** del cuerpo JSON crudo, usando tu secret como llave: ``` X-Woku-Signature: sha256= ``` Además de la firma, cada entrega lleva dos headers informativos: | Header | Contenido | | - | - | | `X-Woku-Event` | Nombre del evento entregado (por ejemplo `nps_submission.created`). | | `X-Woku-Delivery` | Identificador único de la entrega, útil para descartar duplicados. | > [!WARNING] > > Calcula la firma sobre el **cuerpo crudo** de la solicitud (los bytes > exactos recibidos), **antes** de parsearlo como JSON. Re-serializar el > objeto puede cambiar el orden de las llaves o el espaciado y producir una > firma distinta. Compara siempre con una función de **tiempo constante** para evitar ataques de temporización. Si la firma no coincide, descarta la solicitud. ```js Node.js theme={null} import crypto from 'node:crypto'; function verifyWokuSignature(rawBody, signatureHeader, secret) { // signatureHeader: "sha256=" const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex'); const a = Buffer.from(signatureHeader); const b = Buffer.from(expected); return a.length === b.length && crypto.timingSafeEqual(a, b); } // Ejemplo con Express. Usa el cuerpo crudo, no el JSON parseado. import express from 'express'; const app = express(); app.post( '/webhooks/woku', express.raw({ type: 'application/json' }), (req, res) => { const signature = req.header('X-Woku-Signature') ?? ''; if (!verifyWokuSignature(req.body, signature, process.env.WOKU_WEBHOOK_SECRET)) { return res.status(401).send('Invalid signature'); } const event = JSON.parse(req.body.toString('utf8')); // ... procesa el evento res.status(200).json({ received: true }); }, ); ``` ```python Python theme={null} import hashlib import hmac def verify_woku_signature(raw_body: bytes, signature_header: str, secret: str) -> bool: # signature_header: "sha256=" expected = "sha256=" + hmac.new( secret.encode("utf-8"), raw_body, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, signature_header) # Ejemplo con Flask. request.data es el cuerpo crudo. from flask import Flask, request, abort, jsonify import os app = Flask(__name__) @app.post("/webhooks/woku") def woku_webhook(): signature = request.headers.get("X-Woku-Signature", "") if not verify_woku_signature(request.data, signature, os.environ["WOKU_WEBHOOK_SECRET"]): abort(401) event = request.get_json() # ... procesa el evento return jsonify(received=True), 200 ``` ```php PHP theme={null} " $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret); return hash_equals($expected, $signatureHeader); } $rawBody = file_get_contents('php://input'); $signature = $_SERVER['HTTP_X_WOKU_SIGNATURE'] ?? ''; $secret = getenv('WOKU_WEBHOOK_SECRET'); if (!verify_woku_signature($rawBody, $signature, $secret)) { http_response_code(401); echo 'Invalid signature'; exit; } $event = json_decode($rawBody, true); // ... procesa el evento http_response_code(200); header('Content-Type: application/json'); echo json_encode(['received' => true]); ``` ## Respuesta esperada de tu endpoint Tu endpoint debe responder con un código **HTTP 2xx** (idealmente `200`) lo antes posible. woku considera exitosa la entrega ante cualquier 2xx. > [!TIP] > > Procesa el evento de forma **asíncrona**: responde `200` de inmediato y > encola el trabajo pesado. woku usa un timeout de **15 segundos** por > intento; si tu endpoint tarda más, la entrega se cuenta como fallida. ## Reintentos y dead-letter Si tu endpoint no responde con 2xx (o no responde dentro del timeout), woku **reintenta con backoff exponencial**: | Intento | Espera antes del intento | | - | - | | 1 | inmediato | | 2 | \~1 s | | 3 | \~2 s | Tras agotar los **3 intentos**, la entrega pasa a estado **dead-letter** y no se vuelve a intentar. En el detalle del webhook, en **Empresa → Integraciones → Webhooks**, puedes revisar el **historial de entregas** con filtro por estado (Exitoso, Fallido, Pendiente, Dead-letter). Desde ahí también puedes editar el webhook, rotar su clave o eliminarlo. > [!NOTE] > > Como un evento puede entregarse más de una vez (por un reintento sobre una > entrega que sí llegó pero respondió tarde), diseña tu endpoint para que > sea **idempotente**: usa el header `X-Woku-Delivery` o el identificador > del recurso en `data` para descartar duplicados. ## Tickets a SAC Los tickets de soporte generados por la IA de woku no se entregan por webhook: se envían a tu plataforma de soporte mediante **destinos directos** configurados en el módulo Soporte. Consulta la guía de [tickets a SAC](/docs/guides/support-tickets). # Conector Zendesk Source: https://woku.app/docs/integrations/zendesk Conecta tu cuenta de Zendesk con woku mediante un API token y envía tickets a tu equipo de soporte cuando una opinión lo amerita El **conector Zendesk de woku** vincula tu cuenta de Zendesk con tu empresa en woku usando un **API token**. Su propósito es alimentar los **tickets a SAC** del módulo Soporte: cuando el motor detecta una opinión negativa que amerita seguimiento, woku crea un ticket directamente en tu Zendesk, con el contexto del cliente y de la respuesta que lo originó. > [!NOTE] > > La conexión se crea una sola vez y queda disponible para todos los > destinos de tickets de tipo Zendesk de tu empresa. Los destinos no > guardan credenciales propias: siempre referencian la conexión. ## Antes de empezar: obtén el API token en Zendesk **1. Abre la configuración de API** En Zendesk, entra al **Admin Center** y navega a **Aplicaciones e integraciones → API**. **2. Habilita el acceso por token** Activa la opción de **acceso por token** (Token access). Si esta opción está deshabilitada en tu cuenta, woku no podrá validar la credencial y la conexión fallará. **3. Crea un API token** Genera un nuevo API token y cópialo. Zendesk lo muestra una sola vez, así que guárdalo hasta terminar la conexión en woku. > [!TIP] > > Usa el email de un **agente o administrador real** de tu Zendesk. Los > tickets que woku crea quedan a nombre de ese usuario, por lo que > conviene que sea una cuenta activa del equipo de soporte. ## Crear la conexión en woku En **Empresa → Integraciones**, ubica la tarjeta **Zendesk** y completa tres datos: | Campo | Descripción | | - | - | | Subdominio | El subdominio de tu cuenta. Acepta `acme`, `acme.zendesk.com` o la URL completa; woku lo normaliza automáticamente. | | Email del agente | El correo del agente o administrador dueño del token. | | API token | El token generado en el Admin Center, de mínimo 8 caracteres. | Antes de guardar, woku **valida la credencial en vivo** contra la API de Zendesk (consulta tu propio usuario en `/api/v2/users/me.json` con autenticación básica de email y token). Si el token es inválido, o tu cuenta tiene deshabilitado el acceso por token, la creación falla y woku te muestra el motivo. > [!NOTE] > > Una empresa puede tener **varias conexiones Zendesk, una por > subdominio** (los duplicados se rechazan). Es útil si operas instancias > separadas por país o por unidad de negocio. ## Seguridad y ciclo de vida de la conexión * El token se guarda **cifrado** y es de **solo escritura**: la interfaz nunca lo vuelve a mostrar, solo una pista enmascarada. * Para **rotar el token**, edita la conexión e ingresa el nuevo valor. woku lo verifica en vivo contra Zendesk antes de persistirlo; si no es válido, la conexión conserva el token anterior. * El botón **Probar** re-verifica la conexión en cualquier momento y registra su salud. Si Zendesk responde con un error de autenticación, la conexión queda marcada como **requiere re-autenticación**. * Cada conexión muestra su estado: **conectada**, **requiere re-autenticación** o **error**. Además puedes **habilitarla o deshabilitarla** sin perder la configuración, o **eliminarla** por completo. ## Qué hace woku con la conexión La conexión alimenta los **destinos de tickets a SAC** del módulo Soporte. Un destino de tipo Zendesk referencia la conexión y, opcionalmente, un **Group ID**: el grupo de agentes de Zendesk que recibirá los tickets de ese destino. Cuando el motor escala una opinión negativa, woku crea el ticket en tu Zendesk (`/api/v2/tickets.json`) con: * **Asunto** y **descripción en HTML** con el resumen del caso. * **Solicitante**: el nombre y el email del cliente afectado, para que el ticket quede asociado a la persona correcta. * **Prioridad** mapeada según la severidad del caso: `urgent`, `high`, `normal` o `low`. * **Etiquetas**: `woku`, `voc`, la herramienta de origen (woku, NPS, CSAT o CES) y el nivel de riesgo de fuga del cliente. * **Grupo**: el Group ID del destino, si lo configuraste. El enlace al ticket creado queda guardado en woku. Desde el detalle del ticket puedes abrirlo en Zendesk con **Ver en el SAC**. ## Preguntas frecuentes > **¿Qué permisos necesita el token?** > > El token hereda los permisos del agente cuyo email configuraste. Para > crear tickets basta un agente estándar; usa un administrador si tu > cuenta restringe la creación de tickets por API. > **¿Qué pasa si roto o revoco el token en Zendesk?** > > La conexión dejará de autenticar y, en la siguiente verificación, > quedará marcada como **requiere re-autenticación**. Edita la conexión > e ingresa el token nuevo; woku lo valida en vivo antes de guardarlo. > **¿Puedo conectar más de una cuenta de Zendesk?** > > Sí. Puedes crear varias conexiones, siempre que cada una apunte a un > **subdominio distinto**. Luego cada destino de tickets elige qué > conexión usar. > **¿Qué pasa con los tickets si elimino la conexión?** > > Los tickets ya creados **permanecen en tu Zendesk**: woku solo > elimina la conexión y sus credenciales. Los destinos que dependían de > ella dejan de poder enviar hasta que los apuntes a otra conexión. ## Siguiente paso > **[Tickets a SAC](/docs/guides/support-tickets)** > > Conoce el motor de escalamiento: cómo se detectan las opiniones que > ameritan un ticket, cómo se rutean a cada destino y cómo se hace el > seguimiento desde woku. # Estudio de datos (agente de IA) Source: https://woku.app/docs/reports/data-studio Describe lo que necesitas en lenguaje natural y un agente de IA construye un informe de insights con números verificados, versionado y publicable > [!NOTE] > > Estudio de datos está disponible solo en Corporate. > [!NOTE] > > **Disponible en el plan Corporate.** Esta funcionalidad forma parte de las capacidades empresariales de woku. [Conversa con nuestro equipo comercial](https://woku.app/pricing). El **Estudio de datos** (Data Studio) es el módulo de analítica conversacional de woku. En lugar de configurar un reporte campo por campo, describes lo que necesitas en lenguaje natural y un agente de IA construye un **informe de insights** sobre los datos reales de tu empresa: KPIs, hallazgos con evidencia, visualizaciones y acciones recomendadas, listo para revisar y publicar. ## Cómo se usa 1. Abres una conversación y describes el informe que quieres. 2. El agente propone un **plan** (qué datos usará y qué mostrará) y espera tu aprobación. 3. Al aprobarlo, consulta los datos en el servidor, los analiza, **verifica cada número** contra los datasets y construye el informe. 4. Puedes pedir **cambios en lenguaje natural** (incluido cambiar el periodo analizado), volver a una **versión anterior** o calcular **métricas avanzadas** como predicciones. 5. El informe queda versionado; puedes **publicarlo** con un enlace público o protegido por clave. Durante todo el proceso la conversación recibe eventos en vivo (el agente "pensando", el plan, los datos extraídos, la revisión visual y el informe listo). ## Cómo trabaja el agente El agente es un **orquestador** conversacional que propone un plan, espera tu aprobación y luego ejecuta un pipeline determinista: consulta los datos en el servidor, los analiza, verifica la evidencia, renderiza el informe y lo revisa visualmente antes de entregarlo. ```mermaid theme={null} flowchart TD U([Usuario]) <-->|conversación en vivo| AG{{"Agente orquestador"}} AG --> P["1 · Proponer el plan"] P --> OK{"¿Apruebas el plan?"} OK -->|sí| D["2 · Consultar los datos
siempre del lado del servidor"] D -. catálogo de consultas .-> DATOS[("Datos de woku")] D --> A["3 · Analizar
KPIs, hallazgos, acciones"] A --> V["4 · Verificar la evidencia
cada número contra los datasets"] V --> R["5 · Renderizar el HTML
autocontenido, SVG del servidor"] R --> REV{"Revisión visual
¿aprueba?"} REV -->|no · reparar| A REV -->|sí| LISTO([Informe versionado y publicable]) ``` ### Las cinco herramientas | Herramienta | Qué hace | | - | - | | **generate\_plan** | Arma el plan del informe a partir del catálogo completo de consultas disponibles y lo propone al usuario. No ejecuta nada hasta que lo apruebes. | | **create\_insight\_report** | Ejecuta el pipeline determinista que construye el informe aprobado (ver la sección siguiente). | | **revise\_dashboard** | Aplica cambios pedidos en lenguaje natural sobre el informe existente, incluido cambiar el periodo analizado (por ejemplo "excluye enero" o "solo el último trimestre"). | | **set\_dashboard\_version** | Vuelve a una versión anterior del informe. | | **compute\_advanced\_metric** | Calcula métricas avanzadas, por ejemplo predicciones, usando el intérprete de código de OpenAI. Solo se ejecuta con tu **consentimiento explícito** para enviar datos agregados. | ### El pipeline del informe `create_insight_report` no es un agente libre, sino un **pipeline determinista**: 1. **Datos del servidor**: los datasets se consultan siempre del lado del servidor a través del catálogo de consultas; el modelo nunca toca la base de datos. 2. **Análisis**: el analista produce un informe estructurado con KPIs, hallazgos respaldados por evidencia, visualizaciones y acciones recomendadas. 3. **Verificación de evidencia**: cada afirmación numérica se verifica contra los datasets, con un reintento correctivo. Los hallazgos que no pasan la verificación se descartan: un informe nunca publica números sin verificar. 4. **Render determinista**: el HTML se genera autocontenido, con SVG renderizado en el servidor y sin dependencias de CDNs. 5. **Ver y reparar**: un modelo multimodal revisa el resultado renderizado antes de entregarlo, con un máximo de 2 rondas de reparación. 6. **Persistencia**: el informe queda guardado como una nueva versión de la app. ### Acceso a los datos (multi-tenant) El agente nunca consulta la base directo: trabaja sobre un **catálogo de consultas** del servidor. El `companyId` **siempre** se inyecta desde el contexto de autenticación y nunca desde lo que diga el modelo, garantizando el aislamiento entre empresas. El catálogo cubre KPIs globales, métricas por woku y por carpeta, tendencias de calificación, clientes y segmentos, NPS y sus herramientas, formularios y canales de respuesta. También incluye el **sentimiento del texto**: la distribución y el sentimiento neto por tipo de herramienta (`get_sentiment_summary`), y el sentimiento de cada comentario en las vistas de reseñas, para cruzarlo con calificaciones, clientes o períodos. Ver [Accionabilidad y sentimiento](/docs/core-concepts/actionability-and-sentiment). ## Eventos en streaming (SSE) El endpoint del agente responde como `text/event-stream`. Estos son los eventos que emite: | Evento | Significado | | - | - | | `thinking` | Razonamiento o progreso del agente. | | `plan_proposed` | Plan listo para revisión del usuario. | | `data_extracted` | Dataset consultado (clave, filas). | | `analysis_complete` | Análisis terminado (clave, tipo). | | `visual_review` | Resultado de la revisión visual (aprobado, puntaje). | | `screenshot` | Captura generada del informe. | | `app_ready` | Informe construido (id, versión, URL). | | `title` | Título de la conversación, generado automáticamente. | | `message` | Respuesta final del asistente. | | `error` | Resumen de error. | | `done` | Fin del stream. | ## Persistencia y publicación * **Conversación**: historial de mensajes, plan capturado y herramientas ejecutadas. * **App**: metadatos y **versiones inmutables**, cada una conserva su propio HTML. Revisar o volver a una versión anterior nunca altera las demás. * **Publicación**: cada app puede publicarse y despublicarse; el enlace usa un slug y el acceso puede ser **público** o **protegido por clave**, con verificación de la clave al abrirlo. ## Límites por conversación Para controlar costo y abuso, cada conversación tiene topes: | Límite | Valor | | - | - | | Mensajes | 20 | | Versiones construidas | 5 | | Enfriamiento entre mensajes | 1 s | | Presupuesto | 5 USD | ## Modelos * **claude-sonnet-5**, la conversación del orquestador y el análisis del informe. * **o4-mini**, solo la revisión visual multimodal. * **gpt-5.5**, respaldo del plan y del análisis ante una sobrecarga transitoria. # Espacio de reseñas Source: https://woku.app/docs/reports/reviews-space Explora tus reseñas en un universo 3D donde la cercanía significa similitud: los comentarios que hablan de lo mismo se agrupan en temas El **Espacio de reseñas** es un universo 3D donde cada punto es una reseña con comentario. La posición de cada punto se calcula por **similitud semántica**: las reseñas que hablan de lo mismo quedan cerca entre sí y, al acumularse, forman **temas** que puedes explorar. Lo encuentras en el grupo **Análisis** del panel, junto a Estadísticas, Estudio de datos y Reportes. A diferencia de un gráfico tradicional, el espacio no parte de categorías predefinidas: los temas emergen de lo que tus clientes escriben. Sirve para responder preguntas como "¿de qué están hablando mis clientes?" o "¿este problema es nuevo o viene creciendo?". ## Cuándo se puebla El espacio se construye solo, sin configuración: * La **proyección 3D** aparece apenas existen algunas reseñas con comentario (bastan unas pocas). * Los **temas** requieren volumen: alrededor de **300 reseñas con comentario** elegibles. Con menos volumen verás los puntos, pero sin agrupación temática. * El cálculo se **actualiza automáticamente cada noche**, incorporando las reseñas nuevas. Mientras tanto, la vista comunica el estado real: * **"Estamos preparando tu espacio"**: la primera proyección está en curso y la vista se actualiza sola cuando termina. * **"Aún no hay suficientes reseñas"**: falta volumen para proyectar. La vista se poblará a medida que lleguen reseñas con comentario. ## Explorar el espacio * **Acercar y alejar**: al acercar la cámara ves puntos individuales; al alejarla, los puntos se agregan en estrellas con **conteos exactos** calculados en el servidor, para que el resumen visual nunca mienta. * **Pasar el cursor por un punto**: se carga al momento un extracto del comentario de esa reseña. * **Hacer clic en un tema**: se abre su ficha con las métricas del tema. ## La ficha de tema Al seleccionar un tema se abre una ficha con números **exactos, servidos por el catálogo de temas del servidor**, nunca estimados a partir del dibujo 3D: * Cantidad de **respuestas** y de **sujetos** analizados, con el desglose de clientes identificados y anónimos. * **Primera y última vez** que el tema apareció. * **Tendencia**: en alza, a la baja, estable o nuevo. * **Cobertura de clasificación**: qué proporción de las reseñas del tema fue clasificada. * Distribución de score en **críticas, neutras y positivas**. * **Palabras clave** del tema y **reseñas de evidencia** que lo ilustran. ## Filtros, colores y vista tabla Puedes acotar lo que se muestra con cuatro filtros: | Filtro | Opciones | | - | - | | Periodo | Día, semana, mes, año, histórico | | Fuente | woku, NPS, CSAT, CES | | Tipo | Reconocimiento, Mejora | | Score | Críticas, Neutras, Positivas | El color de los puntos admite dos modos: por **Temas** (cada tema con su color) o por **Tipo de feedback** (reconocimiento y mejora). Además del espacio 3D existe la vista **Tabla**, que muestra la misma información en formato de lista. Puedes alternar entre ambas cuando quieras, y si tu navegador no soporta WebGL la tabla se activa automáticamente como respaldo. ## Distancias aproximadas y reseñas sin tema > [!NOTE] > > La proyección reduce un espacio de muchas dimensiones a solo tres, por lo > que las **distancias en el dibujo son aproximadas**: sirven para orientarse, > no para medir. Los números de la ficha de tema sí son exactos. La leyenda > lo recuerda y además muestra la cobertura real de la vista, por ejemplo > "120 de 150 reseñas proyectadas". Las reseñas que no calzan con ningún tema quedan agrupadas como **"Sin tema"**. Es normal que existan: son comentarios atípicos o muy distintos del resto, y el espacio los muestra en lugar de esconderlos. # Envíos programados de reportes Source: https://woku.app/docs/reports/scheduled-reports Envía por correo el reporte PDF de una carpeta o de una herramienta cada mes, cada quincena, cada semana o una sola vez, a personas dentro y fuera de woku Un **envío programado** manda por correo el reporte PDF de una **carpeta** (todas las herramientas de la carpeta y sus subcarpetas) o de **una herramienta** (woku, NPS, CSAT o CES) a una lista de destinatarios. Los destinatarios no necesitan cuenta en woku: sirve para directorios, jefaturas o clientes que quieren el informe en su bandeja sin entrar a la plataforma. ## Qué lleva el correo * El **PDF del reporte** del período: primero una página de métricas (respuestas, promedio, reconocimientos y oportunidades de mejora, sentimiento, distribución de puntajes y nube de palabras) y después el análisis de comentarios con IA. * En los envíos de una carpeta, el **CSV** de las respuestas del período, si lo activas. * Un enlace para **darse de baja en un clic**. Quien se da de baja deja de recibir los reportes de esa empresa; el resto de los correos de woku no cambia. El correo sale a nombre de tu empresa, en español o en inglés. ## Frecuencias | Frecuencia | Cuándo sale | Qué período cubre | | - | - | - | | Mensual | El día 1, a las 12:00 UTC | El mes anterior completo | | Quincenal | Los días 1 y 16, a las 12:00 UTC | Del 16 a fin de mes, o del 1 al 15 | | Semanal | Los lunes, a las 12:00 UTC | La semana anterior, de lunes a domingo | | Una sola vez | Ahora o en la fecha que elijas | El período que elijas (desde y hasta) | Cada período se envía una sola vez, aunque haya varias instancias del servidor. Si un envío falla, queda registrado y no se reintenta solo; puedes mandarlo de nuevo con **Enviar ahora**. ## En la aplicación En el reporte de una carpeta de **Herramientas**, o en el reporte de un woku, NPS, CSAT o CES, el botón **Programar envío** abre un diálogo con: * La **lista de envíos** de ese reporte, cada uno con su próximo envío o su estado, y las acciones **Enviar ahora**, **Pausar** o **Reanudar**, **Editar** y **Eliminar**. * El **formulario** para agregar uno: frecuencia (con la fecha del próximo envío), destinatarios (hasta 10 correos, separados por coma o en líneas distintas) y, en una carpeta, si adjunta el CSV. Para un envío **único** eliges el período y si sale **ahora** o **en una fecha**. Todos los envíos de la empresa están en **Configuración de empresa > Reportes programados**, en una tabla con el reporte, la frecuencia, los destinatarios y el estado, con las mismas acciones. Un envío único no se edita: se borra y se crea de nuevo. ## API, SDK y MCP * `GET /v1/report-subscriptions` lista los envíos (opcionalmente de una carpeta o herramienta, con `scopeType` y `scopeId`). * `POST /v1/report-subscriptions` crea uno: `scopeType` (`folder`, `woku`, `nps`, `csat` o `ces`), `scopeId`, `frequency` (`monthly`, `biweekly`, `weekly` u `once`), `recipients`, y opcionalmente `includeCsv` y `locale`. Un envío `once` lleva `periodFrom` y `periodTo` (ISO, `periodTo` exclusivo) y `sendAt`; sin `sendAt` sale en los minutos siguientes. * `PATCH /v1/report-subscriptions/:id` edita un envío recurrente o lo pausa (`active: false`) y lo reanuda. * `DELETE /v1/report-subscriptions/:id` lo elimina. * `POST /v1/report-subscriptions/:id/send` lo envía ahora: el último período completo de uno recurrente, o el período propio de uno único. ```ts JavaScript theme={null} const monthly = await woku.reportSubscriptions.create({ scopeType: 'folder', scopeId: folderId, frequency: 'monthly', recipients: ['directorio@empresa.com'], includeCsv: true, }); await woku.reportSubscriptions.update(monthly.id, { active: false }); ``` ```python Python theme={null} monthly = woku.report_subscriptions.create( { "scopeType": "folder", "scopeId": folder_id, "frequency": "monthly", "recipients": ["directorio@empresa.com"], "includeCsv": True, } ) woku.report_subscriptions.update(monthly["id"], {"active": False}) ``` En el servidor MCP están `list_scheduled_reports`, `schedule_report`, `update_scheduled_report`, `delete_scheduled_report` y `send_scheduled_report_now`. Consulta [Herramientas del MCP](/docs/mcp/tools). # Análisis de texto con IA Source: https://woku.app/docs/reports/text-analysis Clasificación automática de comentarios, sentimiento, palabras clave y descubrimiento de temas emergentes con IA en las respuestas abiertas El **análisis de texto con IA** convierte los comentarios abiertos de tus clientes (texto o notas de voz transcritas) en información estructurada y accionable. Funciona sobre las respuestas de **woku, NPS, CSAT y CES** y combina tres capacidades: **clasificación automática** de cada comentario, **palabras clave y resúmenes** generados por IA, y **descubrimiento de temas emergentes** en el conjunto de respuestas. > [!NOTE] > > Todo el análisis es automático y continuo: se aplica a cada respuesta en > el momento en que ingresa, sin configuración previa y sin reglas que > mantener. ## Clasificación automática de comentarios El motor de IA clasifica cada comentario, sea texto escrito o una nota de voz transcrita, según si requiere acción: * **Reconocimiento** (sin acción requerida): no hay nada que hacer, por ejemplo un elogio o un agradecimiento. * **Mejora** (requiere acción): el cliente pide, sugiere o implica algo que tu equipo debería hacer, corregir o responder, aunque venga dentro de un elogio. Esta clasificación se aplica sola al ingresar cada respuesta, en las cuatro herramientas (woku, NPS, CSAT y CES), y decide qué comentarios activan el agente de follow up, las alertas, los tickets y los planes de acción. Los comentarios sin contenido (solo calificación) no se clasifican. El detalle está en [Accionabilidad y sentimiento](/docs/core-concepts/actionability-and-sentiment). ## Sentimiento Además de la accionabilidad, la IA lee el **sentimiento del texto** de cada comentario: **positivo**, **neutro** o **negativo**. Es una lectura independiente que solo se usa para análisis y nunca dispara acciones. Las tarjetas, estadísticas y reportes muestran su distribución y el **sentimiento neto** (de -100 a +100, como el NPS), junto al promedio de la calificación. Ver [Accionabilidad y sentimiento](/docs/core-concepts/actionability-and-sentiment). ### Sentimiento por calificación en los temas En el Espacio de reseñas, cada respuesta se ubica además en uno de tres niveles, **crítico**, **neutro** o **positivo**, derivado de la calificación que dejó el cliente. Estos niveles alimentan los conteos del análisis: cada tema descubierto muestra su distribución de respuestas críticas, neutras y positivas, lo que permite ver de un vistazo si un tema concentra molestia o elogio. ### Investigación propia woku combina **modelos de lenguaje líderes del mercado** con investigación propia en análisis de sentimiento para el español de Latinoamérica, desarrollada en colaboración con el **Doctorado en IA** de la Universidad de Concepción (UdeC), la Universidad Técnica Federico Santa María (USM), la Universidad del Bío-Bío (UBB) y la Universidad Católica de la Santísima Concepción (UCSC), el primer doctorado en Inteligencia Artificial de Latinoamérica. > **[Entrevista sobre el desarrollo del modelo](https://www.linkedin.com/posts/pauriquelme_ia-gowoku-ugcPost-7465134849452908545-Pwaa/?utm_source=share\&utm_medium=member_desktop\&rcm=ACoAAArMdJkBjSyLzdF_dxZqLfZdeR81u-xX-Pg)** > > Video con la entrevista al académico del Doctorado en IA sobre el desarrollo del modelo propio de sentimiento de woku. ## Palabras clave y resúmenes De cada opinión se extraen **palabras clave** automáticas. Estas palabras alimentan la **nube de palabras** de los reportes de woku, de carpeta y de NPS, que además incluyen un **resumen generado por IA** y **acciones sugeridas** a partir de lo que dicen los clientes. CSAT y CES tienen su propio **Resumen IA**, que sintetiza en lenguaje natural las respuestas de cada medición. ### Reportes por período En todos los reportes (de un woku, de una carpeta, de una herramienta NPS, CSAT o CES y los de la empresa) puedes elegir el **período** con las mismas opciones que en Métricas: **Histórico**, **7**, **30** o **90 días**, o **Personalizado**, que abre un calendario para elegir el primer y el último día. El resumen, las cifras y el PDF incluyen solo las respuestas de ese período, y el título del PDF lo indica. El reporte histórico no cambia. La pestaña **Métricas** tiene el mismo selector: con un rango personalizado, cada cifra se compara con el período anterior de igual largo. Con menos de **5 comentarios**, el reporte no genera un resumen con IA, porque con tan pocas respuestas inventaría tendencias: dice que hay pocos comentarios y los muestra tal cual. ### Buscar en los comentarios En las opiniones de un woku y en las respuestas de NPS, CSAT y CES puedes filtrar por **período** y **buscar una palabra** en los comentarios, sin importar mayúsculas ni tildes. Por ejemplo, "iluminacion" encuentra "Iluminación". ## Temas emergentes Más allá de las categorías que ya conoces, el **motor semántico** de woku agrupa las respuestas por significado y descubre **temas emergentes** que no estaban definidos de antemano, con conteos **exactos**: cada cifra corresponde a respuestas reales que puedes revisar. Los temas se exploran en el **Espacio de reseñas**, un universo 3D donde cada respuesta es un punto y las respuestas que hablan de lo mismo quedan cerca. Al seleccionar un tema se abre un panel con: * **Etiqueta y resumen** del tema. * **Cantidad de respuestas** que lo componen. * **Distribución de sentimiento** (crítico, neutro, positivo). * **Tendencia** y primera y última aparición en el tiempo. * **Evidencia**: las respuestas reales que sustentan el tema. El análisis es unificado: un mismo tema puede reunir respuestas de woku, NPS, CSAT y CES. ## Dónde se visualiza Los resultados del análisis de texto aparecen en varios lugares de la plataforma: * **Reportes de herramientas y carpetas**: nubes de palabras, resúmenes IA y acciones sugeridas. El reporte de una carpeta reúne wokus y herramientas NPS, CSAT y CES en un solo análisis (sin mezclar sus escalas de puntaje); ver [Carpetas y herramientas](/docs/guides/folders-and-tools). En la aplicación, ese reporte es la pestaña **Análisis de texto**; la pestaña **Métricas por herramienta** muestra las cifras de cada herramienta. El reporte de cada woku, NPS, CSAT o CES tiene las mismas dos pestañas: **Análisis de texto** y **Métricas**, con las cifras y el sentimiento de esa herramienta. * **Espacio de reseñas**: temas emergentes y distribución de sentimiento. * **Estudio de datos (Corporate)**: análisis interactivo con evidencia de tu empresa. # Protección contra fuerza bruta Source: https://woku.app/docs/security/anti-brute-force Bloqueo automático tras intentos fallidos, notificación al usuario y desbloqueo administrativo Woku detecta y bloquea ataques de fuerza bruta sobre el login para proteger las cuentas de los usuarios. ## Cómo funciona 1. Cada intento de login (exitoso o fallido) queda registrado en una tabla `LoginAttempt` con el identificador usado (lowercased), la IP de origen y el resultado. 2. Si una cuenta acumula **5 intentos fallidos en los últimos 15 minutos**, el sistema: * Pone el campo `lockedUntil` del usuario a **15 minutos en el futuro**. * Registra una entrada `auth.lockout` en el [registro de auditoría](/docs/security/audit-log) con `failedAttempts`, `lockedUntil` y la IP del último intento. * Envía un **email** al usuario notificando el bloqueo (ver abajo). 3. Durante el bloqueo, cualquier intento de login (incluso con la contraseña correcta) responde `403 Forbidden`. 4. Pasado el window de 15 minutos, el bloqueo se levanta automáticamente al siguiente intento, no hace falta acción manual. ## Email de notificación Cuando se dispara el bloqueo, el sistema envía al usuario un correo vía AWS SES con: * **Asunto**: "Bloqueo temporal de tu cuenta en woku". * **Cuerpo**: explica que detectamos varios intentos fallidos, cuándo se levanta el bloqueo, desde qué IP, y un CTA para resetear la contraseña. El email es **fire-and-forget**: si SES está caído, el bloqueo igual ocurre y el fallo del correo se loguea internamente; no hay impacto en la seguridad. ## Desbloqueo administrativo Si el usuario necesita acceder antes de que pase el window, un administrador interno puede desbloquearlo desde el backoffice. La acción queda registrada como `auth.unlock` en el registro de auditoría con la IP del request. ## Limitaciones * La detección es **per-usuario**, no per-IP. Un atacante distribuido desde múltiples IPs probando muchos usuarios distintos no dispara el bloqueo por usuario, pero queda igualmente expuesto al rate limit global (10 req/s, 50 req/10s, 100 req/min por IP, gestionado por `@nestjs/throttler`). * Si el atacante usa un identificador que no corresponde a ningún usuario, no hay bloqueo (no hay nada que bloquear), pero el rate limit por IP igual aplica. ## Verificación de estado El estado de bloqueo de un usuario no se expone públicamente al front. La UI muestra el mismo mensaje genérico ("Usuario o contraseña incorrectos") para evitar revelar si una cuenta existe o no, esto reduce el riesgo de enumeración de usuarios. # Registro de auditoría Source: https://woku.app/docs/security/audit-log Quién hizo qué en tu empresa, cuándo y desde dónde. Filtros, paginación y export CSV. Cada empresa en Woku tiene un **registro de auditoría** propio que captura todas las acciones críticas ejecutadas por sus usuarios. ## Acceder al registro 1. En **admin.woku.app**, ve a **Empresa → Registro de auditoría**. 2. Verás una tabla paginada (25 entradas por página) con las acciones más recientes arriba. ## Qué eventos quedan registrados | Categoría | Eventos registrados | | - | - | | Autenticación | `auth.login`, `auth.logout`, `auth.lockout`, `auth.unlock`, `auth.session.revoke`, `auth.mfa.enroll.start`, `auth.mfa.enroll.confirm`, `auth.mfa.verify`, `auth.mfa.disable`, `auth.mfa.backup-codes.regenerate` | | Empresa | `company.create`, `company.update`, `company.add-admin`, `company.remove-member` | | Usuario | `user.create`, `user.update-name`, `user.update-email`, `user.password-recover` | | Woku | `woku.create`, `woku.update`, `woku.delete`, `woku.close` | | Formulario | `form.create`, `form.update`, `form.delete` | Cada entrada incluye: * **Fecha/hora** exacta (ISO 8601 con milisegundos). * **Acción** (uno de los códigos de arriba). * **Recurso** afectado y su ID cuando aplica. * **Actor**: email del usuario que ejecutó la acción (cuando hay sesión autenticada). * **IP** del request (extraída de `x-forwarded-for` o IP directa). ## Filtrar La barra de filtros permite combinar: * **Acción** (texto exacto, por ejemplo `auth.login`). * **Recurso** (texto exacto, por ejemplo `user` o `woku`). * **Email del actor**. * **Rango de fechas** (Desde / Hasta, ambas opcionales). Haz clic en **Aplicar** para refrescar la tabla con los filtros. **Limpiar** vuelve al estado sin filtros. ## Exportar a CSV El botón **Exportar CSV** descarga todas las entradas que coinciden con los filtros actuales (la paginación se ignora; siempre exporta el match completo). El archivo se llama `audit-log-YYYY-MM-DD.csv` y contiene las columnas: ``` timestamp,action,resource,resourceId,actorEmail,actorId,companyId,ip,userAgent ``` Las comillas, comas y saltos de línea se escapan según RFC 4180. ## Retención * **Default**: 365 días. Pasada esa fecha, MongoDB elimina las entradas vía un TTL index per-documento (`expireAt`). * **Configurable per-empresa**: una mejora pendiente expondrá el ajuste en la UI de Settings. Por ahora la retención se puede customizar contactando a soporte. ## Garantías * **Audit fire-and-forget**: el registro de un evento NUNCA bloquea ni revierte la acción auditada. Si la base de auditoría está caída, la acción sigue su curso y el fallo se loguea internamente. * **Aislamiento per-empresa**: el filtro `companyId` siempre se aplica en queries del UI. No hay manera de listar acciones de otra empresa. * **Inmutable**: las entradas no se editan ni se borran a mano. Solo expiran por TTL. # Autenticación Source: https://woku.app/docs/security/authentication Flujo de inicio de sesión, sesiones persistentes, idle timeout y refresh tokens ## Inicio de sesión Los usuarios inician sesión en `admin.woku.app/login` con su email (o usuario) + contraseña. La contraseña se compara contra un hash bcrypt; la contraseña en plano nunca se almacena ni se transmite más allá del propio formulario. Un inicio de sesión exitoso genera: * Un **access token** (JWT firmado) que el cliente adjunta como `Authorization: Bearer ` en cada request. * Un **refresh token** opaco (32 bytes aleatorios, single-use) con validez de 30 días. * Una **Session** persistida del lado del servidor que liga el token a un usuario y permite revocarlo o expirarlo. ## Idle timeout Cada request autenticado refresca el campo `lastActivity` de la sesión (debounced cada 60 segundos para no saturar la base). Si la sesión queda sin actividad por más del tiempo configurado, se cierra automáticamente: el siguiente request recibe `401 Unauthorized` y el usuario debe iniciar sesión de nuevo. * **Default**: 7 días de inactividad → cierre. * **Override per-sesión**: opcional, vía el campo `idleTimeoutMin` de la sesión. * **Override global**: variable de entorno `SESSION_IDLE_TIMEOUT_MIN`. El cierre por idle también persiste `isClosed: true` en la sesión, de modo que un atacante con el token robado tampoco puede usarlo. ## Refresh tokens (rotación single-use) Cuando el cliente quiere prolongar la sesión sin pedirle al usuario que ingrese sus credenciales nuevamente, envía su refresh token actual al servicio de autenticación. El servidor: 1. Verifica que el refresh exista, no esté cerrado, y no esté vencido. 2. Genera **un nuevo par** (access + refresh) y **invalida el viejo** atómicamente en la misma fila `Session`. 3. Devuelve el par nuevo. Si el refresh es desconocido, está cerrado, o ya expiró, la respuesta es `401 Unauthorized` y el usuario debe iniciar sesión otra vez. ## Logout Al cerrar sesión, esta se marca como cerrada (`isClosed: true`). A partir de ahí, ningún request con ese access ni con su refresh funciona. ## Garantías * **Tokens nunca aparecen en la URL**: solo van por header o body, y TLS los protege en tránsito (ver [Headers y CSP](/docs/security/headers-and-csp) para HSTS). * **Revocación inmediata**: el admin puede revocar cualquier sesión desde el endpoint backoffice; el siguiente request del token revocado falla. * **Compatibilidad**: el flujo con solo access token sigue funcionando para clientes que no implementan refresh (la rotación es opt-in). # Cifrado en reposo y firmas de integridad Source: https://woku.app/docs/security/encryption-and-signatures Cómo Woku protege datos sensibles almacenados y cómo asegura que documentos críticos no se modifiquen sin detectarlo Woku usa dos primitivas criptográficas para proteger los datos que guarda en su base: * **Cifrado AES-256-GCM** para campos sensibles en reposo. * **HMAC-SHA256** para firmar documentos críticos y detectar cualquier modificación posterior. Ambas primitivas viven en un único `EncryptionService` del backend y usan la misma clave maestra (`ENCRYPTION_KEY`) derivada vía `scrypt`. ## Cifrado en reposo ### Cuándo se cifra Todo campo que contenga información personal o credenciales se cifra antes de persistirse en MongoDB. En particular: * **Datos de cliente** en respuestas anónimas: email y teléfono se almacenan cifrados (`form-submission`). * **Credenciales de integraciones** y tokens de OAuth (cuando una empresa conecta Woku con Salesforce, Sperant, etc.). * **Secrets de webhooks** que la empresa configura para recibir eventos. ### Cómo funciona | | Valor | | - | - | | Algoritmo | AES-256-GCM (autenticación integrada vía auth tag) | | Llave | Derivada con `scrypt(ENCRYPTION_KEY, salt, 32)` | | IV | Aleatorio de 12 bytes por cada cifrado | | Formato persistido | `::` | Cada cifrado usa un IV nuevo, así que cifrar dos veces el mismo valor produce dos ciphertexts distintos (no se puede inferir igualdad por inspección). El `authTag` se valida en cada descifrado: si el ciphertext fue alterado, el descifrado lanza un error en vez de devolver basura. ### Búsqueda sobre campos cifrados Para poder buscar por email sin descifrar todos los registros, Woku guarda un hash SHA-256 paralelo (`generateSearchHash`) en lowercase. La búsqueda compara hash contra hash, no texto contra texto. ## Firmas de integridad (HMAC-SHA256) ### Para qué sirven Cuando una empresa exige que sus respuestas de formularios no puedan ser modificadas después de almacenarse (auditoría legal, compliance de sector regulado), Woku puede firmar cada documento con **HMAC-SHA256** al momento de escribirlo y verificar la firma al leerlo. Si alguien modifica el documento en la base directamente, la verificación falla y la lectura devuelve error. ### Cómo funciona ``` firma = HMAC-SHA256(ENCRYPTION_KEY, ":") ``` | | Detalle | | - | - | | Algoritmo | HMAC-SHA256 | | Llave | La misma `ENCRYPTION_KEY` derivada arriba | | Entrada | Concatenación `:` | | Salida | 64 caracteres hex | | Verificación | Constant-time (`crypto.timingSafeEqual`) | **Scope = separación de dominio**: cada caso de uso firma con un scope distinto (ej: `form-submission`, `form-response`). Una firma generada para un scope **no es válida** en otro, así un atacante no puede mover firmas entre tipos de documentos. **JSON canónico**: Woku ordena recursivamente las llaves de los objetos antes de firmar, así dos representaciones lógicamente iguales del mismo documento producen la misma firma (independiente de en qué orden las recibió la API o las escribió Mongo). Los arrays NO se reordenan, el orden posicional es semánticamente significativo. ### Activar para tu empresa Hay un flag por empresa: `integrityHashEnabled`. Cuando se activa, las nuevas escrituras de documentos críticos se firman; las lecturas verifican y fallan si la firma no coincide. > **Estado actual:** la primitiva (`signDocument` / `verifySignature`) > ya está disponible en el backend y el flag existe en el modelo de > empresa. La integración automática con `form-submission` y > `form-response` (cuando `integrityHashEnabled` está activo) llega > en un release posterior. Los clientes con compliance estricto que > necesiten esto antes pueden coordinarlo con soporte. ## Gestión de llave * `ENCRYPTION_KEY` vive en SSM Parameter Store como `SecureString` bajo `/shared/prod/secrets/ENCRYPTION_KEY` y se inyecta al container al arrancar (ver [Gestión de secrets](/docs/security/secrets-management)). * Rotación de la llave es manual hoy. Implica: 1. Generar la llave nueva. 2. Re-cifrar todos los registros (script de migración) con la nueva llave antes de switchear `ENCRYPTION_KEY` en SSM, en una ventana de mantenimiento. 3. Descartar la vieja. * No hay HSM en V1; la llave vive en variables de entorno del proceso (en memoria) y nunca se loggea. ## Garantías * **Cifrado autenticado**: si un atacante modifica el ciphertext en la base, el `authTag` no valida y el descifrado lanza error → el registro alterado no se devuelve como si fuera válido. * **Firma constant-time**: `verifySignature` usa comparación resistente a timing attacks. * **Domain separation**: el scope en HMAC evita reutilización de firmas entre tipos de documentos. * **JSON determinístico**: la canonicalización elimina ambigüedad por orden de llaves. ## Limitaciones conocidas * La rotación de `ENCRYPTION_KEY` requiere ventana de mantenimiento (no hay key versioning aún). * La firma de `form-submission` / `form-response` no está cableada automáticamente; llega en el release de Stage 10. * La aplicación a credenciales de integraciones de terceros depende de que esas integraciones se construyan (Stage 6). # Headers de seguridad y CSP Source: https://woku.app/docs/security/headers-and-csp HSTS, CSP nonce-based, X-Frame-Options, Permissions-Policy y demás headers aplicados por defecto Toda respuesta HTTP de Woku incluye un set de headers de seguridad calibrados para obtener calificación A+ en [securityheaders.com](https://securityheaders.com). ## Headers comunes (todos los dominios) | Header | Valor | Por qué | | - | - | - | | `Strict-Transport-Security` | `max-age=63072000; includeSubDomains; preload` | Fuerza HTTPS por 2 años en navegador. Apto para HSTS preload list. | | `X-Content-Type-Options` | `nosniff` | Bloquea MIME-sniffing. | | `X-Frame-Options` | `DENY` | Bloquea cualquier framing del contenido. Defensa-en-profundidad sobre `frame-ancestors`. | | `Referrer-Policy` | `strict-origin-when-cross-origin` | No leakea path/query a sitios externos. | | `Permissions-Policy` | `camera=(self), microphone=(self), geolocation=(), interest-cohort=()` | Habilita cámara/micrófono solo para Woku; bloquea geolocation y FLoC. | | `Cross-Origin-Opener-Policy` | `same-origin` | Aísla el contexto del navegador para mitigar Spectre. | ## API (`api.woku.app`) La API sirve también la documentación Swagger en `/documentation`, que usa scripts inline propios. En el API se aplican todos los headers de arriba y **CSP no se enforza** porque la API no es una superficie HTML para usuarios. La protección CSP se enforza en los frontends donde corre código que ejecuta el navegador (review, admin). CORS está restringido a una **allowlist** (`ALLOWED_ORIGINS` env var). En desarrollo se añaden `localhost:5173` (Vite admin) y `localhost:3000` (Next.js review) automáticamente. ## Frontend público (`review.woku.app`) Además de los headers comunes, este dominio aplica una **CSP nonce-based** generada per-request: ``` default-src 'self'; script-src 'self' 'nonce-' 'strict-dynamic'; style-src 'self' 'unsafe-inline'; img-src 'self' blob: data: https://wokuapifiles.s3.us-east-1.amazonaws.com; font-src 'self' data:; connect-src 'self' https://api.woku.app wss://api.woku.app; media-src 'self' blob: https://wokuapifiles.s3.us-east-1.amazonaws.com; frame-ancestors 'none'; base-uri 'self'; form-action 'self'; object-src 'none'; upgrade-insecure-requests ``` Lo importante: * **`script-src` con nonce + `strict-dynamic`**: solo se ejecuta el bundle de Next.js (que lleva el nonce) y los scripts que ese bundle cargue dinámicamente. Cualquier ` ``` **3. Verifica** Abre tu sitio y espera a que se dispare el trigger (en el ejemplo, 5 segundos). El widget aparecerá como modal. > [!WARNING] > > Usa **siempre** la publishable key (`pk_...`) en el widget, **nunca** la > clave secreta de la API. El widget es código público: cualquiera puede > inspeccionar su configuración. La publishable key solo permite capturar > feedback; no expone datos de tu cuenta. ## Autenticación: publishable key El widget se autentica con la **publishable key** de tu empresa, enviándola en el header `x-woku-key` de cada captura. A diferencia de la clave secreta (usada por integraciones server-side), la publishable key: * Empieza con el prefijo `pk_` (ej. `pk_live_...`). * Es **segura de embeber** en HTML público. * Solo tiene permiso de **captura** (no lee ni administra recursos). La encuentras en **Empresa → Integraciones** del panel administrativo ([https://admin.woku.app](https://admin.woku.app)). ## Configuración El objeto que pasas a `WokuWidget.init(...)` acepta estos campos: | Campo | Requerido | Descripción | | - | - | - | | `companyId` | sí | Identificador de tu empresa. | | `publishableKey` | sí | Clave pública `pk_...` (header `x-woku-key`). | | `captureType` | sí | `'woku'` (estrellas 1-5) o `'nps'` (escala 0-10). | | `wokuId` | condicional | Requerido cuando `captureType === 'woku'`. | | `npsToolId` | no | Para NPS; si se omite, el NPS es a nivel de empresa. | | `apiBaseUrl` | no | URL base de la API. Por defecto `https://clientapi.woku.app`. | | `widgetBaseUrl` | no | Origen del iframe. Por defecto `https://cdn.woku.app/sdks/woku-widget/v1`. | | `lang` | no | `'es'` o `'en'`. Si se omite, se autodetecta del navegador. | | `branding` | no | Muestra "Powered by Woku". Por defecto `true`. | | `theme` | no | Personalización visual (ver [Tema](#tema)). | | `triggers` | sí | Lista de condiciones que muestran el widget (ver [Triggers](#triggers)). | | `urlRules` | no | Reglas include/exclude por URL (regex). | ### Tipo de captura: woku vs NPS **woku (1-5 estrellas)** Captura una calificación de 1 a 5 estrellas asociada a un `wokuId`. ```html theme={null} ``` En modo `woku` el usuario ve estrellas 1-5 y, opcionalmente, deja un comentario en texto o audio. **NPS (0-10)** Captura un puntaje NPS de 0 a 10. El `npsToolId` es opcional: si lo omites, la captura se asocia al NPS a nivel de empresa. ```html theme={null} ``` woku categoriza automáticamente cada respuesta: detractor (0-6), pasivo (7-8) o promotor (9-10). ### Idioma (i18n) El widget incluye dos idiomas: **español** (`es`, por defecto) e **inglés** (`en`). El idioma se resuelve en este orden: 1. El campo `lang` de la configuración. 2. El idioma del navegador (`navigator.language`). 3. Fallback a `es`. **Español** ```js theme={null} WokuWidget.init({ companyId: 'TU_COMPANY_ID', publishableKey: 'pk_live_...', captureType: 'nps', lang: 'es', triggers: [{ type: 'time', value: 5, behavior: 'modal' }], }); ``` **Inglés** ```js theme={null} WokuWidget.init({ companyId: 'TU_COMPANY_ID', publishableKey: 'pk_live_...', captureType: 'nps', lang: 'en', triggers: [{ type: 'time', value: 5, behavior: 'modal' }], }); ``` **Autodetección** ```js theme={null} // Sin lang: se usa navigator.language y, si no, español. WokuWidget.init({ companyId: 'TU_COMPANY_ID', publishableKey: 'pk_live_...', captureType: 'nps', triggers: [{ type: 'time', value: 5, behavior: 'modal' }], }); ``` ### Triggers Cada trigger define **cuándo** aparece el widget y **cómo** se presenta (`behavior`). Puedes combinar varios; se dispara el primero que cumpla. ```ts theme={null} interface TriggerConfig { type: 'time' | 'scroll' | 'exit-intent' | 'custom-event' | 'click-selector'; value?: number | string; // segundos, % de scroll, nombre de evento o selector CSS behavior: 'modal' | 'banner' | 'side-tab' | 'fullscreen'; } ``` | `type` | `value` | Cuándo se dispara | | - | - | - | | `time` | segundos | Tras N segundos en la página. | | `scroll` | porcentaje | Al alcanzar N % de scroll. | | `exit-intent` | | Al mover el cursor fuera de la ventana (solo escritorio). | | `custom-event` | nombre del evento | Al dispararse `window.dispatchEvent(new Event(nombre))`. | | `click-selector` | selector CSS | Al hacer clic en un elemento que coincide. | Modos de presentación (`behavior`): `modal` (ventana centrada con overlay), `banner` (barra fija), `side-tab` (pestaña lateral) y `fullscreen` (pantalla completa). ```js theme={null} WokuWidget.init({ companyId: 'TU_COMPANY_ID', publishableKey: 'pk_live_...', captureType: 'nps', triggers: [ { type: 'scroll', value: 70, behavior: 'banner' }, { type: 'click-selector', value: '#dar-feedback', behavior: 'modal' }, ], }); ``` ### Tema Personaliza la apariencia del widget. Los valores se aplican como CSS custom properties dentro del iframe (excepto `zIndex`, que controla el overlay en tu página): ```js theme={null} WokuWidget.init({ // ... theme: { primaryColor: '#1447e6', fontFamily: 'Inter, sans-serif', borderRadius: '12px', zIndex: 9999, }, }); ``` ## API programática El loader expone `window.WokuWidget`: ```js theme={null} WokuWidget.show(); // muestra el widget manualmente WokuWidget.hide(); // lo oculta WokuWidget.destroy(); // remueve el iframe y limpia los listeners WokuWidget.on('open', () => { /* el widget se abrió */ }); WokuWidget.on('close', () => { /* el widget se cerró */ }); WokuWidget.on('submit', (data) => { console.log('enviado:', data); }); WokuWidget.on('skip', () => { /* el usuario omitió el feedback */ }); ``` ## Requisitos de CSP Si tu sitio usa **Content-Security-Policy**, debes permitir el origen del CDN tanto para el script del loader como para el iframe de la micro-app: ``` Content-Security-Policy: script-src cdn.woku.app; /* el loader