Jornadas — ações, variáveis e personalização

Uma ação é o momento em que a jornada produz um efeito fora da própria progressão. Ela pode enviar uma notificação, chamar um serviço do cliente ou iniciar outra jornada para a mesma pessoa.

Uma boa ação precisa acertar três coisas:

1. o que deve acontecer;
2. quais dados serão usados;
3. o que a instância fará se a execução falhar.

Tipos de ação

O PrismaFlow oferece três tipos de ação: push, webhook e entrada em outra jornada.

Push

Envia uma notificação pelo provider configurado. O título e a descrição são normalmente escritos na própria ação, porque representam a comunicação daquele ponto da jornada.

Um push pode, por exemplo, avisar que uma forma de pagamento não foi aceita e apresentar o próximo passo disponível.

Webhook

Faz uma requisição para um endpoint configurado pelo cliente. O webhook pode executar uma operação de negócio, registrar uma atividade ou entregar uma comunicação por um canal que o próprio cliente gerencia.

Isso permite manter credenciais e regras de canais como WhatsApp e e-mail dentro dos serviços do cliente. Para o PrismaFlow, a ação continua sendo um webhook; o sistema chamado decide como concluir a operação.

Entrar em outra jornada

Cria uma instância numa jornada de destino para a mesma pessoa. A jornada atual continua pelo próximo passo, enquanto a nova instância segue a versão publicada da jornada escolhida.

Esse recurso ajuda a dividir fluxos grandes em responsabilidades menores. Uma jornada pode reconhecer uma oportunidade e encaminhar a pessoa para outra jornada especializada em recuperação de pagamento, por exemplo.

A entrada ainda respeita as políticas da jornada de destino. Por isso, encaminhar a pessoa não garante que uma nova instância será criada: uma política de entrada única, deduplicação ou limite pode impedir essa entrada.

Template, ação e provider cumprem papéis diferentes

Para push e webhook, os três conceitos trabalham juntos:

• provider: representa a integração capaz de executar a entrega;
• template: reúne configurações avançadas e opções reutilizáveis, como sons, imagens, tracking e deeplinks permitidos;
• ação: escreve o conteúdo daquele ponto da jornada, escolhe entre as opções oferecidas pelo template e define os valores dinâmicos usados no nó.

Imagine um template de push que ofereça três deeplinks: home, carrinho e promocoes. Uma ação de recuperação escolhe carrinho, enquanto uma ação de campanha escolhe promocoes. As duas reutilizam a mesma configuração avançada sem precisar criar um template para cada mensagem.

Na ação de recuperação, o time pode escrever:

Olá, {{primeiro_nome}}. Não conseguimos concluir seu pagamento de {{valor}}.

A própria ação define de onde vêm primeiro_nome e valor. O texto pode mudar de uma ação para outra sem multiplicar templates. O template continua responsável pelas possibilidades reutilizáveis, como quais deeplinks podem ser selecionados.

Providers e templates possuem regras próprias de configuração, credenciais, versões e ciclo de vida. Os guias dedicados detalham sua configuração, a diferença entre uma solicitação confirmada, entregue ou clicada e como templates organizam opções reutilizáveis.

O que é uma variável

Uma variável liga um placeholder, como {{primeiro_nome}}, a um valor disponível quando a instância alcança a ação.

Os placeholders podem aparecer no título, na descrição e em outros campos configurados pela ação. Cada um precisa apontar para uma fonte.

Trait e identidade leem o perfil atual

Traits e identidades são resolvidos quando a ação é executada. Se a pessoa mudou de plano durante uma espera, a variável de trait encontra o plano atual, não necessariamente o plano que existia na entrada.

Use identidade para os dados protegidos que identificam ou alcançam uma pessoa. Não copie e-mail, telefone ou outro identificador para properties ou traits apenas para personalizar uma ação.

Contexto preserva a entrada

Contexto contém os dados que acompanharam a entrada da instância. Numa jornada iniciada por evento, isso pode incluir as propriedades daquele acontecimento.

Se PAGAMENTO_RECUSADO@1 iniciou a jornada, o motivo, o valor e o produto podem ser usados depois, desde que façam parte do contexto recebido. Mesmo que outros pagamentos aconteçam, esse retrato continua ligado àquela instância.

Dados coletados vêm de uma etapa anterior

Uma etapa de coleta pode chamar um serviço e guardar uma resposta validada para os próximos nós. A ação consegue usar esses campos como Dados coletados.

Essa fonte só fica disponível quando a coleta acontece antes da ação em todos os caminhos que chegam até ela. Isso impede que um caminho tente usar uma resposta que nunca foi produzida.

Use fallback para não depender de um dado perfeito

Trait, identidade, Contexto e Dados coletados aceitam um valor padrão. Use esse fallback sempre que houver uma alternativa segura.

Por exemplo, {{primeiro_nome}} pode usar “Olá” ou outra composição neutra quando o nome não estiver disponível. Um texto secundário também pode receber uma versão genérica.

Não use um fallback que mude o significado da operação. Se o valor é essencial — como o código de um benefício que deveria ter sido criado — continuar com um valor inventado produz uma comunicação incorreta.

Sem valor resolvido e sem fallback, o placeholder permanece incompleto e a ação não é enviada.

Exemplo: recuperar um pagamento sem prometer o que falhou

Considere uma jornada iniciada por PAGAMENTO_RECUSADO@1:

