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 paquete woku es el cliente oficial de servidor para la API de gestion de woku en Python. Con un cliente síncrono (Woku) y su gemelo asíncrono (AsyncWoku) sobre httpx 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 la contraparte del SDK de JavaScript, con la misma superficie.

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

pip install woku

Requiere Python 3.9 o superior. El SDK trae py.typed, asi que los type checkers reconocen sus tipos sin configuración extra.

Inicialización

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

from woku import Woku

woku = Woku(api_key="sk_...")  # o define WOKU_API_KEY y llama Woku()

Si omites api_key, el SDK lee la variable de entorno WOKU_API_KEY.

Opción	Requerida	Descripción
`api_key`	sí	Clave secreta de compañía. Por defecto la variable `WOKU_API_KEY`.
`base_url`	no	URL base de la API. Por defecto `https://clientapi.woku.app`.
`timeout`	no	Tiempo máximo por solicitud en segundos. Por defecto `60.0`.
`max_retries`	no	Reintentos automáticos ante fallos transitorios. Por defecto `2`.

Los cuerpos de solicitud aceptan un diccionario simple (como en los ejemplos) o un modelo Pydantic generado desde woku._generated.models.

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.

Rotar o revocar la clave

Rotar genera una clave nueva e invalida de inmediato la anterior; guarda la que devuelve antes de continuar.

result = woku.company.rotate_key()
# guarda result["secretKey"] de forma segura; la clave anterior deja de funcionar

woku.company.revoke_key()  # deja la cuenta sin clave activa

Quickstart

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

from woku import Woku

woku = Woku(api_key="sk_...")

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

# 2. Crear una herramienta NPS.
tool = woku.nps_tools.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.
woku.trackers.assign_to_entity(
    "nps", tool["_id"], {"name": tracker["name"], "value": "TX-42"}
)

# 4. Enviarla por correo o WhatsApp.
woku.nps.send_invitations(
    {"channel": "email", "npsToolId": tool["_id"], "recipients": ["ana@example.com"]}
)

# 5. Leer la entrega y la tasa de respuesta.
stats = woku.dispatches.stats({"channel": "email"})
print(stats["responseRate"])

Cliente asíncrono

AsyncWoku expone los mismos recursos con métodos await e iteración con async for. Úsalo como context manager para cerrar el pool de conexiones.

import asyncio
from woku import AsyncWoku


async def main() -> None:
    async with AsyncWoku(api_key="sk_...") as woku:
        async for ticket in await woku.tickets.list({"severity": "high"}):
            print(ticket["title"])


asyncio.run(main())

Flujos principales

Tickets de soporte

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

for ticket in woku.tickets.list({"severity": "high"}):
    print(ticket["title"])

stats = 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.

woku.action_plans.approve("plan_123")

# Leer el detalle y la línea de tiempo del plan.
plan = woku.action_plans.get("plan_123")
events = woku.action_plans.events("plan_123")

# Cerrar o reabrir el plan.
woku.action_plans.complete("plan_123")

Paginación

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

for ticket in woku.tickets.list({"severity": "high"}):
    print(ticket["title"])

first = woku.dispatches.list({"channel": "whatsapp"})
if first.has_next_page():
    second = first.get_next_page()

En el cliente asíncrono se recorre con async for.

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 request_id del servidor:

from woku import NotFoundError, RateLimitError

try:
    woku.tickets.get("inexistente")
except NotFoundError as err:
    print(err.status, err.request_id)  # 404, "req_..."
except RateLimitError as err:
    print("reintenta en", err.retry_after_seconds)

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 el argumento options:

woku.tickets.list({"severity": "high"}, options={"timeout": 10.0, "max_retries": 0})
woku.nps_tools.create(body, options={"idempotency_key": "mi-clave"})

Referencia

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

