Documentación de woku - Guía para desarrolladores

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.

El SDK @wokuapp/sdk es el cliente oficial de servidor para la API de gestion de woku. Con un solo cliente tipado administras trackers externos, herramientas VoC (NPS, CSAT, CES), wokus, formularios, flows, planes de accion, tickets de soporte, envios de encuestas y seguimiento de entrega, todo sobre la API pública v1.

Es un SDK de servidor. La clave secreta de compañía otorga acceso completo de gestion, asi que debe vivir solo en tu backend. Nunca la incluyas en un bundle de navegador, una app móvil ni ningún cliente que no controles. Para capturar feedback desde una app móvil usa el SDK de React Native, que usa una clave pública de captura.

Instalación

npm install @wokuapp/sdk

Requiere Node.js 18 o superior (usa el fetch global). No tiene dependencias de runtime.

Inicialización

Crea una instancia de Woku una sola vez y reutilízala.

import { Woku } from '@wokuapp/sdk';

const woku = new Woku({ apiKey: process.env.WOKU_API_KEY });

Si omites apiKey, el SDK lee la variable de entorno WOKU_API_KEY. También puedes pasar la clave directamente: new Woku('sk_...').

Opción	Requerida	Descripción
`apiKey`	sí	Clave secreta de compañía. Por defecto `process.env.WOKU_API_KEY`.
`baseURL`	no	URL base de la API. Por defecto `https://clientapi.woku.app`.
`timeout`	no	Tiempo máximo por solicitud en ms. Por defecto `60000`.
`maxRetries`	no	Reintentos automáticos ante fallos transitorios. Por defecto `2`.

Autenticación

El SDK autentica con la Clave de Compañía, la misma clave secreta que usa la API. La obtiene el propietario de la empresa desde la sección Información de la empresa en la aplicación administrativa: admin.woku.app.

Authorization: Bearer <Company-Key>

El SDK agrega ese header por ti en cada llamada.

Rotar o revocar la clave

Como la clave secreta otorga acceso completo, puedes rotarla o revocarla desde el propio SDK. Rotar genera una clave nueva e invalida de inmediato la anterior; guarda la que devuelve antes de continuar.

const { secretKey } = await woku.company.rotateKey();
// guarda secretKey de forma segura; la clave anterior deja de funcionar

await woku.company.revokeKey(); // deja la cuenta sin clave activa

Quickstart

Un flujo completo: crear un tracker, crear una herramienta NPS, etiquetarla con el tracker, enviarla y leer la tasa de respuesta.

import { Woku } from '@wokuapp/sdk';

const woku = new Woku({ apiKey: process.env.WOKU_API_KEY });

// 1. Crear una definición de tracker (idempotente).
const tracker = await woku.trackers.create({
  name: 'Tienda #1',
  system: 'retail',
});

// 2. Crear una herramienta NPS.
const tool = await woku.npsTools.create({
  name: 'Post-compra',
  npsMessage: '¿Qué tan probable es que nos recomiendes?',
});

// 3. Asignar un valor del tracker a la herramienta NPS, para que cada respuesta
//    quede etiquetada con la tienda y el reporte se agrupe por ella.
await woku.trackers.assignToEntity('nps', tool._id, {
  name: tracker.name,
  value: 'TX-42',
});

// 4. Enviarla por correo o WhatsApp.
await woku.nps.sendInvitations({
  channel: 'email',
  npsToolId: tool._id,
  recipients: ['ana@example.com'],
});

// 5. Leer la entrega y la tasa de respuesta.
const stats = await woku.dispatches.stats({ channel: 'email' });
console.log(stats.responseRate);

Flujos principales

Herramientas VoC

Crea y administra herramientas NPS, CSAT y CES, y captura sus respuestas.

const csat = await woku.csatTools.create({
  name: 'Soporte',
  question: '¿Qué tan satisfecho quedaste con la atención?',
});

// Enviar y luego leer respuestas.
await woku.csat.sendInvitations({
  channel: 'email',
  csatToolId: csat._id,
  recipients: ['ana@example.com'],
});
for await (const response of await woku.csat.listResponses()) {
  console.log(response);
}

