Objeto Journey

Os métodos de ciclo de vida, criação e atualização todos retornam um objeto de jornada com a mesma estrutura de nível superior:

Estrutura

{
  "info": { ... },        // metadados somente leitura (apenas respostas)
  "params": { ... },      // configuração de toda a jornada (criar / atualizar)
  "points": [ ... ],      // nós da tela e suas conexões
  "comments": [ ... ]     // comentários da tela
}

Quando você cria ou atualiza uma jornada, você envia title, params, points e comments. As respostas retornam info (que contém params), além de points e comments.

Info

Metadados da jornada somente leitura. Retornado por todos os métodos v3. Não faz parte do corpo da solicitação.

Campo	Tipo	Descrição
uuid	string	ID da Journey.
title	string	Nome da jornada.
status	JourneyStatus	Estado atual.
created_at	string	Timestamp de criação (ISO 8601).
updated_at	string	Timestamp da última atualização (ISO 8601).
is_first_activated	bool	Se a jornada foi iniciada pelo menos uma vez.
params	JourneyParams	Configuração de toda a jornada.
category_uuid	string	UUID da categoria, ou vazio se não categorizado.
pointCounts	map<string, uint32>	Contagem de pontos por tipo.
campaign_type	CampaignType	Como os usuários entram na jornada.
stop_reason	string	Por que a jornada parou, se aplicável.
last_edited_by	User	Usuário que editou a jornada pela última vez.
dynamic_entry	bool	Se a entrada dinâmica está habilitada.

JourneyParams

Configuração de toda a jornada. Enviado na criação/atualização e retornado dentro de info.params.

Campo	Tipo	Descrição
application_code	string	Código do aplicativo ao qual a jornada pertence. Obrigatório na criação.
silent_hours	SilentHours	Horas durante as quais as mensagens são suprimidas, por canal.
capping	EntryCapping	Limites de frequência com que um usuário pode reentrar na jornada.
conversion_window	ConversionWindow	Janela para atribuir conversões de meta.
user_id_track_change_policy	UserIDTrackChangePolicy	Como lidar com a mudança de ID de um usuário no meio da jornada.

SilentHours

Suprime o envio durante as horas de silêncio. Configurado por canal: cada canal utiliza seus próprios SilentHoursParams:

Campo	Tipo	Descrição
push_params	SilentHoursParams	Horas de silêncio para notificações push.
inapp_params	SilentHoursParams	Horas de silêncio para mensagens in-app.
email_params	SilentHoursParams	Horas de silêncio para e-mails.
sms_params	SilentHoursParams	Horas de silêncio para SMS.
whatsapp_params	SilentHoursParams	Horas de silêncio para WhatsApp.
line_params	SilentHoursParams	Horas de silêncio para LINE.

Cada SilentHoursParams é:

Campo	Tipo	Descrição
enabled	bool	Se as horas de silêncio se aplicam a este canal.
from_time	Time	Início da janela de silêncio: { "hour": 0–23, "minute": 0–59 }.
to_time	Time	Fim da janela de silêncio.
week_days	bool[]	Sete booleanos para os dias em que a janela se aplica (Segunda-feira = índice 0).
behavior	enum	O que fazer quando uma mensagem cai dentro das horas de silêncio: WaitAndSend (reter e enviar quando a janela terminar), DropAndGo (pular a mensagem, continuar a jornada imediatamente), ou WaitAndDrop (esperar o fim da janela e continuar sem enviar).

EntryCapping

Limita a frequência com que o mesmo usuário pode entrar na jornada.

Campo	Tipo	Descrição
is_enabled	bool	Se o limite de entrada está ativado.
period	uint64	Número mínimo de segundos entre as entradas de um usuário.

ConversionWindow

Campo	Tipo	Descrição
seconds	uint64	Quanto tempo após entrar em uma jornada a conclusão de uma meta pelo usuário ainda conta como uma conversão.

Point

Um ponto é um nó na tela da jornada: um ponto de entrada, uma mensagem, um atraso, um divisor, e assim por diante.

Campo	Tipo	Descrição
uuid	string	ID único do ponto dentro da jornada. Deve ser um UUID canônico RFC 4122: 32 dígitos hexadecimais em grupos de 8-4-4-4-12.
title	string	Nome de exibição do ponto.
point_type	PointType	O tipo de nó.
outputs	array of PointOutput	Conexões com pontos subsequentes.
position	Position	Coordenadas na tela.
point_data	object	Exatamente uma chave aninhada, correspondendo a point_type (veja a tabela de tipos de ponto).

Nota

Todos os UUIDs (info.uuid, cada uuid de ponto, e o next_point_uuid de cada saída) devem ser UUIDs canônicos RFC 4122 (grupos hexadecimais 8-4-4-4-12).

PointOutput

As saídas de um ponto são suas ramificações de saída. Suas chaves não são de formato livre. O validador espera um conjunto exato de chaves para cada tipo de ponto e rejeita uma jornada cujo ponto tenha o número errado de saídas ou uma chave que não reconhece.

Campo	Tipo	Descrição
identity.key	string	Chave da ramificação. Deve seguir as regras de chaves de saída abaixo.
identity.order	int	Ordem de exibição da ramificação.
info.title	string	Rótulo opcional da ramificação.
info.next_point_uuid	string	UUID do próximo ponto ao qual esta ramificação se conecta.

Chaves de saída

A ramificação padrão (primeira) é sempre chamada de "default". Ramificações adicionais são chamadas de "output1", "output2", … (o prefixo output seguido por um índice baseado em 1). Dois tipos de ponto quebram essa regra, conforme observado abaixo.