action_plans

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=None, options=None)`	`SyncPage[WokuRecord] (AsyncPage[WokuRecord] on the async client; both auto-paginate on iteration)`	Lista los planes de acción, con filtros opcionales y paginación.
`get(plan_id, options=None)`	`WokuRecord`	Obtiene un plan de acción por id.
`events(plan_id, options=None)`	`list[WokuRecord]`	Devuelve la línea de tiempo del plan (eventos, más antiguos primero).
`get_conversation(plan_id, options=None)`	`WokuRecord`	Devuelve la conversación IA del plan (solo lectura).
`reply(plan_id, text, options=None)`	`WokuRecord`	Responde al agente IA del plan (turno pago, compuesto de forma asincrónica).
`create_task(plan_id, body, options=None)`	`WokuRecord`	Crea una tarea en el plan.
`update_task(plan_id, task_id, body, options=None)`	`WokuRecord`	Actualiza una tarea del plan.
`reorder_tasks(plan_id, body, options=None)`	`WokuRecord`	Reordena las tareas del plan.
`delete_task(plan_id, task_id, options=None)`	`WokuRecord`	Elimina una tarea del plan.
`approve(plan_id, options=None)`	`WokuRecord`	Aprueba el plan.
`reopen(plan_id, options=None)`	`WokuRecord`	Reabre el plan.
`cancel(plan_id, options=None)`	`WokuRecord`	Cancela el plan.
`complete(plan_id, options=None)`	`WokuRecord`	Marca el plan como completado.
`resume(plan_id, options=None)`	`WokuRecord`	Reanuda el plan.

action_plan_groups

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=None, options=None)`	`list[WokuRecord]`	Lista los grupos, con busqueda opcional.
`get(group_id, options=None)`	`WokuRecord`	Obtiene un grupo con sus stats embebidas.
`create(body, options=None)`	`WokuRecord`	Crea un grupo.
`update(group_id, body, options=None)`	`WokuRecord`	Actualiza un grupo.
`set_enabled(group_id, enabled, options=None)`	`WokuRecord`	Habilita o deshabilita el grupo.
`delete(group_id, options=None)`	`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(options=None)`	`WokuRecord`	Obtiene la empresa que hace la llamada.
`rotate_key(options=None)`	`ApiKeyResult`	Rota la clave secreta y devuelve la nueva (invalida la anterior).
`revoke_key(options=None)`	`WokuRecord`	Revoca la clave secreta.

dispatches

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

Método	Retorno	Descripción
`list(params=None, options=None)`	`SyncPage[Dispatch] (AsyncPage[Dispatch] on the async client)`	Lista los envios con estado de entrega, sin PII.
`stats(params=None, options=None)`	`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=None, options=None)`	`SyncPage[WokuRecord] (AsyncFlows: AsyncPage[WokuRecord])`	Lista los flujos de encuestas, paginado.
`get(flow_id, options=None)`	`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=None, options=None)`	`SyncPage[WokuRecord] (AsyncPage[WokuRecord] on AsyncForms)`	Lista los formularios, paginado.
`get(form_id, options=None)`	`WokuRecord`	Obtiene un formulario por id.
`list_responses(form_id, params=None, options=None)`	`SyncPage[WokuRecord] (AsyncPage[WokuRecord] on AsyncForms)`	Lista las respuestas de un formulario, paginado.
`send_invitations(form_id, body, options=None)`	`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, options=None)`	`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
`company_nps(params=None, options=None)`	`WokuRecord`	Obtiene el reporte NPS a nivel empresa.
`nps_tool(nps_tool_id, params=None, options=None)`	`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
`send_invitations(body, options=None)`	`InvitationsResult`	Envia la encuesta NPS por correo o WhatsApp (idempotente).
`list_responses(params=None, options=None)`	`SyncPage[WokuRecord] (AsyncPage[WokuRecord] on the async client)`	Lista las respuestas NPS, paginado.
`get_response(response_id, options=None)`	`WokuRecord`	Obtiene una respuesta NPS por id.

csat

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

Método	Retorno	Descripción
`send_invitations(body, options=None)`	`InvitationsResult`	Envia las invitaciones CSAT (idempotente).
`list_responses(params=None, options=None)`	`SyncPage[WokuRecord] (AsyncPage[WokuRecord] on the async client)`	Lista las respuestas CSAT, paginado.
`get_response(response_id, options=None)`	`WokuRecord`	Obtiene una respuesta CSAT por id.

ces

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

Método	Retorno	Descripción
`send_invitations(body, options=None)`	`InvitationsResult`	Envia las invitaciones CES (idempotente).
`list_responses(params=None, options=None)`	`SyncPage[WokuRecord] (AsyncPage[WokuRecord] on the async client)`	Lista las respuestas CES, paginado.
`get_response(response_id, options=None)`	`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=None, options=None)`	`SyncPage[Ticket] (AsyncPage[Ticket] on the async client; both support pagination iteration)`	Lista los tickets con filtros opcionales.
`stats(params=None, options=None)`	`TicketStats`	Devuelve conteos agregados por herramienta y por destino.
`get(ticket_id, options=None)`	`Ticket`	Obtiene un ticket por id.
`update(ticket_id, body, options=None)`	`Ticket`	Actualiza (patch) un ticket.

ticket_destinations

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