Tickets de soporte

Los tickets los genera la IA de woku. Puedes listarlos, filtrarlos y curarlos.

for await (const ticket of await woku.tickets.list({ severity: 'high' })) {
  console.log(ticket.title);
}

const stats = await woku.tickets.stats();

Planes de acción

Aprueba y gestiona los planes de acción dentro de woku: cambia su estado y administra sus tareas.

await woku.actionPlans.approve('plan_123');

// Leer el detalle y la línea de tiempo del plan.
const plan = await woku.actionPlans.get('plan_123');
const events = await woku.actionPlans.events('plan_123');

// Cerrar o reabrir el plan.
await woku.actionPlans.complete('plan_123');

Paginación

Los métodos de listado devuelven una Page. Recorre cada elemento a través de las páginas, o página por página:

for await (const ticket of await woku.tickets.list({ severity: 'high' })) {
  console.log(ticket.title);
}

const first = await woku.dispatches.list({ channel: 'whatsapp' });
if (first.hasNextPage()) {
  const second = await first.getNextPage();
}

Idempotencia

Los GET y las escrituras protegidas se reintentan con la misma clave: crear trackers o herramientas NPS/CSAT/CES, enviar invitaciones de los cinco tipos, y crear, inscribir, detener, generar URL o emitir eventos de Viajes. Las otras escrituras, los uploads y la rotación de secretos se intentan una sola vez. Una clave por sí sola no agrega idempotencia a un endpoint sin soporte. La deduplicación dura 24 horas. Un resultado incierto conserva su registro; verifica el resultado antes de cambiar de clave o repetir fuera de ese plazo.

Manejo de errores

Cada fallo es un WokuError. Los errores HTTP son subclases tipadas que llevan el status, el cuerpo y el requestId del servidor:

import { NotFoundError, RateLimitError } from '@wokuapp/sdk';

try {
  await woku.tickets.get('inexistente');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.error(err.status, err.requestId); // 404, "req_..."
  } else if (err instanceof RateLimitError) {
    console.error('reintenta en', err.retryAfterSeconds);
  }
}

Los fallos de transporte (DNS, TLS, timeout) son WokuConnectionError y WokuTimeoutError. El SDK reintenta automáticamente los GET y las escrituras idempotentes con backoff y respeto del header Retry-After.

Configuración por llamada

Cada método acepta overrides en su último argumento:

await woku.tickets.list(
  { severity: 'high' },
  { timeout: 10_000, maxRetries: 0 },
);

Referencia

Referencia completa de namespaces y métodos. Para las formas exactas de request y response, consulta el API reference.

actionPlans

Lee y gestiona planes de acción, incluido el kanban gestionado (tareas, conversación IA y transiciones de estado).

Método	Retorno	Descripción
`list(params?, opts?)`	`Promise<Page<WokuRecord>>`	Lista los planes de acción, con filtros opcionales y paginación.
`get(id, opts?)`	`Promise<WokuRecord>`	Obtiene un plan de acción por id.
`events(id, opts?)`	`Promise<WokuRecord[]>`	Devuelve la línea de tiempo del plan (eventos, más antiguos primero).
`getConversation(id, opts?)`	`Promise<WokuRecord>`	Devuelve la conversación IA del plan (solo lectura).
`reply(id, text, opts?)`	`Promise<WokuRecord>`	Responde al agente IA del plan (turno pago, compuesto de forma asincrónica).
`createTask(id, body, opts?)`	`Promise<WokuRecord>`	Crea una tarea en el plan.
`updateTask(id, taskId, body, opts?)`	`Promise<WokuRecord>`	Actualiza una tarea del plan.
`reorderTasks(id, body, opts?)`	`Promise<WokuRecord>`	Reordena las tareas del plan.
`deleteTask(id, taskId, opts?)`	`Promise<WokuRecord>`	Elimina una tarea del plan.
`approve(id, opts?)`	`Promise<WokuRecord>`	Aprueba el plan.
`reopen(id, opts?)`	`Promise<WokuRecord>`	Reabre el plan.
`cancel(id, opts?)`	`Promise<WokuRecord>`	Cancela el plan.
`complete(id, opts?)`	`Promise<WokuRecord>`	Marca el plan como completado.
`resume(id, opts?)`	`Promise<WokuRecord>`	Reanuda el plan.

