Carpetas y herramientas

​

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.

​

En la aplicación

• 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.

​

Carpetas

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" }'

​

Crear una herramienta dentro de una carpeta

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": "<id de la carpeta>" }'

​

Buscar y listar herramientas

​

Cifras por tipo

​

Métricas por herramienta de una carpeta

• 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).

curl "https://clientapi.woku.app/v1/folders/FOLDER_ID/metrics?days=30" \
  --header "Authorization: Bearer $WOKU_API_KEY"

​

Mover en lote

{
  "items": [
    { "type": "csat", "id": "<id de la herramienta>" },
    { "type": "woku", "id": "<id del woku>" },
    { "type": "folder", "id": "<id de una carpeta>" }
  ],
  "folderId": null
}

​

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.

​

Alertas de WhatsApp por carpeta

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.
• 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 por hora; los siguientes se descartan.
• 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

• 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).

curl --request POST https://clientapi.woku.app/v1/journey-folders/organize \
  --header "Authorization: Bearer $WOKU_API_KEY"

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);

​

SDK y MCP

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);
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'] });

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"])
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"]})