/v1. Las URLs entrantes las devuelve la configuración del momento; usa esas URLs como destinos del emisor.
1. Preparar media y credenciales
fileId, filename y type. Guarda el fileId como WOKU_FILE_ID. La clave secreta y el secreto del emisor pertenecen a la configuración del servidor.
2. Crear cuatro momentos
Guarda el siguiente código enjourney.mjs. Crea un viaje apagado y configura dos URLs con token generado por woku y dos momentos con firma del emisor. Puedes generar una URL para cada momento aunque normalmente avance por espera.
Ejecuta node journey.mjs para crear y revisar el borrador. El ejemplo deja tickets y planes apagados; en un programa real puedes habilitar cada acción por separado con recipients.ticketsEnabled y recipients.plansEnabled. Tickets usan ticketEmails; planes usan planMembers con usuarios de la empresa y roles admin o assignee. El creador permanece como administrador del grupo.
contentMode define de dónde sale el contenido, independientemente de trigger. JavaScript es un cuerpo de función que recibe payload y devuelve un string. No tiene imports, red ni acceso a archivos. El schema acotado valida el payload antes de ejecutar el contenido. Las rutas no admiten constructor, prototype ni __proto__.
La imagen dinámica de Woku debe ser una URL HTTPS pública. Si configuraste una espera secundaria y el webhook nunca llega, el momento usa su nombre, variables y media estáticos; por eso el ejemplo conserva toolSpec.fileId. Las carpetas se crean si no existen. Los nombres son opcionales y usan la clave cuando faltan, respetando los límites de nombres de carpeta.
3. Previsualizar y activar
Añade estos pasos al mismo archivo, después de la definición desendMoment. Reemplaza el email por una dirección de prueba autorizada.
200, interpreta el JavaScript con el payload enviado y muestra la pregunta compuesta de CSAT/CES/NPS cuando corresponde y no inscribe ni envía. Cambia deliveryMode para probar otra rama. No verifica firmas: compruébalas enviando un evento real después de activar.
En un viaje nuevo v2, cada momento tiene un envío inicial y un recordatorio al día siguiente por defecto. El ejemplo lo declara explícitamente en sequence. Una espera de cero días significa una hora. Puedes cambiar los intentos y ventanas; las definiciones anteriores conservan sus valores.
4. Enviar eventos con una referencia estable
SiSTART_MODE=operator, inscribe el caso y después emite sus confirmaciones:
START_MODE=webhook, omite la inscripción. El webhook de Compra inicia el caso. En ambos recorridos, todos los emisores usan el mismo order.id; el email identifica al contacto, y la referencia enlaza los eventos del caso.
Un evento posterior puede llegar adelantado y esperar su condición anterior. El webhook adelanta un momento temporal y cancela su espera; un evento tardío no repite una herramienta que ya se envió. La exclusión de ejecución no depende solo de X-Woku-Event-Id.
No intercambies estos secretos. Las lecturas de conexión devuelven la URL sin credencial y su estado de configuración, nunca el token guardado ni el secreto del emisor.
5. Inicio por primera respuesta
Esta es una alternativa a la inscripción del paso 4. Ejecuta la configuración conSTART_MODE=response para un viaje nuevo o usa un caso nuevo antes de enviar sus eventos. El acceso por QR o enlace también está disponible en viajes v2 con inicio operator. Obtener o preparar la entrada no inicia el recorrido. No prepares otra entrada para un caso que ya está en curso.
dispatchToken; en Woku usa un comentario o audio identificado. Guarda la respuesta válida primero; esa respuesta confirma el inicio una sola vez. La entrada preparada aparece pendiente y no manda una nueva invitación a la primera herramienta.
6. Seguimiento, reintentos y detención
nextCursor aparece solo si hay otra página. Cada caso conserva su versión, historial y próximo paso. Editar el viaje crea una versión para casos futuros y conserva las credenciales separadas; una participación en curso usa su snapshot anterior.
El ciclo se completa al responder la última herramienta o 30 días desde su primer envío. Una inscripción manual puede reutilizar la misma clave cuando el ciclo previo haya completado o terminado su detención. Detener cancela esperas y recordatorios del caso exacto, conserva feedback y otros casos, y no retira entregas ya aceptadas por un proveedor.
En POST de administración que admiten
X-Woku-Idempotency-Key, usa una clave nueva para una operación nueva y conserva la anterior para sus reintentos. Reutilizarla con otro cuerpo reproduce la respuesta original; usarla en otra operación devuelve 422.
El mismo contrato en MCP y SDKs
En MCP, pidewoku_guide con topic=customer_journeys. create_journey y update_journey usan los mismos momentos avanzados, pero llaman cadence a sequence. Usa preview_journey_moment, get_journey_connections, mint_journey_moment_url y set_journey_sender_secret para conectar. Las mutaciones de credenciales y la detención requieren confirmación explícita; las escrituras necesitan mcp:write.
Los SDKs JavaScript y Python conservan la API /v1, tienen tipos generados de los momentos y no activan un viaje al crearlo. Consulta la referencia MCP y los conceptos del viaje.
Volver desde el mismo QR o enlace
Conserva requestId mientras preparas o reintentas la misma primera herramienta. Si la API devuelve HTTP 409 con códigojourney_entry_closed, identificó un ciclo
completado o detenido. Para un nuevo ciclo sin referencia externa, vuelve a preparar
con un requestId nuevo. No renueves el ID por timeout, error de red ni conflicto
con una evaluación activa. Una referencia de compra explícita sigue identificando
ese mismo caso y debe cambiar para una compra distinta.