Contexto
As etapas de Contexto permitem criar e atualizar uma ou mais variáveis para um usuário conforme ele avança por um Canvas. Por exemplo, se você tem um Canvas que gerencia descontos sazonais, pode usar uma variável de contexto para armazenar um código de desconto diferente cada vez que um usuário entra no Canvas.

A disponibilidade do Canvas Context varia por espaço de trabalho. Se Context não aparecer no menu de etapas do Canvas e o menu de personalização mostrar Canvas Entry Properties em vez de Context Variables, use canvas_entry_properties para dados de entrada. Entre em contato com o gerente da sua conta se precisar de acesso ao Canvas Context.
Como funciona

As etapas de Contexto permitem criar e usar dados temporários durante a jornada de um usuário por um Canvas específico. Esses dados existem apenas dentro dessa jornada do Canvas. Eles não persistem em outros Canvas nem fora da sessão.
As variáveis de contexto existem apenas naquela jornada específica do Canvas. Elas não alteram o perfil do usuário de forma permanente e não aparecem em outros Canvas. Por isso, são ideais para informações temporárias que só importam para uma campanha ou um fluxo de trabalho específico.

Para uma referência completa sobre variáveis de contexto, incluindo tipos de dados, uso e práticas recomendadas, consulte a Referência de variáveis de contexto.
Em uma etapa de Contexto, você pode definir ou atualizar até 10 variáveis de contexto. Essas variáveis podem ser usadas para personalizar postergações, segmentar usuários de forma dinâmica e enriquecer as mensagens ao longo do Canvas. Por exemplo, você pode criar uma variável de contexto com o horário do voo agendado de um usuário e depois usá-la para definir postergações personalizadas e enviar lembretes.
Você pode definir variáveis de contexto de duas formas:
- Na entrada do Canvas: As propriedades do evento personalizado ou do disparo por API são preenchidas automaticamente como variáveis de contexto.
- Em uma etapa de Contexto: Defina ou atualize variáveis de contexto manualmente adicionando uma etapa de Contexto.
Cada variável de contexto exige um nome, um tipo de dado e um valor (definido com Liquid ou com a ferramenta Adicionar personalização). Depois de definidas, você pode referenciar as variáveis de contexto em todo o Canvas usando Liquid, como {{context.${flight_time}}}. No campo Nome da variável de contexto, você também pode inserir o nome da variável de contexto ou selecioná-lo no menu suspenso do editor da etapa. Para saber mais, consulte a Referência de variáveis de contexto.
Cada entrada no Canvas redefine as variáveis de contexto com base nos dados de entrada mais recentes e na configuração do Canvas. Assim, os usuários podem ter várias jornadas ativas, cada uma com seu próprio contexto. Por exemplo, se um cliente tem dois voos marcados, ele terá dois estados de jornada separados rodando ao mesmo tempo—cada um com suas próprias variáveis de contexto específicas do voo, como horário de partida e destino. Então, você pode enviar lembretes personalizados sobre o voo das 14h para Nova York e, ao mesmo tempo, enviar atualizações diferentes sobre o voo de amanhã às 8h para Los Angeles. Dessa forma, cada mensagem continua relevante para a reserva específica.
Processamento de usuários e lotes
As etapas de Contexto processam usuários em lotes para otimizar a performance. Quando os usuários entram em uma etapa de Contexto, a Braze os processa em lotes de 1.000 usuários por padrão. Esses lotes são processados em paralelo, mas, dentro de cada lote, os usuários são processados em sequência.
Isso significa que:
Exemplo: Se 3.500 usuários entrarem em uma etapa de Contexto com Connected Content que leva 650 ms por usuário:
- A Braze cria 4 lotes de usuários (1.000, 1.000, 1.000 e 500 usuários neste exemplo).
- Cada lote processa os usuários em sequência, então um lote de 1.000 usuários leva cerca de 10,8 minutos (650 segundos; 1.000 × 650 ms).
- Os lotes terminam em momentos diferentes, então os usuários vão passando para a próxima etapa à medida que o lote deles é concluído.
- Os primeiros usuários podem chegar à próxima etapa vários minutos antes dos últimos, dependendo do tamanho do lote e dos tempos de resposta do Connected Content.
Sem Connected Content, as etapas de Contexto são processadas muito mais rápido, porque não há chamadas de API externas para aguardar.
Considerações
- Você pode definir até 10 variáveis de contexto por etapa de Contexto.
- Cada variável precisa de um nome exclusivo (somente letras, números e sublinhados, com até 100 caracteres).
- O tamanho total de todas as variáveis em uma etapa não pode ultrapassar 50 KB.
- As variáveis passadas por disparos via API compartilham o mesmo namespace das variáveis criadas em etapas de Contexto. Então, se você redefinir uma variável em uma etapa de Contexto, ela substitui o valor da API.
Para mais detalhes e usos avançados, consulte a referência de variáveis de contexto.
Criação de uma etapa de Contexto

