Objeto Journey

Los métodos de ciclo de vida, crear y actualizar devuelven un objeto journey con la misma forma de nivel superior:

Forma

{
  "info": { ... },        // metadatos de solo lectura (solo respuestas)
  "params": { ... },      // configuración para todo el journey (crear / actualizar)
  "points": [ ... ],      // nodos del canvas y sus conexiones
  "comments": [ ... ]     // comentarios del canvas
}

Cuando crea o actualiza un journey, envía title, params, points y comments. Las respuestas devuelven info (que contiene params) más points y comments.

Info

Metadatos del journey de solo lectura. Devueltos por cada método v3. No forma parte del cuerpo de la solicitud.

Campo	Tipo	Descripción
uuid	string	ID de Journey.
title	string	Nombre del Journey.
status	JourneyStatus	Estado actual.
created_at	string	Marca de tiempo de creación (ISO 8601).
updated_at	string	Marca de tiempo de la última actualización (ISO 8601).
is_first_activated	bool	Si el journey se ha iniciado al menos una vez.
params	JourneyParams	Configuración para todo el journey.
category_uuid	string	UUID de la categoría, o vacío si no está categorizado.
pointCounts	map<string, uint32>	Recuento de puntos por tipo.
campaign_type	CampaignType	Cómo los usuarios entran en el journey.
stop_reason	string	Por qué se detuvo el journey, si corresponde.
last_edited_by	User	Usuario que editó por última vez el journey.
dynamic_entry	bool	Si la entrada dinámica está habilitada.

JourneyParams

Configuración para todo el journey. Se envía al crear/actualizar y se devuelve dentro de info.params.

Campo	Tipo	Descripción
application_code	string	Código de aplicación al que pertenece el journey. Requerido al crear.
silent_hours	SilentHours	Horas durante las cuales se suprimen los mensajes, por canal.
capping	EntryCapping	Límites sobre la frecuencia con la que un usuario puede volver a entrar en el journey.
conversion_window	ConversionWindow	Ventana para atribuir conversiones de objetivos.
user_id_track_change_policy	UserIDTrackChangePolicy	Cómo manejar el cambio de ID de un usuario a mitad del journey.

SilentHours

Suprime el envío durante las horas de silencio. Configurado por canal: cada canal toma sus propios SilentHoursParams:

Campo	Tipo	Descripción
push_params	SilentHoursParams	Horas de silencio para notificaciones push.
inapp_params	SilentHoursParams	Horas de silencio para mensajes in-app.
email_params	SilentHoursParams	Horas de silencio para correos electrónicos.
sms_params	SilentHoursParams	Horas de silencio para SMS.
whatsapp_params	SilentHoursParams	Horas de silencio para WhatsApp.
line_params	SilentHoursParams	Horas de silencio para LINE.

Cada SilentHoursParams es:

Campo	Tipo	Descripción
enabled	bool	Si las horas de silencio se aplican a este canal.
from_time	Time	Inicio de la ventana de silencio: { "hour": 0–23, "minute": 0–59 }.
to_time	Time	Fin de la ventana de silencio.
week_days	bool[]	Siete booleanos para los días en que se aplica la ventana (lunes = índice 0).
behavior	enum	Qué hacer cuando un mensaje cae dentro de las horas de silencio: WaitAndSend (retener y luego enviar cuando termine la ventana), DropAndGo (omitir el mensaje, continuar el journey inmediatamente) o WaitAndDrop (esperar a que termine la ventana y luego continuar sin enviar).

EntryCapping

Limita la frecuencia con la que el mismo usuario puede entrar en el journey.

Campo	Tipo	Descripción
is_enabled	bool	Si el límite de entrada está activado.
period	uint64	Número mínimo de minutos entre las entradas de un usuario. 0 significa que el usuario puede entrar solo una vez en la vida.

El límite se cuenta desde el momento en que el usuario entró en el journey, y se rastrea por ID de usuario, por lo que todos los dispositivos de un usuario comparten una única entrada. Mientras dura el período, el punto de entrada rechaza más intentos de entrada y los cuenta como errores en lugar de crear un viajero.

Tres comportamientos a tener en cuenta cuando cambie esta configuración:

