Context

Context steps allow you to create and update one or more variables for a user as they move through a Canvas. For example, if you have a Canvas that manages seasonal discounts, you can use a context variable to store a different discount code each time a user enters the Canvas.

How it works

Context steps allow you to create and use temporary data during a user’s journey through a specific Canvas. This data exists only within that Canvas journey and doesn’t persist across different Canvases or outside the session.

For a full reference on context variables, including data types, usage, and best practices, see the Context variables reference.

Within a Context step, you can define or update up to 10 context variables. These variables can be used to personalize delays, segment users dynamically, and enrich messaging throughout the Canvas. For example, you could create a context variable for a user’s scheduled flight time, then use it to set personalized delays and send reminders.

You can set context variables in two ways:

• At Canvas entry: Data from the event or API trigger can automatically populate context variables.
• In a Context step: Define or update context variables manually by adding a Context step.

Each context variable requires a name, a data type, and a value (set using Liquid or the Add Personalization tool). When defined, you can reference context variables throughout the Canvas using Liquid, such as {{context.${flight_time}}}.

Each Canvas entry redefines context variables based on the latest entry data and Canvas setup, allowing users to have multiple active journeys with their own context. For example, if a customer has two upcoming flights, they’ll have two separate journey states running simultaneously—each with its own flight-specific context variables like departure time and destination. This allows you to send personalized reminders about their 2 pm flight to New York while sending different updates about their 8 am flight to Los Angeles tomorrow, so that each message stays relevant to the specific booking.

User processing and batching

Context steps process users in batches to optimize performance. When users enter a Context step, Braze processes them in batches of 1,000 users by default. These batches are processed in parallel, but within each batch, users are processed sequentially.

This means:

• Parallel batch processing: Multiple batches of 1,000 users are processed simultaneously, allowing large audiences to be handled efficiently.
• Sequential processing within batches: Within each batch, users are processed one after another. If your Context step includes Connected Content calls, each user’s Connected Content request must complete before the next user in that batch is processed.
• Independent batch progression: Each batch progresses independently. When a batch completes processing, those users advance to the next step immediately, even if other batches are still processing. This means users from different batches may reach subsequent steps at different times.

Example: If 3,500 users enter a Context step with Connected Content that takes 650ms per user:

• Braze creates approximately 4 batches of users (for example, three batches of 1,000 users and one batch of 500 users).
• Each batch processes users sequentially, so a batch of 1,000 users takes approximately 10–11 minutes (1,000 × 650ms, assuming sequential processing with no overhead).
• Batches complete at different times, so users trickle into the next step as their batch finishes.
• The first users may reach the next step several minutes before the last users, depending on batch size and Connected Content response times.

Without Connected Content, Context steps process much faster because there are no external API calls to wait for.

Considerations

• You can define up to 10 context variables per Context step.
• Each variable requires a unique name (letters, numbers, underscores only, up to 100 characters).
• The total size of all variables in a step cannot exceed 50 KB.
• Variables passed in using API triggers share the same namespace as those created in Context steps; redefining a variable in a Context step overrides the API value.

For more details and advanced usage, see Context variables reference.

Creating a Context step

Step 1: Add a step

Add a step to your Canvas, then drag and drop the component from the sidebar, or select the plus button and select Context.

Step 2: Define the variables

To define a context variable:

1. Give your context variable a name.
2. Select a data type.
3. Write a Liquid expression manually or use Add Personalization to create a Liquid snippet from pre-existing attributes.
4. Select Preview to check the value of your context variable.
5. (Optional) To add additional variables, select Add Context variable and repeat steps 1-4.
6. When you’re finished, select Done.

Now you can use your context variable anywhere you use Liquid, such as in Message and User Update steps, by selecting Add Personalization. For a full walkthrough, see Context variables reference.

Context variable filters

You can create filters using context variables in Audience Paths and Decision Split steps. For filter setup, comparison logic, and advanced examples, see Context variables reference.

Previewing user paths

We recommend testing and previewing your user paths to make sure your messages are sent to the right audience and context variables are evaluated to the expected outcomes.

Be sure to observe any common scenarios that create invalid context variables. When previewing your user path, you can view the outcomes of personalized Delay steps using context variables, and any audience or decision step comparisons that match users to any context variables.

If the context variable is valid, you can reference the variable throughout your Canvas. However, if the context variable wasn’t created correctly, future steps in your Canvas won’t perform correctly either. For example, if you create a Context step to assign users an appointment time and set the appointment time’s value to a past date, the reminder email in your Message step does not send.

Converting Connected Content strings to JSON

When making a Connected Content call in a Context step, JSON returned from the call is evaluated as a string data type for consistency and error prevention. If you want to convert this string into JSON, convert it by using as_json_string. For example:

