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:

Shape

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

Quando você cria ou atualiza uma Journey, você envia title, params, points e comments. As respostas retornam info (que contém params), além de 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 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 e continuar a Journey 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 Journey.

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	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ó no canvas 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 de 8-4-4-4-12.
title	string	Nome de exibição do point.
point_type	PointType	O tipo de nó.
outputs	array of PointOutput	Conexões para points subsequentes.
position	Position	Coordenadas do canvas.
point_data	object	Exatamente uma chave aninhada, correspondente 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 de 8-4-4-4-12 hexadecimais).

PointOutput

As saídas de um point 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 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 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 point ao qual esta ramificação se conecta. Opcional — deixá-lo em branco encerra a Journey para o usuário, da mesma forma que um point terminador explícito.

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 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 (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 no canvas.
y	float	Coordenada vertical no canvas.

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 “set 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 do canvas.
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

JourneyStatus enum

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

CampaignType enum

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

PointType enum

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

UserIDTrackChangePolicy enum

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