• Salir del journey antes de tiempo no libera el límite. El usuario espera el período completo incluso después de alcanzar un punto de salida.
• Un period modificado se aplica a las entradas realizadas después de la actualización. Los usuarios que entraron antes mantienen el período que estaba en vigor cuando entraron.
• Establecer is_enabled en false levanta el límite para todos los usuarios inmediatamente.

Nota

El Panel de Control escribe el mismo campo desde el límite de entrada de la Campaña, que ofrece 0 (una vez en la vida), 1440 (una vez al día), 10080 (una vez a la semana), 43800 (una vez al mes) y 131500 (una vez cada tres meses).

ConversionWindow

Campo	Tipo	Descripción
seconds	uint64	Cuánto tiempo después de entrar en un journey la finalización de un objetivo por parte de un usuario todavía cuenta como una conversión.

Point

Un punto es un nodo en el canvas del journey: un punto de entrada, un mensaje, un retraso, un divisor, etc.

Campo	Tipo	Descripción
uuid	string	ID único del punto dentro del journey. Debe ser un UUID canónico RFC 4122: 32 dígitos hexadecimales en grupos de 8-4-4-4-12.
title	string	Nombre para mostrar del punto.
point_type	PointType	El tipo de nodo.
outputs	array of PointOutput	Conexiones a puntos posteriores.
position	Position	Coordenadas del canvas.
point_data	object	Exactamente una clave anidada, que coincide con point_type (consulte la tabla de tipos de puntos).

Nota

Todos los UUID (info.uuid, cada uuid de punto y el next_point_uuid de cada salida) deben ser UUID canónicos RFC 4122 (grupos hexadecimales 8-4-4-4-12).

PointOutput

Las salidas de un punto son sus ramas salientes. Sus claves no son de formato libre. El validador espera un conjunto exacto de claves para cada tipo de punto, y rechaza un journey cuyo punto tenga un número incorrecto de salidas o una clave que no reconoce.

Campo	Tipo	Descripción
identity.key	string	Clave de la rama. Debe seguir las reglas de claves de salida a continuación.
identity.order	int	Orden de visualización de la rama.
info.title	string	Etiqueta de rama opcional.
info.next_point_uuid	string	UUID del siguiente punto al que se conecta esta rama. Opcional: dejarlo sin establecer finaliza el journey para el usuario, igual que un punto terminador explícito.

Claves de salida

La rama predeterminada (primera) siempre se llama "default". Las ramas adicionales se nombran "output1", "output2", … (el prefijo output seguido de un índice basado en 1). Dos tipos de puntos rompen esta regla, como se indica a continuación.

Tipo de punto	Claves de salida esperadas
Puntos de entrada (START_BY_SEGMENT, START_BY_API, EVENT), INAPP, SET_TAGS, WEBHOOK, AUDIENCE_SYNC, y puntos de mensaje sin divisor (SEND_PUSH, SEND_EMAIL, SEND_SMS, SEND_WHATSAPP, SEND_LINE, SEND_KAKAO, SEND_TELEGRAM, SEND_DATA)	default
GOAL_EVENT, EXIT	ninguno (sin salidas)
FILTER	default, output1
BOOLEAN_SPLITTER	default, luego output1 … outputN (una rama extra por condición. Una división simple de sí/no es default + output1)
WAIT (retraso)	default. Un retraso dinámico con división de ramas añade output1
WAIT_EVENT	default es la rama de evento no activado. output1 (o, con un script de condiciones, una rama por condición) es la ruta activada
SEND_PUSH con un divisor	default, output1 (y output2 cuando tanto el divisor de mensaje como el de entrega están activados)
SEND_EMAIL / SEND_SMS / SEND_LINE / SEND_WHATSAPP con un divisor	default, output1
SEND_WHATSAPP con un preset de respuesta rápida	default, más una rama por respuesta rápida. La clave es el valor de la respuesta rápida en sí
AB_SPLITTER	output0, output1, output2, … (uno por variante. No hay rama default)

Position

Campo	Tipo	Descripción
x	float	Coordenada horizontal en el canvas.
y	float	Coordenada vertical en el canvas.

Tipos de puntos y point_data

point_data es un one-of: lleva exactamente un objeto anidado cuya clave está determinada por el point_type del punto.