Se Variável de contexto estiver disponível como filtro no seu espaço de trabalho, você não precisa de uma etapa de Contexto para referenciar propriedades do evento disparador nas etapas Jornadas do público ou Divisão de decisão. Você pode referenciar as propriedades diretamente nos grupos de filtro. Certifique-se de selecionar o tipo de dado correto.
Etapa 1: Adicionar uma etapa
Adicione uma etapa ao seu Canvas e arraste e solte o componente da barra lateral. Você também pode selecionar o botão de adição e escolher Contexto.
Etapa 2: Definir as variáveis

Você pode definir até 10 variáveis de contexto em cada etapa de Contexto.
Para definir uma variável de contexto:
- Dê um nome à sua variável de contexto.
- Selecione um tipo de dados.
- Escreva uma expressão Liquid manualmente ou use Adicionar personalização para criar um snippet Liquid a partir de atributos existentes.
- Selecione Prévia para verificar o valor da sua variável de contexto.
- (Opcional) Para adicionar mais variáveis, selecione Adicionar variável de contexto e repita as etapas 1 a 4.
- Quando terminar, selecione Concluído.
Agora você pode usar sua variável de contexto em qualquer lugar que aceite Liquid, como nas etapas de Mensagem e de Atualização de usuário, selecionando Adicionar personalização. No campo Nome da variável de contexto, você também pode digitar o nome da variável de contexto ou selecioná-lo no menu suspenso do editor da etapa. Para ver o passo a passo completo, consulte a referência de variáveis de contexto.

Ao fazer referência a variáveis de contexto, use sempre o formato {{context.${variable_name}}}.
Filtros de variáveis de contexto
Você pode criar filtros usando variáveis de contexto nas etapas de Jornadas de público e Divisão de decisão.
Para direcionar usuários com base na resposta de uma etapa de agente, adicione a etapa de agente antes da etapa de Jornadas de público ou de Divisão de decisão. A etapa de agente armazena a saída no contexto do Canvas, que você pode avaliar com filtros de variáveis de contexto nessas etapas de ramificação.
Se o agente retornar um objeto e você quiser filtrar por uma propriedade aninhada, digite o caminho no campo Nome da variável de contexto usando notação de ponto, em vez de apenas o nome da variável de nível superior (por exemplo, intent_agent.persona quando persona estiver aninhada em intent_agent).

A lista Nome da variável de contexto inclui variáveis de etapas de Contexto e de etapas de agente. Para uma propriedade de entrada do Canvas, digite o nome dela e selecione Usar “ENTRY_PROPERTY_NAME“. Substitua ENTRY_PROPERTY_NAME pelo nome da propriedade de entrada que você digitou. Para uma propriedade aninhada, use notação de ponto, como order.total.
Para saber mais sobre a configuração de filtros, a lógica de comparação e exemplos avançados, consulte a referência de variáveis de contexto.