actionPlanGroups

Gestiona los grupos de planes de acción (listar, obtener con stats, crear, actualizar, habilitar/deshabilitar y eliminar).

Método	Retorno	Descripción
`list(params?, opts?)`	`Promise<WokuRecord[]>`	Lista los grupos, con busqueda opcional.
`get(id, opts?)`	`Promise<WokuRecord>`	Obtiene un grupo con sus stats embebidas.
`create(body, opts?)`	`Promise<WokuRecord>`	Crea un grupo.
`update(id, body, opts?)`	`Promise<WokuRecord>`	Actualiza un grupo.
`setEnabled(id, enabled, opts?)`	`Promise<WokuRecord>`	Habilita o deshabilita el grupo.
`delete(id, opts?)`	`Promise<WokuRecord>`	Elimina el grupo.

company

Gestiona la empresa que hace la llamada y su clave de API en /v1/companies/me.

Método	Retorno	Descripción
`me(opts?)`	`Promise<WokuRecord>`	Obtiene la empresa que hace la llamada.
`rotateKey(opts?)`	`Promise<ApiKeyResult>`	Rota la clave secreta y devuelve la nueva (invalida la anterior).
`revokeKey(opts?)`	`Promise<WokuRecord>`	Revoca la clave secreta.

dispatches

Seguimiento de entrega sobre los envios de invitaciones (/v1/dispatches).

Método	Retorno	Descripción
`list(params?, opts?)`	`Promise<Page<Dispatch>>`	Lista los envios con estado de entrega, sin PII.
`stats(params?, opts?)`	`Promise<DispatchStats>`	Devuelve metricas de tasa de respuesta sobre los envios.

flows

Acceso de solo lectura a los flujos de encuestas (/v1/flows).

Método	Retorno	Descripción
`list(params?, opts?)`	`Promise<Page<WokuRecord>>`	Lista los flujos de encuestas, paginado.
`get(id, opts?)`	`Promise<WokuRecord>`	Obtiene un flujo de encuestas por id.

forms

Lee formularios y sus respuestas, y envia invitaciones de formulario (/v1/forms).

Método	Retorno	Descripción
`list(params?, opts?)`	`Promise<Page<WokuRecord>>`	Lista los formularios, paginado.
`get(id, opts?)`	`Promise<WokuRecord>`	Obtiene un formulario por id.
`listResponses(id, params?, opts?)`	`Promise<Page<WokuRecord>>`	Lista las respuestas de un formulario, paginado.
`sendInvitations(id, body, opts?)`	`Promise<InvitationsResult>`	Envia un formulario por correo o WhatsApp (idempotente).

quarantines

Verifica si un contacto esta en cuarentena (/v1/quarantines).

Método	Retorno	Descripción
`check(params, opts?)`	`Promise<WokuRecord>`	Verifica si un contacto (email o teléfono) esta en cuarentena.

reports

Lee reportes NPS (/v1/reports): a nivel empresa y por herramienta NPS.

Método	Retorno	Descripción
`companyNps(params?, opts?)`	`Promise<WokuRecord>`	Obtiene el reporte NPS a nivel empresa.
`npsTool(npsToolId, params?, opts?)`	`Promise<WokuRecord>`	Obtiene el reporte NPS de una herramienta NPS.

nps

Envia la encuesta NPS y lee sus respuestas (/v1/nps).

Método	Retorno	Descripción
`sendInvitations(body, opts?)`	`Promise<InvitationsResult>`	Envia la encuesta NPS por correo o WhatsApp (idempotente).
`listResponses(params?, opts?)`	`Page<WokuRecord>`	Lista las respuestas NPS, paginado.
`getResponse(id, opts?)`	`Promise<WokuRecord>`	Obtiene una respuesta NPS por id.

csat

Envia la encuesta CSAT y lee sus respuestas (/v1/csat).

