Templates — conteúdo, camadas, respostas, versões e ciclo de vida

Um template organiza as possibilidades que uma ação pode usar ao enviar uma comunicação ou chamar um endpoint. Ele ajuda a reutilizar configurações sem obrigar todas as ações a terem o mesmo conteúdo.

No PrismaFlow, template não é sinônimo de mensagem pronta. Título e corpo de um push costumam ser escritos na própria ação. O template define o que fica fixo, o que pode ser escolhido e o que deve ser preenchido livremente em cada uso.

Integração, template e ação

Os três conceitos trabalham em sequência:

1. a integração conecta o PrismaFlow ao provider e guarda credenciais, identificação e configurações do ambiente;
2. o template define a estrutura reutilizável e as opções permitidas;
3. a ação escolhe o template, preenche o conteúdo livre, seleciona variantes e resolve valores dinâmicos.

Um template pertence a uma integração específica. Se for necessário trocar de app no OneSignal ou usar outro destino de webhook, crie um novo template ligado à integração correta.

Três formas de configurar um campo

Campos centrais, como título, corpo, método e path, podem usar três modos.

Livre

A ação preenche o valor. Esse é o modo recomendado para título e corpo quando cada ponto da jornada possui sua própria comunicação.

Uma ação de boas-vindas pode escrever uma mensagem, enquanto outra ação de recuperação de pagamento usa um texto diferente. As duas continuam compartilhando as configurações avançadas do mesmo template.

Fixo

O valor é definido no template e não muda entre as ações que o utilizam.

Use esse modo quando o conteúdo precisa ser igual em todos os usos. Um aviso obrigatório ou um identificador técnico da integração são exemplos melhores do que fixar toda mensagem de uma campanha.

Lista de opções

O template oferece alternativas aprovadas e define uma delas como padrão. A ação escolhe uma opção ou mantém o padrão.

Esse modo funciona bem quando o time quer dar liberdade controlada. Em vez de permitir qualquer valor, o template pode oferecer somente opções que já foram revisadas.

Camadas agrupam configurações avançadas

Uma camada reúne campos que cumprem a mesma finalidade. Ela pode possuir valores fixos ou oferecer um conjunto de variantes.

Quando a camada é fixa, todas as ações recebem a mesma configuração. Quando ela possui variantes, a ação escolhe uma opção completa, sem precisar preencher seus campos separadamente.

Exemplo: deeplinks

Um template de push pode oferecer uma camada com três destinos:

• Home abre a página inicial;
• Carrinho leva a pessoa de volta à compra;
• Promoções abre a área de ofertas.

A ação de recuperação escolhe Carrinho. Uma campanha promocional escolhe Promoções. A regra de abertura permanece centralizada no template.

Exemplo: aparência de uma campanha

Outra camada pode agrupar ícone, imagem e som. O conjunto padrão usa a identidade habitual do app. Variantes sazonais, como Natal, Páscoa ou Carnaval, podem trocar esses elementos em conjunto.

Assim, a ação seleciona a identidade da campanha sem precisar conhecer cada campo técnico exigido pelo provider.

Não crie uma variante para cada mensagem. Camadas funcionam melhor para opções avançadas que realmente serão reutilizadas.

Templates de push

No push, título e corpo podem ser fixos, escolhidos em lista ou livres. O template também pode organizar opções suportadas pelo provider, como:

• deeplink;
• ícones e imagens;
• som;
• dados adicionais;
• configurações de tracking.

Os idiomas disponíveis vêm da integração. Quando título ou corpo possuem conteúdo no template, os valores precisam respeitar os idiomas configurados.

Para a maioria das jornadas, deixe título e corpo livres e mantenha no template somente as opções reutilizáveis. Isso evita criar um template novo para cada frase.

Templates de webhook

No webhook, o template descreve a requisição que será feita. Ele pode definir:

• método HTTP;
• path do endpoint;
• query parameters;
• headers;
• body.

Método e path podem ser fixos, escolhidos numa lista ou preenchidos pela ação. Query, headers e body são organizados em camadas com valores fixos ou variantes.

A integração fornece a URL base e as configurações comuns. O template completa o caminho e a estrutura da chamada. A ação escolhe opções e fornece os valores daquele caso.

A resposta também possui um contrato

Um template de webhook pode declarar o formato esperado da resposta. Esse schema informa quais campos existem, seus tipos e quais deles são obrigatórios.

Esse contrato é importante em dois cenários.

Condição webhook

A jornada faz uma requisição e decide o caminho de acordo com a resposta.

