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

# Customer journeys

> Describe your customer experience, evaluate its moments, and automate follow-up with control over each customer case

A **customer journey** organizes when to listen to a person and what you want to understand at each moment. A **participation**, also called an enrollment in the API, evaluates one purchase or case. The same customer can have several independent participations.

## Create a journey from your business experience

In the admin, open **Voice of the customer > Customer journeys**. Start with three answers in your own words:

1. What experience your customer goes through.
2. Which moments happen and in what order.
3. What you want to understand at each moment.

**Propose my journey** interprets those answers with AI and proposes editable moments. This is a form: clarifications appear alongside its fields. Correct moments, reorder them, undo changes, or design them yourself. Drafts are saved separately from the definition that the engine executes.

Then review delays and whether the journey creates tickets, plans, or both. Enroll from the platform or share customer entry; configure initiation by another system in the first moment. Each action has its own section and can be turned off without completing its recipients. Review the proposal before saving. **Save and connect** leaves a new journey off. Connect its systems and activate it when the required resources are ready.

## Who starts the evaluation

Only the first moment determines how a journey starts.

| Initiation                   | What starts the participation                                     | First answer             |
| ---------------------------- | ----------------------------------------------------------------- | ------------------------ |
| From Woku (`operator`)       | A user adds a customer through the platform, API or MCP           | Not required to continue |
| Customer answer (`response`) | The customer's answer to the first tool is saved                  | Required to start        |
| External system (`webhook`)  | The first moment's webhook arrives with its reference and contact | Not required to continue |

In the admin, you can enroll with an email or phone number. A normalized email identifies the customer when present; without one, the normalized phone identifies them and the first invitation goes through WhatsApp. With manual enrollment, the same identifier can complete this journey more than once, but can have only one evaluation in progress at a time. API and MCP retain `subjectKey` for integrations that need a case reference distinct from the contact.

The cycle completes when the customer answers the final tool or 30 days after that tool's first send. You can then enroll the same customer again without asking for another key. Each cycle keeps its own history.

For response initiation, share the entry through a **QR code, product label, WhatsApp message, or any other link**. The channel does not change the rule. Sharing, scanning, opening the link, or completing contact details does not start the journey. The first tool is prepared in advance; its answer starts the journey once without sending that tool again.

Entry may request the purchase reference and contact needed for follow-up. Until the first answer exists, the participation shows **Waiting to start**.

## When later moments are evaluated

Later moments advance automatically. They cannot have another manual start.

* **Delay in days**: evaluate after the configured milestone of the previous moment. The suggested initial wait is 10 days. If you choose 0 days, Woku waits 1 hour before sending the next tool. The form uses the previous moment's send as its anchor; when the customer initiates by answering, the first delay starts from that answer.
* **Primary webhook**: wait for confirmation from the system that knows about that moment.
* **Optional webhook fallback**: if confirmation does not arrive, evaluate the same moment after the configured number of days. The delay needs a known participation and preceding milestone.

Every moment owns a connection, including moments normally driven by a delay. An earlier webhook **advances the evaluation and cancels the wait**. The timer and webhook do not produce two initial sends. If the fallback already acted, a late webhook does not repeat the send.

The fallback sends the moment's evaluation; it does not establish that a delivery or another business event occurred. Without a fallback, the moment keeps waiting for its webhook.

## Tools owned by each moment

Each moment creates a **Woku, CSAT, CES, or NPS** tool. Different moments never share a tool or receive an existing one.
In a new journey, the tool is reused by default among customers of that same moment. You can choose one tool per participation when the case requires it.

| Option                                        | Scope                                                                                         |
| --------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Shared within this moment (`shared`, default) | Reuses the tool only within that moment and configuration, preserving each case's correlation |
| One per participation (`per_enrollment`)      | Each purchase or case gets its own tool at that moment                                        |

CSAT evaluates satisfaction, CES ease, and NPS recommendation. `toolSpec.subject` supplies the experience, action, or company/product, not the whole question. NPS also uses `toolSpec.audience`. Variables support Spanish and English. Woku requires an uploaded image or video through `toolSpec.fileId` and uses the moment name as its title. `toolSpec.descriptionEn` sets its English title; if omitted, Woku retains its existing automatic translation.

New journeys use **one initial send and a reminder the following day by default**. You can change or disable the reminder for each moment. Earlier definitions retain their attempt configuration.

## Connect CRM, logistics, and other systems

For example, the CRM reports a purchase to the **Sale** URL, and logistics software reports delivery to the **Delivery** URL. Both must send **the same purchase or case reference**. Email identifies a contact but does not replace that reference: a person may have two simultaneous orders.

Configure each connection from its moment:

1. Choose a URL with an embedded credential, or the signature produced by the external system.
2. Set the reference, email, and phone paths when the payload uses another structure, such as `order.id`.
3. Save the connection and test reading with a sample. This test does not send tools, enroll customers, or verify the sender signature.
4. Generate and copy the URL into the corresponding system. A configured credential does not prove that a real call has arrived.