1
2
{% connected_content http://example.com :save product %}
{{ product | as_json_string }}

Time zone consistency standardization

While most event properties using the timestamp type are already in UTC in Canvas, there are some exceptions. With the addition of Canvas Context, all default timestamp event properties in action-based Canvases are in UTC. This change is part of a broader effort to ensure a more predictable and consistent experience when editing Canvas steps and messages. Note that this change impacts all action-based Canvases, whether the specific Canvas is using a Context step or not.

Troubleshooting

Invalid context variables

A context variable is considered invalid when:

• A call to an embedded Connected Content fails.
• The Liquid expression at runtime returns a value that doesn’t match the data type or is empty (null).

For example, if the context variable data type is Number but the Liquid expression returns a string, it is invalid.

In these circumstances:

• The user advances to the next step.
• The Canvas step analytics counts this as Not Updated.

When troubleshooting, monitor the Not Updated metric to check that your context variable is updating correctly. If the context variable is invalid, your users can continue in your Canvas past the Context step, but may not qualify for later steps.

Refer to Data types for the example setups for each data type.

Delays in sending with Connected Content

All users in a batch are processed before any users advance. After batch processing completes, successful users move to the next step while failed users are retried separately—successful users don’t wait for retry attempts to succeed before advancing.

Retry behavior: Context steps (and all Canvas steps) use Canvas-specific retry mechanisms, not the standard Connected Content retry behavior. If a Connected Content call fails, Braze retries the step approximately 13 times with exponential backoff. If all retries fail, the user exits the Canvas.

Processing time: The time it takes to process all users through a Context step depends on:

• The number of users entering the step
• Whether Connected Content is used (and its response time)
• The batch size (default 1,000 users per batch)

If your Connected Content endpoint has rate limits, consider that Context steps process users sequentially within each batch, which helps respect rate limits naturally. However, multiple batches process in parallel, so ensure your endpoint can handle concurrent requests from multiple batches.

Frequently asked questions

What changes when Canvas Context becomes generally available?

When Canvas Context becomes generally available, the following details apply:

• All timestamps with a datetime type from trigger event properties in action-based Canvases are in UTC.
• This change impacts all action-based Canvases, whether the specific Canvas is using a Context step or not.

What is the reason for this change?

This change is part of a broader effort to create a more predictable and consistent experience when editing Canvas steps and messages.

When is this change taking effect?

• If you’re participating in the Canvas Context early access, this change has already been applied.
• If you’re not participating in the Canvas Context early access, this change applies when you join the early access or when Canvas Context becomes generally available.

Are API-triggered or scheduled Canvases impacted by this change?

No.

Will this change impact Canvas entry properties?

Yes, this impacts canvas_entry_properties if the canvas_entry_property is being used in an action-based Canvas and the property type is time. In all circumstances, we recommend using Liquid time_zone filters for timestamps to be represented in the desired timezone.

Here’s an example of how to do this:

What is a practical example of how the new timestamp behavior might affect my messages?

Let’s say we have an action-based Canvas that has the following content in a Message step:

1
Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!

This results in the following message:

1
Your appointment is scheduled for 2025-08-05 4:15pm, we’ll see you then!

Because no time zone is specified using Liquid, the timestamp here is in UTC.

To specify a time zone clearly, we can use Liquid time_zone filters like this:

1
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!

This results in the following message:

1
Your appointment is scheduled for 2025-08-05 8:15am, we'll see you then!

Because the America/Los Angeles time zone is specified using Liquid, the timestamp here is in PST.

The preferred time zone can also be sent in the event properties payload and used in Liquid logic:

1
2
3
4
{
  "appointment_time": "2025-08-05T08:15:30:250-0800"
  "user_timezone": "America/Los_Angeles"
}

How do context variables differ from Canvas entry properties?

If you’re participating in the Context step early access, Canvas entry properties are now included as Canvas context variables. This means you can send Canvas entry properties using the Braze API and reference them in other steps, similar to using a context variable with the Liquid snippet.

Can variables reference each other in a singular Context step?

Yes. All variables in a Context step are evaluated in a sequence, meaning you could have the following context variables set up:

This also applies across multiple Context steps. For example, imagine this sequence:

1. An initial Context step creates a variable called JobInfo with the value job_title.
2. A Message step references {{context.${JobInfo}}} and displays job_title to the user.
3. Later, a Context step updates the context variable, changing the value of JobInfo to job_description.
4. All subsequent steps that reference JobInfo now use the updated value job_description.

Context variables use their most recent value throughout the Canvas, with each update affecting all following steps that reference that variable.