Escolhendo entre os tipos de filtro “Day of year” e “Time”: Ao filtrar variáveis de contexto que contêm datas, escolha o tipo de comparação correto com base em se a data se repete a cada ano. Use “Day of year” somente quando o ano não estiver incluído no valor que a variável de contexto produz.
- Use “Day of year” quando a data se repete a cada ano (por exemplo, aniversários, datas comemorativas ou feriados como o Natal). Esse tipo de comparação calcula com base no dia do ano (1-365/366), ignorando o componente do ano.
- Use “Time” quando a data for uma data absoluta que não se repete (por exemplo, datas de término de contrato, datas de compromissos ou datas de renovação de inscrição). Esse tipo de comparação calcula com base no timestamp completo, incluindo o ano.
Usar “Day of year” para datas absolutas pode produzir resultados incorretos ou inesperados porque o cálculo ignora o componente do ano. Por exemplo, se você estiver comparando uma data futura de término de contrato em abril para determinar se está dentro de 63 dias, usar “Day of year” pode corresponder incorretamente às datas porque compara apenas os números dos dias (119 vs 359) sem considerar que abril está na verdade a 188 dias de distância.
Prévia das jornadas de usuários
Recomendamos testar e fazer a prévia das jornadas de usuários para garantir que suas mensagens sejam enviadas ao público certo e que as variáveis de contexto sejam avaliadas com os resultados esperados.

