Objeto Journey

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

Estrutura

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

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

Info

Metadados de Journey 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 Journey.
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 Journey foi iniciada pelo menos uma vez.
params	JourneyParams	Configuração para toda a Journey.
category_uuid	string	UUID da categoria, ou vazio se não categorizado.
pointCounts	map<string, uint32>	Contagem de Points por tipo.
campaign_type	CampaignType	Como os usuários entram na Journey.
stop_reason	string	Por que a Journey parou, se aplicável.
last_edited_by	User	Usuário que editou a Journey pela última vez.
dynamic_entry	bool	Se a entrada dinâmica está habilitada.

JourneyParams

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

Campo	Tipo	Descrição
application_code	string	Código da Aplicação à qual a Journey 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 Journey.
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 Journey.

SilentHours

Suprime o envio durante horários 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 e continuar a Journey imediatamente), ou WaitAndDrop (aguardar o fim da janela e continuar sem enviar).

EntryCapping

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

Campo	Tipo	Descrição
is_enabled	bool	Se a limitação de entrada está ativa.
period	uint64	Número mínimo de minutos entre as entradas de um usuário. 0 significa que o usuário pode entrar apenas uma vez na vida.

O limite é contado a partir do momento em que o usuário entrou na Journey, e é rastreado por ID de usuário, então todos os dispositivos de um usuário compartilham uma única entrada. Enquanto o período durar, o ponto de entrada rejeita novas tentativas de entrada e as conta como erros em vez de criar um viajante.

Três comportamentos a serem considerados ao alterar essas configurações:

• Sair da Journey antecipadamente não libera o limite. O usuário aguarda o período completo mesmo após atingir um ponto de saída.
• Um period alterado se aplica a entradas feitas após a atualização. Usuários que entraram anteriormente mantêm o período que estava em vigor quando entraram.
• Definir is_enabled como false remove o limite para todos os usuários imediatamente.

Nota

O Painel de Controle escreve o mesmo campo de Limite de entrada da Campanha, que oferece 0 (uma vez na vida), 1440 (uma vez por dia), 10080 (uma vez por semana), 43800 (uma vez por mês) e 131500 (uma vez a cada três meses).

ConversionWindow

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

Point

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

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

Nota

Todos os UUIDs (info.uuid, cada uuid de Point 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 Point são seus ramos de saída. Suas chaves não são de formato livre. O validador espera um conjunto exato de chaves para cada tipo de Point e rejeita uma Journey cujo Point tenha o número errado de saídas ou uma chave que não reconhece.

Campo	Tipo	Descrição
identity.key	string	Chave do ramo. Deve seguir as regras de chaves de saída abaixo.
identity.order	int	Ordem de exibição do ramo.
info.title	string	Rótulo opcional do ramo.
info.next_point_uuid	string	UUID do próximo Point ao qual este ramo se conecta. Opcional — deixá-lo em branco encerra a Journey para o usuário, da mesma forma que um Point terminator explícito.

Chaves de saída

O ramo padrão (primeiro) é sempre nomeado como "default". Ramos adicionais são nomeados "output1", "output2", … (o prefixo output seguido por um índice baseado em 1). Dois tipos de Point quebram essa regra, conforme observado abaixo.

Tipo de Point	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 (um ramo 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 ramos adiciona output1
WAIT_EVENT	default é o ramo de evento-não-acionado. output1 (ou, com um script de condições, um ramo por condição) é o caminho acionado
SEND_PUSH com um divisor	default, output1 (e output2 quando ambos os divisores de mensagem e entrega estão ativos)
SEND_EMAIL / SEND_SMS / SEND_LINE / SEND_WHATSAPP com um divisor	default, output1
SEND_WHATSAPP com um preset de resposta rápida	default, mais um ramo 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á ramo default)

Position

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

Tipos de Point e point_data

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

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

Nota

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

Exemplo de Point

Um Point “definir tags” com uma única conexão downstream:

{
  "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 Point acima para a lista completa e a chave point_data a que cada um se refere.

Enum UserIDTrackChangePolicy

Controla o que acontece com um usuário que está no meio da Journey 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 Journey quando seu ID mudar.

Relacionados

Referência de Point

Criar e atualizar

Ciclo de vida