Método	Retorno	Descripción
`sendInvitations(body, opts?)`	`Promise<InvitationsResult>`	Envia las invitaciones CSAT (idempotente).
`listResponses(params?, opts?)`	`Page<WokuRecord>`	Lista las respuestas CSAT, paginado.
`getResponse(id, opts?)`	`Promise<WokuRecord>`	Obtiene una respuesta CSAT por id.

ces

Envia la encuesta CES y lee sus respuestas (/v1/ces).

Método	Retorno	Descripción
`sendInvitations(body, opts?)`	`Promise<InvitationsResult>`	Envia las invitaciones CES (idempotente).
`listResponses(params?, opts?)`	`Page<WokuRecord>`	Lista las respuestas CES, paginado.
`getResponse(id, opts?)`	`Promise<WokuRecord>`	Obtiene una respuesta CES por id.

tickets

Lee y cura los tickets de soporte generados por IA (/v1/tickets).

Método	Retorno	Descripción
`list(params?, opts?)`	`Promise<Page<Ticket>>`	Lista los tickets con filtros opcionales.
`stats(params?, opts?)`	`Promise<TicketStats>`	Devuelve conteos agregados por herramienta y por destino.
`get(id, opts?)`	`Promise<Ticket>`	Obtiene un ticket por id.
`update(id, body, opts?)`	`Promise<Ticket>`	Actualiza (patch) un ticket.

ticketDestinations

Gestiona los destinos de tickets SAC (/v1/ticket-destinations).

Método	Retorno	Descripción
`list(opts?)`	`Promise<WokuRecord[]>`	Lista todos los destinos configurados.
`get(id, opts?)`	`Promise<WokuRecord>`	Obtiene un destino por id.
`create(body, opts?)`	`Promise<WokuRecord>`	Crea un destino.
`update(id, body, opts?)`	`Promise<WokuRecord>`	Actualiza (patch) un destino.
`delete(id, opts?)`	`Promise<WokuRecord>`	Elimina un destino.
`test(id, opts?)`	`Promise<TestConnectionResult>`	Envia una prueba de conectividad real al destino (confirm:true automatico).

trackers

Gestiona definiciones de tracker externas y asigna/quita valores de tracker en wokus y entidades VoC (/v1/external-trackers).

Método	Retorno	Descripción
`list(params?, opts?)`	`Promise<Page<Tracker>>`	Lista las definiciones de tracker, paginado.
`create(body, opts?)`	`Promise<Tracker>`	Crea una definición de tracker (idempotente).
`get(id, opts?)`	`Promise<Tracker>`	Obtiene una definición de tracker por id.
`update(id, body, opts?)`	`Promise<Tracker>`	Actualiza una definición de tracker.
`activate(id, opts?)`	`Promise<Tracker>`	Activa una definición de tracker.
`deactivate(id, opts?)`	`Promise<Tracker>`	Desactiva una definición de tracker.
`searchEntities(body, opts?)`	`Promise<EntitiesByTrackers>`	Busca entidades VoC cuyos trackers cumplen todos los filtros (AND).
`listWokuValues(wokuId, opts?)`	`Promise<WokuRecord[]>`	Lista los valores de tracker asignados a un woku.
`assignToWoku(wokuId, body, opts?)`	`Promise<WokuRecord>`	Asigna (upsert) un valor de tracker a un woku por nombre (idempotente).
`removeFromWoku(wokuId, trackerName, opts?)`	`Promise<WokuRecord>`	Quita un valor de tracker de un woku por nombre.
`searchWokus(params, opts?)`	`Promise<Page<WokuRecord>>`	Busca wokus por un par exacto (nombre de tracker, valor), paginado.
`listEntityValues(entityType, id, opts?)`	`Promise<WokuRecord[]>`	Lista los valores de tracker de una entidad VoC (nps/csat/ces/form/flow).
`assignToEntity(entityType, id, body, opts?)`	`Promise<WokuRecord>`	Asigna (upsert) un valor de tracker a una entidad VoC por nombre (idempotente).
`removeFromEntity(entityType, id, trackerName, opts?)`	`Promise<WokuRecord>`	Quita un valor de tracker de una entidad VoC por nombre.