point_type	clave point_data	Propósito
POINT_TYPE_START_BY_SEGMENT	start_by_segment	Entrada: usuarios que coinciden con un segmento.
POINT_TYPE_EVENT	message_bus	Entrada: usuarios que activan un evento.
POINT_TYPE_START_BY_API	start_by_api	Entrada: usuarios inyectados a través de la llamada Start by API.
POINT_TYPE_WAIT	delay	Esperar un intervalo fijo o dinámico.
POINT_TYPE_WAIT_EVENT	wait_event	Esperar hasta que ocurra un evento.
POINT_TYPE_SEND_PUSH	send_push	Enviar una notificación push.
POINT_TYPE_SEND_EMAIL	send_email	Enviar un correo electrónico.
POINT_TYPE_SEND_SMS	send_sms	Enviar un SMS.
POINT_TYPE_SEND_WHATSAPP	send_whatsapp	Enviar un mensaje de WhatsApp.
POINT_TYPE_SEND_TELEGRAM	send_telegram	Enviar un mensaje de Telegram.
POINT_TYPE_SEND_KAKAO	send_kakao	Enviar un mensaje de Kakao.
POINT_TYPE_SEND_LINE	send_line	Enviar un mensaje de LINE.
POINT_TYPE_SEND_DATA	send_data	Enviar un mensaje de datos silencioso.
POINT_TYPE_INAPP	inapp	Mostrar un mensaje in-app.
POINT_TYPE_BOOLEAN_SPLITTER	boolean_splitter	Dividir a los usuarios por una condición (segmento, etiquetas o evento).
POINT_TYPE_AB_SPLITTER	ab_splitter	Dividir a los usuarios en grupos A/B.
POINT_TYPE_FILTER	filter	Permitir que solo los usuarios que coincidan con un filtro continúen.
POINT_TYPE_SET_TAGS	set_tags	Actualizar las etiquetas de usuario.
POINT_TYPE_WEBHOOK	web_hook	Enviar una solicitud HTTP saliente.
POINT_TYPE_GOAL_EVENT	goal_event	Rastrear un objetivo de conversión.
POINT_TYPE_AUDIENCE_SYNC	audience_sync	Sincronizar usuarios con una audiencia externa.
POINT_TYPE_EXIT	terminator	Salir del journey.

Nota

Las cargas útiles de point_data por tipo están documentadas en la Referencia de puntos. Los puntos de entrada, temporización, división y acción se cubren en su totalidad allí. Los puntos de mensajería se cubren a nivel de envoltura con enlaces a los documentos del canal correspondiente.

Punto de ejemplo

Un punto “set tags” con una única conexión descendente:

{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "title": "Etiquetar como interesado",
  "point_type": "POINT_TYPE_SET_TAGS",
  "position": { "x": 480, "y": 120 },
  "outputs": [
    {
      "identity": { "key": "default", "order": 0 },
      "info": { "title": "", "next_point_uuid": "ffffffff-1111-2222-3333-444444444444" }
    }
  ],
  "point_data": {
    "set_tags": {
      "application_code": "XXXXX-XXXXX",
      "tags": [ { "name": "engaged", "value": "true" } ]
    }
  }
}

JourneyComment

Campo	Tipo	Descripción
id	string	UUID del comentario.
message	string	Texto del comentario.
position	Position	Coordenadas del canvas.
index	int	Orden de visualización.
created_at	string	Marca de tiempo de creación (ISO 8601).
deleted	bool	Si el comentario está eliminado.

Enums

JourneyStatus enum

STATUS_DRAFT, STATUS_RUNNING, STATUS_FINISHED, STATUS_ARCHIVED, STATUS_PAUSED, STATUS_UNKNOWN.

CampaignType enum

• TriggerBased: los usuarios entran por un evento.
• AudienceBased: los usuarios entran desde un segmento.
• APIBased: los usuarios entran a través de la llamada Start by API.
• Mixed: más de un tipo de entrada.
• Unknown: tipo de entrada no determinado.

PointType enum

Consulte la tabla de tipos de puntos anterior para ver la lista completa y la clave point_data a la que se asigna cada uno.

UserIDTrackChangePolicy enum

Controla lo que le sucede a un usuario que está a mitad de un journey cuando su ID de Usuario cambia:

• DEFAULT: comportamiento predeterminado.
• TRACK: seguir rastreando al usuario con el nuevo ID.
• DROP: eliminar al usuario del journey cuando su ID cambia.

Relacionado

Referencia de puntos

Crear y actualizar

Ciclo de vida