Método	Retorno	Descripción
`list(options=None)`	`builtins.list[WokuRecord]`	Lista todos los destinos configurados.
`get(destination_id, options=None)`	`WokuRecord`	Obtiene un destino por id.
`create(body, options=None)`	`WokuRecord`	Crea un destino.
`update(destination_id, body, options=None)`	`WokuRecord`	Actualiza (patch) un destino.
`delete(destination_id, options=None)`	`WokuRecord`	Elimina un destino.
`test(destination_id, options=None)`	`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=None, options=None)`	`SyncPage[Tracker] (AsyncPage[Tracker] on the async client)`	Lista las definiciones de tracker, paginado.
`create(body, options=None)`	`Tracker`	Crea una definición de tracker (idempotente).
`get(tracker_id, options=None)`	`Tracker`	Obtiene una definición de tracker por id.
`update(tracker_id, body, options=None)`	`Tracker`	Actualiza una definición de tracker.
`activate(tracker_id, options=None)`	`Tracker`	Activa una definición de tracker.
`deactivate(tracker_id, options=None)`	`Tracker`	Desactiva una definición de tracker.
`search_entities(body, options=None)`	`EntitiesByTrackers`	Busca entidades VoC cuyos trackers cumplen todos los filtros (AND).
`list_woku_values(woku_id, options=None)`	`list[WokuRecord]`	Lista los valores de tracker asignados a un woku.
`assign_to_woku(woku_id, body, options=None)`	`WokuRecord`	Asigna (upsert) un valor de tracker a un woku por nombre (idempotente).
`remove_from_woku(woku_id, tracker_name, options=None)`	`WokuRecord`	Quita un valor de tracker de un woku por nombre.
`search_wokus(params, options=None)`	`SyncPage[WokuRecord] (AsyncPage[WokuRecord] on the async client)`	Busca wokus por un par exacto (nombre de tracker, valor), paginado.
`list_entity_values(entity_type, entity_id, options=None)`	`list[WokuRecord]`	Lista los valores de tracker de una entidad VoC (nps/csat/ces/form/flow).
`assign_to_entity(entity_type, entity_id, body, options=None)`	`WokuRecord`	Asigna (upsert) un valor de tracker a una entidad VoC por nombre (idempotente).
`remove_from_entity(entity_type, entity_id, tracker_name, options=None)`	`WokuRecord`	Quita un valor de tracker de una entidad VoC por nombre.

nps_tools

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

Método	Retorno	Descripción
`list(params=None, options=None)`	`SyncPage[NpsTool] (AsyncPage[NpsTool] on the async client)`	Lista las definiciones NPS, paginado.
`create(body, options=None)`	`NpsTool`	Crea una definición NPS (POST idempotente).
`get(tool_id, options=None)`	`NpsTool`	Obtiene una herramienta NPS por id.
`update(tool_id, body, options=None)`	`NpsTool`	Actualiza (patch) una herramienta NPS.
`delete(tool_id, options=None)`	`DeletedResult`	Elimina una herramienta NPS por id.

csat_tools

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

Método	Retorno	Descripción
`list(params=None, options=None)`	`SyncPage[CsatTool] (AsyncPage[CsatTool] on the async client)`	Lista las definiciones CSAT, paginado.
`create(body, options=None)`	`CsatTool`	Crea una definición CSAT (POST idempotente).
`get(tool_id, options=None)`	`CsatTool`	Obtiene una herramienta CSAT por id.
`update(tool_id, body, options=None)`	`CsatTool`	Actualiza (patch) una herramienta CSAT.
`delete(tool_id, options=None)`	`DeletedResult`	Elimina una herramienta CSAT por id.

ces_tools

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

Método	Retorno	Descripción
`list(params=None, options=None)`	`SyncPage[CesTool] (AsyncPage[CesTool] on the async client)`	Lista las definiciones CES, paginado.
`create(body, options=None)`	`CesTool`	Crea una definición CES (POST idempotente).
`get(tool_id, options=None)`	`CesTool`	Obtiene una herramienta CES por id.
`update(tool_id, body, options=None)`	`CesTool`	Actualiza (patch) una herramienta CES.
`delete(tool_id, options=None)`	`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=None, options=None)`	`SyncPage[Woku] (async AsyncPage[Woku]); pages are async-iterable`	Lista los wokus de la empresa, paginado.
`create(body, options=None)`	`Woku`	Crea un woku.
`get(woku_id, options=None)`	`Woku`	Obtiene un woku con sus stats de reseñas.
`update(woku_id, body, options=None)`	`Woku`	Actualiza (patch) los campos de un woku.
`delete(woku_id, options=None)`	`DeletedResult`	Elimina un woku.
`update_settings(woku_id, body, options=None)`	`Woku`	Aplica los settings booleanos del woku (idempotente).
`move(woku_id, body, options=None)`	`Woku`	Mueve el woku a una carpeta, o a la raiz con folderId null.
`list_reviews(woku_id, params=None, options=None)`	`SyncPage[WokuRecord] (async AsyncPage[WokuRecord]); pages are async-iterable`	Lista las reseñas de un woku, paginado.
`send_invitations(woku_id, body, options=None)`	`InvitationsResult`	Envia una invitacion de reseña por correo o WhatsApp (idempotente).
`share(woku_id, body, options=None)`	`WokuRecord`	Comparte el link de reseña de un woku por correo.

