Documentación de woku - Guía para desarrolladores

Disponible en el plan Corporate. Esta funcionalidad forma parte de las capacidades empresariales de woku. Conversa con nuestro equipo comercial.

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, 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 y enviarla por correo o WhatsApp.
const tool = await woku.npsTools.create({
  name: 'Post-compra',
  npsMessage: '¿Qué tan probable es que nos recomiendes?',
});
await woku.nps.sendInvitations({
  channel: 'email',
  npsToolId: tool._id,
  recipients: ['ana@example.com'],
});

// 3. 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 planes, envíalos a una herramienta externa o gestiónalos dentro de woku.

await woku.actionPlans.approve('plan_123');
await woku.actionPlans.send('plan_123', {
  provider: 'jira',
  target: { projectId: '10032', issueTypeId: '10001' },
});

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 create incluyen automáticamente una Idempotency-Key, asi que un reintento tras un fallo transitorio nunca crea dos veces. Las acciones (enviar, probar, responder) no se reintentan solas para no repetir un efecto. Puedes pasar tu propia clave por llamada:

await woku.npsTools.create(body, { idempotencyKey: 'mi-clave' });

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

Recursos

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

Versionado

El SDK sigue versionado semántico (MAJOR.MINOR.PATCH). La versión actual publicada es la 0.1.0. Te recomendamos fijar un rango compatible (por ejemplo ^0.1.0) y revisar el changelog antes de subir de versión MAJOR. Las versiones y sus notas están en el paquete npm y en los releases de GitHub.

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

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

Recursos

Versionado

Recursos

​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

​Recursos

​Versionado

​Recursos

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

Recursos

Versionado

Recursos