Tipo de ponto	Chaves de saída esperadas
Pontos de entrada (START_BY_SEGMENT, START_BY_API, EVENT), INAPP, SET_TAGS, WEBHOOK, AUDIENCE_SYNC, e pontos de mensagem sem divisor (SEND_PUSH, SEND_EMAIL, SEND_SMS, SEND_WHATSAPP, SEND_LINE, SEND_KAKAO, SEND_TELEGRAM, SEND_DATA)	default
GOAL_EVENT, EXIT	nenhuma (sem saídas)
FILTER	default, output1
BOOLEAN_SPLITTER	default, depois output1 … outputN (uma ramificação extra por condição. Uma divisão simples de sim/não é default + output1)
WAIT (atraso)	default. Um atraso dinâmico com divisão de ramificação adiciona output1
WAIT_EVENT	default é a ramificação de evento não acionado. output1 (ou, com um script de condições, uma ramificação por condição) é o caminho acionado
SEND_PUSH com um divisor	default, output1 (e output2 quando os divisores de mensagem e de entrega estão ambos ativados)
SEND_EMAIL / SEND_SMS / SEND_LINE / SEND_WHATSAPP com um divisor	default, output1
SEND_WHATSAPP com um preset de resposta rápida	default, mais uma ramificação por resposta rápida. A chave é o próprio valor da resposta rápida
AB_SPLITTER	output0, output1, output2, … (um por variante. Não há ramificação default)

Position

Campo	Tipo	Descrição
x	float	Coordenada horizontal na tela.
y	float	Coordenada vertical na tela.

Tipos de ponto e point_data

point_data é um one-of: ele carrega exatamente um objeto aninhado cuja chave é determinada pelo point_type do ponto.

point_type	chave point_data	Propósito
POINT_TYPE_START_BY_SEGMENT	start_by_segment	Entrada: usuários que correspondem a um segmento.
POINT_TYPE_EVENT	message_bus	Entrada: usuários que acionam um evento.
POINT_TYPE_START_BY_API	start_by_api	Entrada: usuários injetados através da chamada Start by API.
POINT_TYPE_WAIT	delay	Aguardar por um intervalo fixo ou dinâmico.
POINT_TYPE_WAIT_EVENT	wait_event	Aguardar até que um evento ocorra.
POINT_TYPE_SEND_PUSH	send_push	Enviar uma notificação push.
POINT_TYPE_SEND_EMAIL	send_email	Enviar um e-mail.
POINT_TYPE_SEND_SMS	send_sms	Enviar um SMS.
POINT_TYPE_SEND_WHATSAPP	send_whatsapp	Enviar uma mensagem de WhatsApp.
POINT_TYPE_SEND_TELEGRAM	send_telegram	Enviar uma mensagem de Telegram.
POINT_TYPE_SEND_KAKAO	send_kakao	Enviar uma mensagem de Kakao.
POINT_TYPE_SEND_LINE	send_line	Enviar uma mensagem de LINE.
POINT_TYPE_SEND_DATA	send_data	Enviar uma mensagem de dados silenciosa.
POINT_TYPE_INAPP	inapp	Mostrar uma mensagem in-app.
POINT_TYPE_BOOLEAN_SPLITTER	boolean_splitter	Dividir usuários por uma condição (segmento, tags ou evento).
POINT_TYPE_AB_SPLITTER	ab_splitter	Dividir usuários em grupos A/B.
POINT_TYPE_FILTER	filter	Permitir que apenas usuários que correspondem a um filtro continuem.
POINT_TYPE_SET_TAGS	set_tags	Atualizar tags de usuário.
POINT_TYPE_WEBHOOK	web_hook	Enviar uma solicitação HTTP de saída.
POINT_TYPE_GOAL_EVENT	goal_event	Rastrear uma meta de conversão.
POINT_TYPE_AUDIENCE_SYNC	audience_sync	Sincronizar usuários com uma audiência externa.
POINT_TYPE_EXIT	terminator	Sair da jornada.

Nota

Os payloads point_data por tipo estão documentados na Referência de Ponto. Pontos de entrada, tempo, divisão e ação são abordados em detalhes lá. Os pontos de mensagens são abordados no nível do envelope com links para a documentação do canal relevante.

Ponto de exemplo

Um ponto “definir tags” com uma única conexão subsequente:

{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "title": "Tag as engaged",
  "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	Descrição
id	string	UUID do comentário.
message	string	Texto do comentário.
position	Position	Coordenadas na tela.
index	int	Ordem de exibição.
created_at	string	Timestamp de criação (ISO 8601).
deleted	bool	Se o comentário foi excluído.

Enums

Enum JourneyStatus

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

Enum CampaignType

• TriggerBased: usuários entram em um evento.
• AudienceBased: usuários entram a partir de um segmento.
• APIBased: usuários entram através da chamada Start by API.
• Mixed: mais de um tipo de entrada.
• Unknown: tipo de entrada não determinado.

Enum PointType

Veja a tabela de tipos de ponto acima para a lista completa e a chave point_data à qual cada um corresponde.

Enum UserIDTrackChangePolicy

Controla o que acontece com um usuário que está no meio da jornada quando seu ID de Usuário muda:

• DEFAULT: comportamento padrão.
• TRACK: continuar rastreando o usuário sob o novo ID.
• DROP: remover o usuário da jornada quando seu ID mudar.

Relacionados

Referência de ponto

Criar e atualizar

Ciclo de vida