Recursos

trackers, nps_tools / csat_tools / ces_tools, nps / csat / ces, wokus, forms, flows, action_plans, action_plan_groups, tickets, ticket_destinations, 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 PyPI: woku
Código y ejemplos: github.com/wokuApp/woku-python
SDK de JavaScript equivalente: SDK de JavaScript
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.

with open("delivery.jpg", "rb") as image:
    media = woku.media.upload(image, filename="delivery.jpg", content_type="image/jpeg")
# media["fileId"] -> moment.toolSpec.fileId
for entry in woku.journeys.iter_enrollments(journey_id, {"limit": 50}):
    print(entry["id"], entry["lifecycle"])

AsyncWoku también admite await media.upload y async for con journeys.iter_enrollments. El caller es responsable de cerrar el archivo.

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}`
`rotate_webhook_secret(id)`	`POST /v1/journeys/{id}/webhook-secret`
`enroll(id, body)`	`POST /v1/journeys/{id}/enrollments`
`list_enrollments(id, params)`	`GET /v1/journeys/{id}/enrollments`
`get_enrollment(id, enrollment_id)`	`GET /v1/journeys/{id}/enrollments/{enrollmentId}`
`stop_enrollment(id, enrollment_id, body)`	`POST /v1/journeys/{id}/enrollments/{enrollmentId}/stop`
`connections(id)`	`GET /v1/journeys/{id}/connections`
`mint_moment_url(id, stage_key)`	`POST /v1/journeys/{id}/moments/{stageKey}/url-token`
`set_sender_secret(id, stage_key, secret)`	`POST /v1/journeys/{id}/moments/{stageKey}/sender-secret`
`preview_moment(id, stage_key, payload)`	`POST /v1/journeys/{id}/moments/{stageKey}/preview`
`emit_event(body)`	`POST /v1/journey-events`
`entry_info(id)`	`GET /v1/journey-entries/{journeyId}`
`prepare_entry(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. iter_enrollments(id, params, options) recorre las páginas por cursor bajo demanda.

Gestión (servidor)

Captura (cliente)

SDK de Python

Instalación

Inicialización

Autenticación

Rotar o revocar la clave

Quickstart

Cliente asíncrono

Flujos principales

Tickets de soporte

Planes de acción

Paginación

Idempotencia

Manejo de errores

Configuración por llamada

Referencia

action_plans

action_plan_groups

company

dispatches

flows

forms

quarantines

reports

nps

csat

ces

tickets

ticket_destinations

trackers

nps_tools

csat_tools

ces_tools

wokus

Recursos

Versionado

Recursos

Viajes y media local

journeys

​Instalación

​Inicialización

​Autenticación

​Rotar o revocar la clave

​Quickstart

​Cliente asíncrono

​Flujos principales

​Tickets de soporte

​Planes de acción

​Paginación

​Idempotencia

​Manejo de errores

​Configuración por llamada

​Referencia

​action_plans

​action_plan_groups

​company

​dispatches

​flows

​forms

​quarantines

​reports

​nps

​csat

​ces

​tickets

​ticket_destinations

​trackers

​nps_tools

​csat_tools

​ces_tools

​wokus

​Recursos

​Versionado

​Recursos

​Viajes y media local

​journeys

Instalación

Inicialización

Autenticación

Rotar o revocar la clave

Quickstart

Cliente asíncrono

Flujos principales

Tickets de soporte

Planes de acción

Paginación

Idempotencia

Manejo de errores

Configuración por llamada

Referencia

action_plans

action_plan_groups

company

dispatches

flows

forms

quarantines

reports

nps

csat

ces

tickets

ticket_destinations

trackers

nps_tools

csat_tools

ces_tools

wokus

Recursos

Versionado

Recursos

Viajes y media local

journeys