Imagine um endpoint que informa se uma pessoa possui um benefício disponível. O schema pode declarar o campo booleano eligible. A condição usa esse campo para seguir pelo caminho verdadeiro ou falso.

Coleta de dados

Uma etapa chama o endpoint, valida a resposta e guarda os campos declarados para os próximos nós.

Um serviço pode retornar:

{  "coupon_code": "FRETEGRATIS",  "expires_at": "2026-08-20T23:59:59.000Z"}

O schema declara coupon_code como texto e expires_at como data. Depois da validação, uma ação pode usar esses valores como Dados coletados.

Declare somente os campos que a jornada realmente precisa. Uma resposta pode conter outras informações, mas elas não precisam entrar no contexto da instância.

Variáveis e placeholders

Valores do template e valores preenchidos pela ação podem conter placeholders, como {{primeiro_nome}} ou {{valor}}.

A origem dessas variáveis é configurada na ação. Ela pode apontar para trait, identidade, contexto de entrada, dados coletados, valor fixo ou função. É também na ação que devem ser definidos os fallbacks seguros.

O template apenas oferece o local em que o valor será usado. Ele não decide sozinho de qual perfil ou evento aquele dado virá.

Se um placeholder necessário não puder ser resolvido e não possuir fallback, a ação não será enviada. Evite colocar variáveis num valor fixo quando todas as ações não conseguirem fornecer a mesma informação.

Validação e ativação

Um template nasce como rascunho. Durante a criação e a edição, o PrismaFlow valida se:

• os campos existem no contrato do provider;
• valores fixos e opções possuem tipos aceitos;
• os idiomas obrigatórios foram preenchidos;
• camadas usam destinos suportados;
• campos e camadas não tentam escrever no mesmo lugar;
• cada lista possui opções e um padrão válido;
• o schema de resposta possui uma estrutura reconhecida.

Para ativar, a integração relacionada também precisa estar ativa. Uma validação bem-sucedida confirma a estrutura do template, mas não realiza todos os efeitos possíveis no sistema de destino.

Ciclo de vida

Rascunho

O template pode ser editado, mas ainda não aparece como opção para novas ações. Use esse estado para terminar sua estrutura e revisar as escolhas oferecidas.

Ativo

O template está disponível para jornadas e pode ser executado pela integração relacionada.

Editar um template ativo cria uma nova versão. A alteração não reescreve automaticamente as versões que já foram fixadas em jornadas publicadas.

Arquivado

O template deixa de aparecer para novos usos e não pode ser editado ou reativado. Seu histórico e suas versões permanecem preservados.

Jornadas já publicadas devem continuar usando a versão que fixaram. Antes de arquivar, confira as referências existentes e confirme que nenhuma nova publicação ainda depende daquele template.

Como as versões protegem jornadas publicadas

A primeira ativação publica a primeira versão do template. Cada edição posterior de um template ativo publica outra versão.

Ao publicar uma jornada, o PrismaFlow fixa a versão do template usada naquele desenho. Isso permite que:

• instâncias existentes continuem com a configuração conhecida;
• uma mudança no template não altere silenciosamente uma jornada publicada;
• uma nova versão da jornada escolha a versão mais recente do template depois da revisão.

Se uma campanha sazonal trocar imagem e som, por exemplo, jornadas antigas não devem ganhar essa aparência sem uma nova publicação.

Boas práticas

1. Dê ao template um nome que identifique canal, integração e finalidade.
2. Deixe título e corpo livres quando a mensagem pertence à ação.
3. Use conteúdo fixo somente quando ele realmente precisa ser igual em todos os usos.
4. Use listas para oferecer escolhas aprovadas e sempre defina um padrão seguro.
5. Agrupe em uma variante os campos que precisam mudar juntos, como imagem, som e deeplink.
6. Não multiplique templates apenas para trocar uma frase.
7. Em webhooks, declare como resposta somente os campos usados por condições ou coletas.
8. Revise jornadas relacionadas antes de editar ou arquivar.
9. Publique uma nova versão da jornada quando ela precisar adotar mudanças do template.

Assuntos relacionados

• Providers — catálogo, configuração e ciclo de vida
• Providers — execução, respostas e webhooks de métricas
• Jornadas — ações, variáveis e personalização
• Jornadas — condições, decisões, esperas e progressão

Revisão editorial

• Estado: Em revisão
• Fatos confirmados em: editor de templates, validação, composição, schema de resposta, versionamento e publicação atuais
• Walkthrough: conhecimento operacional fornecido pelo Darlysson na PF-1379 em 15/08/2026
• Lacunas conhecidas: o runtime precisa preservar versões fixadas depois do arquivamento; detalhes estão registrados no complemento interno