npsTools

Gestiona las definiciones de herramientas NPS (/v1/nps-tools).

Método	Retorno	Descripción
`list(params?, opts?)`	`Promise<Page<NpsTool>>`	Lista las definiciones NPS, paginado.
`create(body, opts?)`	`Promise<NpsTool>`	Crea una definición NPS (POST idempotente).
`get(id, opts?)`	`Promise<NpsTool>`	Obtiene una herramienta NPS por id.
`update(id, body, opts?)`	`Promise<NpsTool>`	Actualiza (patch) una herramienta NPS.
`delete(id, opts?)`	`Promise<DeletedResult>`	Elimina una herramienta NPS por id.

csatTools

Gestiona las definiciones de herramientas CSAT (/v1/csat-tools).

Método	Retorno	Descripción
`list(params?, opts?)`	`Promise<Page<CsatTool>>`	Lista las definiciones CSAT, paginado.
`create(body, opts?)`	`Promise<CsatTool>`	Crea una definición CSAT (POST idempotente).
`get(id, opts?)`	`Promise<CsatTool>`	Obtiene una herramienta CSAT por id.
`update(id, body, opts?)`	`Promise<CsatTool>`	Actualiza (patch) una herramienta CSAT.
`delete(id, opts?)`	`Promise<DeletedResult>`	Elimina una herramienta CSAT por id.

cesTools

Gestiona las definiciones de herramientas CES (/v1/ces-tools).

Método	Retorno	Descripción
`list(params?, opts?)`	`Promise<Page<CesTool>>`	Lista las definiciones CES, paginado.
`create(body, opts?)`	`Promise<CesTool>`	Crea una definición CES (POST idempotente).
`get(id, opts?)`	`Promise<CesTool>`	Obtiene una herramienta CES por id.
`update(id, body, opts?)`	`Promise<CesTool>`	Actualiza (patch) una herramienta CES.
`delete(id, opts?)`	`Promise<DeletedResult>`	Elimina una herramienta CES por id.

wokus

Gestiona los wokus (herramientas de captura) (/v1/wokus): reseñas, settings, mover de carpeta, invitaciones y compartir.

Método	Retorno	Descripción
`list(params?, opts?)`	`Promise<Page<WokuResource>>`	Lista los wokus de la empresa, paginado.
`create(body, opts?)`	`Promise<WokuResource>`	Crea un woku.
`get(id, opts?)`	`Promise<WokuResource>`	Obtiene un woku con sus stats de reseñas.
`update(id, body, opts?)`	`Promise<WokuResource>`	Actualiza (patch) los campos de un woku.
`delete(id, opts?)`	`Promise<DeletedResult>`	Elimina un woku.
`updateSettings(id, body, opts?)`	`Promise<WokuResource>`	Aplica los settings booleanos del woku (idempotente).
`move(id, body, opts?)`	`Promise<WokuResource>`	Mueve el woku a una carpeta, o a la raiz con folderId null.
`listReviews(id, params?, opts?)`	`Promise<Page<WokuRecord>>`	Lista las reseñas de un woku, paginado.
`sendInvitations(id, body, opts?)`	`Promise<InvitationsResult>`	Envia una invitacion de reseña por correo o WhatsApp (idempotente).
`share(id, body, opts?)`	`Promise<WokuRecord>`	Comparte el link de reseña de un woku por correo.

Recursos

trackers, npsTools / csatTools / cesTools, nps / csat / ces, wokus, forms, flows, actionPlans, actionPlanGroups, tickets, ticketDestinations, dispatches, reports, company, quarantines.

Versionado

Estas mejoras se preparan para el próximo release. Consulta el changelog del paquete npm/PyPI para conocer la versión publicada antes de usar los métodos nuevos.

Recursos

Paquete npm: @wokuapp/sdk
Código y ejemplos: github.com/wokuApp/sdks
SDK de Python equivalente: SDK de Python
Referencia de la API: Guía de Integración API

Viajes y media local