1. o Contexto preserva o valor, o produto e o motivo da recusa;
2. um webhook chama o serviço do cliente para liberar frete grátis;
3. quando basta saber que a operação foi aceita, o próximo passo pode seguir depois do sucesso da ação;
4. se o código ou outro campo da resposta for necessário, uma etapa de coleta chama o serviço, valida a resposta e guarda os Dados coletados;
5. um push usa o primeiro nome atual do perfil, os dados da entrada e, quando existir, o valor coletado;
6. a jornada pode encaminhar a pessoa para um fluxo especializado de recuperação.

O webhook também poderia pedir ao serviço do cliente que enviasse a comunicação por WhatsApp ou e-mail. Essa escolha é útil quando o cliente prefere manter suas credenciais e regras de envio centralizadas.

A resposta de uma ação webhook comum não vira Dados coletados automaticamente. Use a etapa de coleta quando os próximos nós precisarem ler campos dessa resposta.

O que fazer quando uma ação falha

Cada ação permite escolher entre continuar ou interromper a instância.

Continuar

A instância segue para o próximo nó mesmo quando a ação falha ou é suprimida. Essa opção funciona quando os próximos passos continuam válidos sem a entrega anterior.

Interromper

A instância termina e os nós seguintes não são executados. Use essa proteção quando o restante da jornada depende do sucesso da ação.

No exemplo do frete grátis, comunicar “seu benefício está disponível” depois que o webhook falhou seria um erro grave. A ação que concede o benefício deve interromper a instância em caso de falha. Assim, o push seguinte não promete algo que não aconteceu.

Supressão também pode acionar essa política. Isso acontece, por exemplo, quando o perfil ou o dado de destino necessário não está disponível.

Proteção contra excesso de comunicações

Jornadas diferentes podem tentar falar com a mesma pessoa quase ao mesmo tempo. Uma jornada pode avisar sobre um pagamento, enquanto outra comunica uma promoção ou uma mudança no pedido. Sem coordenação, o usuário receberia várias notificações em sequência, mesmo que cada jornada, analisada sozinha, estivesse funcionando corretamente.

Essa colisão prejudica a experiência, aumenta a sensação de spam e pode fazer uma mensagem importante se perder entre outras comunicações. O PrismaFlow protege a pessoa desse excesso ao organizar os envios de cada canal numa janela compartilhada.

Depois que uma comunicação ocupa a janela de um canal, outra comunicação do mesmo canal para o mesmo perfil e app aguarda até completar 15 minutos.

Essa proteção não é uma particularidade do push: ela pertence a todo canal classificado como comunicação. Hoje, aplica-se ao push. Quando canais como e-mail e SMS forem oferecidos, eles entram no mesmo contrato sem precisar redefinir a regra.

A janela não fica restrita a uma jornada, um template ou uma integração específica. Por isso, ações produzidas por jornadas diferentes também respeitam a janela compartilhada do canal quando pertencem ao mesmo app e perfil.

A segunda comunicação não é descartada. Ela permanece na fila e é reagendada para o tempo restante.

Webhook é a exceção. Ele não participa dessa janela porque também pode representar uma operação de negócio que precisa acontecer imediatamente, como conceder um benefício, atualizar um sistema ou registrar uma atividade.

Aceito pelo provider não é o mesmo que entregue

Uma ação reconhecida como aceita confirma que o provider recebeu a solicitação. Isso não garante, por si só, que a pessoa recebeu ou abriu a comunicação.

Quando o canal fornecer atualizações posteriores, a entrega pode evoluir para estados como entregue ou clicado. Ao investigar uma ação, diferencie:

• a solicitação foi montada corretamente;
• o provider aceitou a solicitação;
• a entrega chegou ao destino;
• a pessoa interagiu com a comunicação.

Testar uma ação

O teste de push ou webhook usa um perfil escolhido e faz um disparo real com a integração e o template configurados. Por isso, exige confirmação com autenticação de dois fatores.

Revise o destino antes de confirmar. Um teste pode enviar uma notificação verdadeira ou chamar um serviço real.

Hoje, uma ação que depende do Contexto de entrada não pode ser testada isoladamente, porque não existe uma instância real fornecendo esses dados. Faça esse teste numa jornada controlada até que o produto ofereça uma simulação de contexto.

Boas práticas

1. Nomeie a ação pelo efeito esperado, como “Liberar frete grátis” ou “Avisar pagamento recusado”.
2. Use Contexto para o acontecimento que iniciou aquela instância e Trait para o estado mais recente do perfil.
3. Use Dados coletados somente depois de uma etapa que esteja presente em todos os caminhos anteriores.
4. Configure fallback para cada variável que possua uma alternativa segura.
5. Interrompa a instância quando os próximos passos dependerem do sucesso da ação.
6. Considere a janela de 15 minutos ao desenhar sequências com mais de uma comunicação no mesmo canal.
7. Não confunda solicitação aceita pelo provider com entrega confirmada.
8. Teste com um perfil e destino controlados antes de publicar uma comunicação em escala.
9. Mantenha opções avançadas reutilizáveis no template e escreva o conteúdo específico da comunicação na ação.

Assuntos relacionados

• Templates — conteúdo, camadas, respostas, versões e ciclo de vida
• Providers — catálogo, configuração e ciclo de vida
• Providers — execução, respostas e webhooks de métricas
• Jornadas — goals, conversões e resultados [blocked]
• Jornadas — condições, decisões, esperas e progressão [blocked]
• Jornadas — entradas, gatilhos, audiências e agendamento [blocked]
• Traits e evolução do perfil
• Identidades e formação de perfis

Revisão editorial

• Estado: Em revisão
• Fatos confirmados em: editor de jornadas, resolução de variáveis, composição e dispatch de ações atuais
• Walkthrough: conhecimento operacional fornecido pelo Darlysson na PF-1374 em 15/08/2026
• Lacunas conhecidas: o teste isolado ainda não permite simular dados de entrada