Generating another URL replaces that moment's previous credential. Sender secrets are encrypted and never returned. Renaming or reordering preserves moment keys and credentials.

The management API reads and configures connections:

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

Use the URL returned by generation as the sending system's destination. A payload in the default shape is:

```json theme={null}
{
  "subjectKey": "order-123",
  "contact": { "email": "customer@example.com" }
}
```

Later moments can send only the reference when contact information is already known. Include a stable `X-Woku-Event-Id` when retrying the same event.

A later moment's signal that arrives before initiation is retained until its conditions are met. Woku does not merge different references or guess that two orders are the same because they share an email.

## Tickets and plans

The form separates two destinations: **ticket emails** and a **plan group made of company users**. The creator's email is included by default for tickets. In the group, the creator remains an administrator and you can add other Woku users as assignees. Focusing the search shows five users; typing filters the rest. Selected users appear below with their avatars.

You can turn **Create tickets** or **Create plans** off independently, including both. A disabled action produces no new tickets or plans and does not require completed recipients. Your choices and entered values remain available for reactivation. In the API, use `recipients.ticketsEnabled` and `recipients.plansEnabled`; omitting them keeps both actions enabled for compatibility.

Woku provisions the journey's support destination, plan group, and trackers. Signals are scoped to that journey. Tickets follow signal rules; plans are generated when the group's threshold is reached. Every answer does not generate a ticket, and every completed evaluation does not generate a plan.

For v2 journeys, the **`Viaje`** tracker value is a stable identity: the journey's readable immutable key as a slug, followed by its full ID. Journeys with the same name have different values, and renaming one does not change its identity. **`ID del viaje`** keeps the raw ID for internal routing.

Only existing company users can belong to the plan group. The group defines membership and permissions; external email addresses are not accepted as plan destinations.

If a valid destination or group is missing, activation shows the incomplete setup. Resource-owning modules retain their settings; saving a journey without changing recipients must not overwrite edits made there.

## Follow and stop one case

The journey view lists participations by reference, contact, state, version, and next step. History distinguishes prepared tools, sends, and answers based on available evidence. Shared tool results include their different participations.

**Stop evaluation** applies to the selected case:

* Shows the names of moments that have not yet been sent.
* Records who requested it, when, and an optional reason.
* Cancels that participation's pending waits and reminders.
* Blocks subsequent activation from webhooks, timers, or late answers.
* Preserves answers, history, shared tools, tickets, and plans.
* Leaves the customer's other participations running.

A delivery already accepted by the provider cannot be recalled. **Stopping** indicates work in progress; the request can be retried. If a process is interrupted during an in-flight send, an uncertain delivery may require review. Stopped cases have no resume action.
You can create a new evaluation for that customer after stopping finishes.

The API uses the exact enrollment identifier:

```text theme={null}
GET /v1/journeys/{id}/enrollments?limit=20
GET /v1/journeys/{id}/enrollments/{enrollmentId}
POST /v1/journeys/{id}/enrollments/{enrollmentId}/stop
```

The list returns `items` and, when more exist, `nextCursor`. Pass that value as `cursor` to continue. Stop accepts `{"reason":"Purchase cancelled"}` and an idempotency key. Switching off the whole journey is a separate operation from stopping one participation.

## Versions and compatibility

The new API definition declares `authoringVersion: 2`, `startMode`, `moments`, and `recipients`. The admin uses the new form for these journeys. Earlier contracts retain their editor and rules, including their events and snapshots. Create a new journey to adopt v2; changing an existing definition's contract number is rejected.

Behavioral configuration changes create a new version for future participations. Those already started keep their configuration. Connection credentials and payload mappings, together with the definition's switch are shared operational settings, not a way to restart a stopped case.

## API, SDKs, and MCP

The management API and SDKs use the company's secret key. Public customer entry is separate: `GET` and `POST /v1/journey-entries/{journeyId}` prepare access; only a valid saved answer confirms initiation.

SDKs support listing, reading, stopping, and connection configuration. MCP provides `create_journey`, `update_journey`, `list_journey_evaluations`, `get_journey_evaluation`, and `stop_journey_evaluation`, alongside connection tools. Operations that stop an evaluation or replace credentials require explicit confirmation.

To start without authoring the full definition, the agent can call `woku_guide` with `topic=customer_journeys`, propose moments with `propose_journey`, and save a disabled journey with `create_journey_from_brief` after your confirmation. `upload_woku_media` imports the image or MP4 video and `set_journey_moment_media` attaches it to the relevant Woku moment. [See the upload paths for each agent](/docs/en/mcp/tools#create-a-woku-or-journey-with-media).

Configure advanced webhook content, localized variables, customer fields, image URL paths, folders and trackers in the [four-moment integration guide](/docs/en/development/journey-integration). Manual content and webhook content are independent of timing; dynamic content creates an instrument per participation.