El SDK de servidor expone las 17 operaciones de Viajes y un iterador de evaluaciones. Los uploads usan multipart y una respuesta generada del OpenAPI; 413 produce PayloadTooLargeError. La clave de compañía permanece en tu backend.

const media = await woku.media.upload({
  file: new Uint8Array(imageBytes), filename: 'delivery.jpg', contentType: 'image/jpeg',
});
// media.fileId -> moment.toolSpec.fileId
for await (const entry of woku.journeys.iterEnrollments(journeyId, { limit: 50 })) {
  console.log(entry.id, entry.lifecycle);
}

journeys

Cada método también acepta opciones por llamada como último argumento.

Método	API v1
`list`	`GET /v1/journeys`
`get(id)`	`GET /v1/journeys/{id}`
`create(body)`	`POST /v1/journeys`
`update(id, body)`	`PATCH /v1/journeys/{id}`
`delete(id)`	`DELETE /v1/journeys/{id}`
`rotateWebhookSecret(id)`	`POST /v1/journeys/{id}/webhook-secret`
`enroll(id, body)`	`POST /v1/journeys/{id}/enrollments`
`listEnrollments(id, params)`	`GET /v1/journeys/{id}/enrollments`
`getEnrollment(id, enrollmentId)`	`GET /v1/journeys/{id}/enrollments/{enrollmentId}`
`stopEnrollment(id, enrollmentId, body)`	`POST /v1/journeys/{id}/enrollments/{enrollmentId}/stop`
`connections(id)`	`GET /v1/journeys/{id}/connections`
`mintMomentUrl(id, stageKey)`	`POST /v1/journeys/{id}/moments/{stageKey}/url-token`
`setSenderSecret(id, stageKey, secret)`	`POST /v1/journeys/{id}/moments/{stageKey}/sender-secret`
`previewMoment(id, stageKey, payload)`	`POST /v1/journeys/{id}/moments/{stageKey}/preview`
`emitEvent(body)`	`POST /v1/journey-events`
`entryInfo(id)`	`GET /v1/journey-entries/{journeyId}`
`prepareEntry(id, body)`	`POST /v1/journey-entries/{journeyId}`

Los listados de evaluaciones devuelven { items, nextCursor }, con un límite máximo de 100 y default de 20. El endpoint separado de la tabla de Admin usa páginas de hasta 50. iterEnrollments(id, params, options) recorre las páginas por cursor bajo demanda.

Gestión (servidor)

Captura (cliente)

SDK de JavaScript

Instalación

Inicialización

Autenticación

Rotar o revocar la clave

Quickstart

Flujos principales

Herramientas VoC

Tickets de soporte

Planes de acción

Paginación

Idempotencia

Manejo de errores

Configuración por llamada

Referencia

actionPlans

actionPlanGroups

company

dispatches

flows

forms

quarantines

reports

nps

csat

ces

tickets

ticketDestinations

trackers

npsTools

csatTools

cesTools

wokus

Recursos

Versionado

Recursos

Viajes y media local

journeys

​Instalación

​Inicialización

​Autenticación

​Rotar o revocar la clave

​Quickstart

​Flujos principales

​Herramientas VoC

​Tickets de soporte

​Planes de acción

​Paginación

​Idempotencia

​Manejo de errores

​Configuración por llamada

​Referencia

​actionPlans

​actionPlanGroups

​company

​dispatches

​flows

​forms

​quarantines

​reports

​nps

​csat

​ces

​tickets

​ticketDestinations

​trackers

​npsTools

​csatTools

​cesTools

​wokus

​Recursos

​Versionado

​Recursos

​Viajes y media local

​journeys

Instalación

Inicialización

Autenticación

Rotar o revocar la clave

Quickstart

Flujos principales

Herramientas VoC

Tickets de soporte

Planes de acción

Paginación

Idempotencia

Manejo de errores

Configuración por llamada

Referencia

actionPlans

actionPlanGroups

company

dispatches

flows

forms

quarantines

reports

nps

csat

ces

tickets

ticketDestinations

trackers

npsTools

csatTools

cesTools

wokus

Recursos

Versionado

Recursos

Viajes y media local

journeys