> ## Documentation Index
> Fetch the complete documentation index at: https://woku.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Viajes del cliente

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

En el inicio por respuesta, comparte el acceso mediante un **QR, una etiqueta de producto, WhatsApp o cualquier otro enlace**. El medio no cambia la regla. Compartir, escanear, abrir el enlace o completar los datos de contacto no inicia el recorrido. 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.

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