Se você estiver fazendo a prévia do seu Canvas na seção Prévia e envio de teste do editor, o carimbo de data/hora na prévia da mensagem de teste não é padronizado para UTC, porque esse painel gera prévias como strings. Isso significa que, se um Canvas estiver configurado para aceitar um objeto time, a prévia da mensagem não reproduz com precisão o que acontece quando o Canvas estiver ativo. Para testar seu Canvas com mais precisão, recomendamos fazer a prévia das jornadas de usuários.
Fique atento aos cenários comuns que geram variáveis de contexto inválidas. Ao fazer a prévia da jornada do usuário, você pode ver os resultados das etapas de postergação personalizadas que usam variáveis de contexto. Também pode ver as comparações nas etapas de público ou de decisão que associam usuários a variáveis de contexto.
Se a variável de contexto for válida, você pode referenciá-la em todo o seu Canvas. No entanto, se a variável de contexto não tiver sido criada corretamente, as etapas seguintes do seu Canvas também não vão funcionar corretamente. Por exemplo, se você criar uma etapa de contexto para atribuir aos usuários um horário de agendamento e definir o valor desse horário como uma data passada, o e-mail de lembrete na sua etapa de mensagem não será enviado.
Conversão de strings do Connected Content em JSON
Quando você faz uma chamada de Connected Content em uma etapa de Contexto, o JSON retornado pela chamada é avaliado como um tipo de dado string, para garantir consistência e evitar erros. Se quiser converter essa string em JSON, use as_json_string. Por exemplo:
{% connected_content http://example.com :save product %}
{{ product | as_json_string }}
Solução de problemas
Variáveis de contexto inválidas
Uma variável de contexto é considerada inválida quando:
- Uma chamada a um Connected Content incorporado falha.
- A expressão Liquid retorna, no momento da execução, um valor que não corresponde ao tipo de dados ou que está vazio (nulo).
- A expressão Liquid chama
{% abort_message() %}.
Por exemplo, se o tipo de dados da variável de contexto for Número, mas a expressão Liquid retornar uma string, a variável é inválida.
Nesses casos:
- O usuário avança para a próxima etapa.
- A análise de dados da etapa do Canvas contabiliza isso como Não atualizado.
Ao solucionar problemas, monitore a métrica Não atualizado para verificar se a variável de contexto está sendo atualizada corretamente. Se a variável de contexto for inválida, seus usuários podem continuar no Canvas após a etapa de Contexto, mas talvez não se qualifiquem para as etapas seguintes.
Consulte Tipos de dados para ver exemplos de configuração para cada tipo de dados.
Uma variável de contexto também pode ser ignorada de propósito com abort_message. Veja Usar abort_message em uma variável de contexto.
Usar abort_message em uma variável de contexto
Você pode usar a Liquid tag abort_message no valor de uma variável de contexto para ignorar essa variável para alguns usuários. Em uma etapa de Contexto, o abort_message afeta apenas a variável em que está. Ele não interrompe a etapa nem faz o usuário sair do Canvas.
Quando o Liquid de uma variável de contexto chama abort_message para um usuário:
- A variável não é definida para esse usuário. Se uma etapa de Contexto anterior já tiver definido essa variável, o usuário mantém o valor anterior.
- As outras variáveis da etapa continuam sendo avaliadas e definidas.
- As variáveis posteriores na mesma etapa que fazem referência a essa variável não recebem um novo valor dela.
- O usuário avança para a próxima etapa.
- A análise de dados da etapa do Canvas contabiliza a variável como Não atualizado.
Por exemplo, esta variável é definida como true para usuários na França e ignorada para todos os outros:
{% if ${country} == "France" %}
true
{% else %}
{% abort_message("Not in France") %}
{% endif %}
Ao visualizar a prévia das jornadas do usuário, uma variável ignorada aparece como “variable_name não foi atualizada porque a lógica Liquid disparou uma interrupção”.
Se as etapas seguintes dependerem dessa variável, planeje o que acontece com os usuários que não a têm definida. Por exemplo, você pode direcioná-los com uma etapa de Jornadas do Público.

As interrupções em etapas de Contexto não são registradas no Registro de atividades de mensagens, e o motivo que você passa para abort_message não é exibido.
Atrasos no envio com Connected Content
Todos os usuários de um lote são processados antes que qualquer usuário avance. Depois que o processamento do lote termina, os usuários bem-sucedidos passam para a próxima etapa, enquanto os usuários com falha passam por novas tentativas separadamente. Ou seja, os usuários bem-sucedidos não esperam as novas tentativas terem sucesso para avançar.
Comportamento de novas tentativas
As chamadas de Connected Content em um Canvas só fazem novas tentativas quando a chamada inclui :retry.
- Etapas de Contexto e de Atualização do Usuário: A Braze tenta novamente a chamada de Connected Content no nível da etapa (até cinco vezes). Se todas as tentativas falharem, o usuário sai do Canvas.
- Etapas de Mensagem: O Connected Content com
:retrycontinua usando o pipeline de envio de mensagens. Os destinatários ficam aguardando na fila de envio enquanto a Braze tenta novamente a chamada até cinco vezes. Se todas as tentativas falharem, a mensagem é interrompida e o usuário avança para a próxima etapa.
Nas etapas de Contexto e de Atualização do Usuário, alguns erros de etapa que permitem nova tentativa, como uma falha ao buscar um código promocional ou um erro inesperado na etapa, podem disparar novas tentativas adicionais no nível da etapa com backoff exponencial (aproximadamente 13 vezes) antes que a Braze faça o usuário sair do Canvas.
Para saber mais sobre a tag :retry, consulte Novas tentativas do Connected Content.
O tempo necessário para processar todos os usuários em uma etapa de Contexto depende de:
- O número de usuários que entram na etapa
- O uso ou não de Connected Content (e o tempo de resposta dele)
- O tamanho do lote (padrão de 1.000 usuários por lote)
Se o seu endpoint de Connected Content tiver limites de frequência, considere que as etapas de Contexto processam os usuários sequencialmente dentro de cada lote, o que ajuda a respeitar esses limites naturalmente. No entanto, vários lotes são processados em paralelo, então confirme que o seu endpoint consegue lidar com solicitações simultâneas de vários lotes.
Consistência de fuso horário
Em espaços de trabalho com Canvas Context, todas as propriedades de evento de data e hora padrão em Canvas baseados em ação ficam em UTC. Isso vale mesmo que o Canvas não use uma etapa de Contexto.

Em todos os casos, recomendamos fortemente usar os filtros de Liquid time_zone para que as datas e horas apareçam no fuso horário desejado. Confira esta pergunta frequente para ver um exemplo.
Perguntas frequentes
Como o Contexto do Canvas afeta os registros de data e hora?
Para espaços de trabalho com Contexto do Canvas:
- Todos os registros de data e hora com um tipo datetime vindos de propriedades do evento-gatilho em Canvas baseados em ação estão em UTC.
- Essa mudança afeta todos os Canvas baseados em ação, independentemente de o Canvas específico usar ou não uma etapa de Contexto.
Qual é o motivo dessa mudança?
Essa mudança faz parte de um esforço mais amplo para criar uma experiência mais previsível e consistente ao editar etapas e mensagens do Canvas.
Os Canvas acionados por API ou agendados são afetados por essa mudança?
Não.
Essa mudança afeta as propriedades de entrada do Canvas?
Sim, ela afeta canvas_entry_properties se a canvas_entry_property estiver sendo usada em um Canvas baseado em ação e o tipo da propriedade for time. Em todos os casos, recomendamos usar filtros time_zone do Liquid para que os registros de data e hora sejam representados no fuso horário desejado.
Veja um exemplo de como fazer isso:
| Liquid na etapa de Mensagem | Resultado | Essa é a forma correta de representar fusos horários no Liquid? |
|---|---|---|
{{canvas_entry_properties.${timestamp_property}}} |
2025-08-05T08:15:30:250-0800 |
Não |
{{canvas_entry_properties.${timestamp_property} | date: "%Y-%m-%d %l:%M %p"}} |
2025-08-05 4:15pm |
Não |
{{canvas_entry_properties.${timestamp_property} | time_zone: "America/Los_Angeles" | date: "%Y-%m-%d %l:%M %p"}} |
2025-08-05 8:15am |
Sim |
Qual é um exemplo prático de como o novo comportamento dos registros de data e hora pode afetar minhas mensagens?
Digamos que temos um Canvas baseado em ação com o seguinte conteúdo em uma etapa de Mensagem:
Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!
Isso resulta na seguinte mensagem:
Your appointment is scheduled for 2025-08-05 4:15 PM, we’ll see you then!
Como nenhum fuso horário foi especificado com Liquid, o registro de data e hora aqui está em UTC.
Para especificar um fuso horário de forma clara, podemos usar filtros time_zone do Liquid assim:
Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | time_zone: "America/Los_Angeles" | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!
Isso resulta na seguinte mensagem:
Your appointment is scheduled for 2025-08-05 8:15 AM, we'll see you then!
Como o fuso horário America/Los Angeles foi especificado com Liquid, o registro de data e hora aqui está em PST.
O fuso horário preferido também pode ser enviado na carga útil das propriedades do evento e usado na lógica do Liquid:
{
"appointment_time": "2025-08-05T08:15:30:250-0800"
"user_timezone": "America/Los_Angeles"
}
Qual é a diferença entre variáveis de contexto e propriedades de entrada do Canvas?
As propriedades de entrada do Canvas são incluídas como variáveis de contexto do Canvas. Isso significa que você pode enviar propriedades de entrada do Canvas usando a API da Braze e referenciá-las em outras etapas, de forma semelhante ao uso de uma variável de contexto com o snippet de Liquid.
As variáveis podem fazer referência umas às outras em uma única etapa de Contexto?
Sim. Todas as variáveis em uma etapa de Contexto são avaliadas em sequência. Então, você poderia configurar as seguintes variáveis de contexto:
| Variável de contexto | Valor | Descrição |
|---|---|---|
favorite_cuisine |
{{custom_attribute.${Favorite Cuisine}}} |
O tipo de culinária favorito de um usuário. |
promo_code |
EATFRESH |
O código de desconto disponível para um usuário. |
personalized_message |
"Enjoy a discount of" {{context.${promo_code}}} "on delivery from your favorite" {{context.${favorite_cuisine}}} restaurants!" |
Uma mensagem personalizada que combina as variáveis anteriores. Em uma etapa de Mensagem, você poderia usar o snippet de Liquid {{context.${personalized_message}}} para referenciar a variável de contexto e entregar uma mensagem personalizada a cada usuário. Você também poderia usar uma etapa de Contexto para salvar o valor do código promocional e usá-lo como modelo em outras etapas ao longo de um Canvas. |
Isso também se aplica a várias etapas de Contexto. Por exemplo, imagine esta sequência:
- Uma etapa de Contexto inicial cria uma variável chamada
JobInfocom o valorjob_title. - Uma etapa de Mensagem referencia
{{context.${JobInfo}}}e exibejob_titlepara o usuário. - Mais adiante, uma etapa de Contexto atualiza a variável de contexto, alterando o valor de
JobInfoparajob_description. - Todas as etapas seguintes que referenciam
JobInfopassam a usar o valor atualizadojob_description.
As variáveis de contexto usam seu valor mais recente ao longo de todo o Canvas. Cada atualização afeta todas as etapas seguintes que referenciam essa variável.