Contexto
Los pasos de Contexto te permiten crear y actualizar una o más variables para un usuario a medida que avanza por un Canvas. Por ejemplo, si tienes un Canvas que gestiona descuentos de temporada, puedes usar una variable de contexto para almacenar un código de descuento diferente cada vez que un usuario entra en el Canvas.

La disponibilidad de Contexto de Canvas varía según el espacio de trabajo. Si Contexto no aparece en el menú de pasos de Canvas y el menú de personalización muestra Canvas Entry Properties en lugar de Variables de contexto, usa canvas_entry_properties para los datos de entrada. Ponte en contacto con tu director de cuentas si necesitas acceso a Contexto de Canvas.
Cómo funciona

Los pasos de Contexto te permiten crear y utilizar datos temporales mientras un usuario recorre un Canvas concreto. Estos datos solo existen dentro de ese recorrido del Canvas y no persisten en otros Canvas ni fuera de la sesión.
Las variables de contexto solo existen para ese recorrido concreto del Canvas. No modifican el perfil del usuario de forma permanente ni aparecen en otros Canvas. Por eso son ideales para información temporal que solo es relevante para una Campaign o un flujo de trabajo específicos.

Para consultar una referencia completa sobre las variables de contexto, incluidos los tipos de datos, su uso y las prácticas recomendadas, consulta la referencia de variables de contexto.
Dentro de un paso de Contexto, puedes definir o actualizar hasta 10 variables de contexto. Estas variables pueden usarse para personalizar retrasos, segmentar usuarios de forma dinámica y enriquecer la mensajería en todo el Canvas. Por ejemplo, podrías crear una variable de contexto para la hora programada del vuelo de un usuario y, luego, usarla para establecer retrasos personalizados y enviar recordatorios.
Puedes establecer variables de contexto de dos maneras:
- Al entrar en el Canvas: Las propiedades del evento personalizado o del desencadenante de la API se rellenan automáticamente como variables de contexto.
- En un paso de Contexto: Define o actualiza variables de contexto manualmente añadiendo un paso de Contexto.
Cada variable de contexto requiere un nombre, un tipo de datos y un valor (establecido mediante Liquid o la herramienta Añadir personalización). Una vez definidas, puedes hacer referencia a las variables de contexto en todo el Canvas utilizando Liquid, como {{context.${flight_time}}}. En el campo Nombre de la variable de contexto, también puedes introducir el nombre de la variable de contexto o seleccionarlo en el desplegable del editor del paso. Para más detalles, consulta la referencia de variables de contexto.
Cada entrada en el Canvas vuelve a definir las variables de contexto en función de los datos de entrada más recientes y de la configuración del Canvas, lo que permite a los usuarios tener varios recorridos activos, cada uno con su propio contexto. Por ejemplo, si un cliente tiene dos próximos vuelos, tendrá dos estados de recorrido distintos ejecutándose simultáneamente, cada uno con sus propias variables de contexto específicas del vuelo, como la hora de salida y el destino. Así puedes enviar recordatorios personalizados sobre su vuelo de las 14:00 a Nueva York y, al mismo tiempo, enviar otras actualizaciones sobre su vuelo de las 8:00 a Los Ángeles de mañana, de modo que cada mensaje siga siendo relevante para la reserva concreta.
Procesamiento de usuarios y procesamiento por lotes
Los pasos de Contexto procesan a los usuarios por lotes para optimizar el rendimiento. Cuando los usuarios entran en un paso de Contexto, Braze los procesa en lotes de 1000 usuarios de forma predeterminada. Estos lotes se procesan en paralelo, pero dentro de cada lote, los usuarios se procesan de forma secuencial.
Esto significa:
Ejemplo: Si 3500 usuarios entran en un paso de Contexto con contenido conectado que tarda 650 ms por usuario:
- Braze crea 4 lotes de usuarios (1000, 1000, 1000 y 500 usuarios en este ejemplo).
- Cada lote procesa a los usuarios de forma secuencial, por lo que un lote de 1000 usuarios tarda aproximadamente 10,8 minutos (650 segundos; 1000 × 650 ms).
- Los lotes terminan en momentos distintos, así que los usuarios van pasando al siguiente paso de forma escalonada a medida que termina su lote.
- Los primeros usuarios pueden llegar al siguiente paso varios minutos antes que los últimos, según el tamaño del lote y los tiempos de respuesta del contenido conectado.
Sin contenido conectado, los pasos de Contexto se procesan mucho más rápido, porque no hay que esperar llamadas a API externas.
Consideraciones
- Puedes definir hasta 10 variables de contexto por paso de Contexto.
- Cada variable requiere un nombre único (solo letras, números y guiones bajos, hasta 100 caracteres).
- El tamaño total de todas las variables de un paso no puede superar los 50 KB.
- Las variables que se pasan mediante desencadenantes de API comparten el mismo espacio de nombres que las creadas en los pasos de Contexto; si redefines una variable en un paso de Contexto, se sobrescribe el valor de la API.
Para más detalles y usos avanzados, consulta la referencia de variables de contexto.
Crear un paso de contexto

Si Context Variable está disponible como filtro en tu espacio de trabajo, no necesitas un paso de contexto para hacer referencia a las propiedades del evento desencadenante en los pasos de rutas de audiencia o división de decisiones. Puedes hacer referencia a las propiedades directamente en los grupos de filtros. Asegúrate de seleccionar el tipo de datos correcto.
Paso 1: Añade un paso
Añade un paso a tu Canvas y luego arrastra y suelta el componente desde la barra lateral, o selecciona el botón más y selecciona Contexto.
Paso 2: Define las variables

Puedes definir hasta 10 variables de contexto para cada paso de contexto.
Para definir una variable de contexto:
- Asigna un nombre a tu variable de contexto.
- Selecciona un tipo de datos.
- Escribe una expresión de Liquid manualmente o utiliza Añadir personalización para crear un fragmento de código de Liquid a partir de atributos existentes.
- Selecciona Vista previa para comprobar el valor de tu variable de contexto.
- (Opcional) Para añadir más variables, selecciona Añadir variable de contexto y repite los pasos 1-4.
- Cuando termines, selecciona Hecho.
Ahora puedes usar tu variable de contexto en cualquier lugar donde uses Liquid, como en los pasos de mensaje y de actualización de usuario, seleccionando Añadir personalización. En el campo Nombre de la variable de contexto, también puedes introducir el nombre de la variable de contexto o seleccionarlo en el desplegable del editor de pasos. Para ver una guía completa, consulta la referencia de variables de contexto.

Cuando hagas referencia a variables de contexto, utiliza siempre el formato {{context.${variable_name}}}.
Filtros de variables de contexto
Puedes crear filtros utilizando variables de contexto en los pasos de Rutas de audiencia y División de decisiones.
Para dirigir a los usuarios en función de la respuesta de un paso de agente, añade el paso de agente antes de tu paso de Rutas de audiencia o de División de decisiones. El paso de agente almacena su salida en el contexto del Canvas, que puedes evaluar con filtros de variables de contexto en esos pasos de ramificación.
Si el agente devuelve un objeto y quieres filtrar por una propiedad anidada, introduce la ruta en el campo Nombre de la variable de contexto utilizando la notación de puntos en lugar de solo el nombre de la variable de nivel superior (por ejemplo, intent_agent.persona cuando persona está anidada en intent_agent).

La lista Nombre de la variable de contexto incluye variables de los pasos de contexto y de los pasos de agente. Para una propiedad de entrada en Canvas, escribe su nombre y selecciona Utilizar “ENTRY_PROPERTY_NAME“. Sustituye ENTRY_PROPERTY_NAME por el nombre de la propiedad de entrada que escribiste. Para una propiedad anidada, utiliza la notación de puntos, como order.total.
Para obtener información sobre la configuración de filtros, la lógica de comparación y ejemplos avanzados, consulta la referencia de variables de contexto.

Elegir entre los tipos de filtro “Día del año” y “Hora”: al filtrar variables de contexto que contienen fechas, elige el tipo de comparación correcto en función de si la fecha se repite cada año. Usa “Día del año” solo cuando el año no esté incluido en el valor que produce la variable de contexto.
- Usa “Día del año” cuando la fecha se repita cada año (por ejemplo, cumpleaños, aniversarios o fiestas como Navidad). Este tipo de comparación calcula en función del día del año (1-365/366), ignorando el componente del año.
- Usa “Hora” cuando la fecha sea una fecha absoluta que no se repita (por ejemplo, fechas de finalización de contratos, fechas de citas o fechas de renovación de suscripciones). Este tipo de comparación calcula basándose en la marca de tiempo completa, incluido el año.
El uso de “Día del año” para fechas absolutas puede producir resultados incorrectos o inesperados, ya que el cálculo ignora el componente del año. Por ejemplo, si comparas la fecha de vencimiento de un contrato futuro en abril para determinar si está dentro de los 63 días, el uso de “Día del año” puede hacer que las fechas coincidan incorrectamente, ya que solo compara los números de los días (119 frente a 359) sin tener en cuenta que, en realidad, quedan 188 días para abril.
Vista previa de las rutas de usuario
Te recomendamos probar y obtener una vista previa de tus rutas de usuario para asegurarte de que tus mensajes se envían a la audiencia correcta y de que las variables de contexto se evalúan con los resultados esperados.

Si obtienes la vista previa de tu Canvas en la sección Vista previa y envío de prueba del editor, la marca de tiempo de la vista previa del mensaje de prueba no se estandariza a UTC, porque este panel genera las vistas previas como cadenas. Esto significa que, si un Canvas está configurado para aceptar un objeto time, la vista previa del mensaje no reflejará con precisión lo que ocurre cuando el Canvas está en vivo. Para probar tu Canvas con la mayor precisión posible, te recomendamos obtener una vista previa de las rutas de usuario.
Asegúrate de tener en cuenta los escenarios comunes que generan variables de contexto no válidas. Al obtener la vista previa de tu ruta de usuario, puedes ver los resultados de los pasos de retraso personalizados que usan variables de contexto, así como cualquier comparación en pasos de audiencia o de decisión que relacione a los usuarios con variables de contexto.
Si la variable de contexto es válida, puedes hacer referencia a ella en todo tu Canvas. Sin embargo, si la variable de contexto no se creó correctamente, los pasos posteriores de tu Canvas tampoco funcionarán correctamente. Por ejemplo, si creas un paso de Contexto para asignar a los usuarios una hora de cita y estableces como valor de la hora de la cita una fecha pasada, el correo electrónico de recordatorio de tu paso de Mensaje no se enviará.
Convertir cadenas de contenido conectado a JSON
Cuando realizas una llamada de contenido conectado en un paso de contexto, el JSON devuelto por la llamada se evalúa como un tipo de datos de cadena para mantener la coherencia y evitar errores. Si quieres convertir esta cadena en JSON, hazlo con as_json_string. Por ejemplo:
{% connected_content http://example.com :save product %}
{{ product | as_json_string }}
Solución de problemas
Variables de contexto no válidas
Una variable de contexto se considera no válida cuando:
- Falla una llamada a un contenido conectado incrustado.
- La expresión de Liquid devuelve, en tiempo de ejecución, un valor que no coincide con el tipo de datos o que está vacío (null).
- La expresión de Liquid llama a
{% abort_message() %}.
Por ejemplo, si el tipo de datos de la variable de contexto es Número, pero la expresión de Liquid devuelve una cadena, la variable no es válida.
En estas circunstancias:
- El usuario avanza al siguiente paso.
- El análisis del paso en Canvas lo contabiliza como No actualizado.
Durante la solución de problemas, supervisa la métrica No actualizado para comprobar que tu variable de contexto se actualiza correctamente. Si la variable de contexto no es válida, tus usuarios pueden continuar en tu Canvas más allá del paso Contexto, pero es posible que no cumplan los requisitos para pasos posteriores.
Consulta Tipos de datos para ver configuraciones de ejemplo de cada tipo de datos.
También puedes omitir una variable de contexto a propósito con abort_message. Consulta Uso de abort_message en una variable de contexto.
Uso de abort_message en una variable de contexto
Puedes usar la etiqueta de Liquid abort_message en el valor de una variable de contexto para omitir esa variable en algunos usuarios. En un paso Contexto, abort_message solo afecta a la variable en la que se encuentra. No detiene el paso ni hace que el usuario salga del Canvas.
Cuando el Liquid de una variable de contexto llama a abort_message para un usuario:
- La variable no se establece para ese usuario. Si un paso Contexto anterior ya había establecido esta variable, el usuario conserva ese valor anterior.
- Las demás variables del paso se siguen evaluando y estableciendo.
- Las variables posteriores del mismo paso que hacen referencia a esta variable no reciben un valor nuevo de ella.
- El usuario avanza al siguiente paso.
- El análisis del paso en Canvas contabiliza la variable como No actualizado.
Por ejemplo, esta variable se establece en true para los usuarios de Francia y se omite para todos los demás:
{% if ${country} == "France" %}
true
{% else %}
{% abort_message("Not in France") %}
{% endif %}
Cuando previsualizas las rutas de usuario, una variable omitida aparece como “variable_name no se actualizó porque la lógica de Liquid desencadenó una cancelación”.
Si los pasos posteriores dependen de esta variable, ten en cuenta a los usuarios que no la tienen establecida. Por ejemplo, puedes dirigirlos con un paso Rutas de audiencia.

Las cancelaciones del paso Contexto no se registran en el Registro de actividad de mensajes, y el motivo que pasas a abort_message no se muestra.
Retrasos en el envío con contenido conectado
Todos los usuarios de un lote se procesan antes de que avance cualquiera de ellos. Una vez completado el procesamiento del lote, los usuarios correctos pasan al siguiente paso, mientras que los usuarios fallidos se reintentan por separado: los usuarios correctos no esperan a que los reintentos tengan éxito para avanzar.
Comportamiento de los reintentos
Las llamadas de contenido conectado en un Canvas solo se reintentan cuando la llamada incluye :retry.
- Pasos Contexto y Actualización de usuario: Braze reintenta la llamada de contenido conectado a nivel de paso (hasta cinco veces). Si todos los reintentos fallan, el usuario sale del Canvas.
- Pasos Mensaje: El contenido conectado con
:retrysigue usando la canalización de mensajería. Los destinatarios se retrasan en la cola de envío mientras Braze reintenta la llamada hasta cinco veces. Si todos los reintentos fallan, el mensaje se cancela y el usuario avanza al siguiente paso.
En los pasos Contexto y Actualización de usuario, ciertos errores de paso reintentables (como un fallo al obtener un código promocional o un error inesperado del paso) pueden desencadenar reintentos adicionales a nivel de paso con retirada exponencial (aproximadamente 13 veces) antes de que Braze haga salir al usuario del Canvas.
Para obtener más información sobre la etiqueta :retry, consulta Reintentos de contenido conectado.
El tiempo que se tarda en procesar a todos los usuarios en un paso Contexto depende de:
- El número de usuarios que entran en el paso
- Si se usa contenido conectado (y su tiempo de respuesta)
- El tamaño del lote (1000 usuarios por lote de forma predeterminada)
Si tu endpoint de contenido conectado tiene límites de velocidad, ten en cuenta que los pasos Contexto procesan a los usuarios de forma secuencial dentro de cada lote, lo que ayuda a respetar los límites de velocidad de forma natural. Sin embargo, varios lotes se procesan en paralelo, así que asegúrate de que tu endpoint pueda gestionar solicitudes simultáneas de varios lotes.
Coherencia de zona horaria
En los espacios de trabajo con Contexto de Canvas, todas las propiedades del evento de marca de tiempo predeterminadas en los Canvas basados en acciones están en UTC. Esto se aplica tanto si el Canvas usa un paso de Contexto como si no.

En todos los casos, te recomendamos encarecidamente usar los filtros time_zone de Liquid para que las marcas de tiempo se representen en la zona horaria que quieras. Puedes consultar esta pregunta frecuente para ver un ejemplo.
Preguntas frecuentes
¿Cómo afecta el Contexto de Canvas a las marcas de tiempo?
En los espacios de trabajo con Contexto de Canvas:
- Todas las marcas de tiempo con un tipo datetime procedentes de propiedades del evento desencadenante en Canvas basados en acciones están en UTC.
- Este cambio afecta a todos los Canvas basados en acciones, tanto si el Canvas concreto utiliza un paso Contexto como si no.
¿Cuál es el motivo de este cambio?
Este cambio forma parte de un esfuerzo más amplio para crear una experiencia más predecible y coherente al editar pasos en Canvas y mensajes.
¿Afecta este cambio a los Canvas desencadenados por API o programados?
No.
¿Afecta este cambio a las propiedades de entrada en Canvas?
Sí, afecta a canvas_entry_properties si la canvas_entry_property se utiliza en un Canvas basado en acciones y el tipo de propiedad es time. En todos los casos, te recomendamos utilizar los filtros time_zone de Liquid para que las marcas de tiempo se representen en la zona horaria deseada.
Aquí tienes un ejemplo de cómo hacerlo:
| Liquid en el paso Mensaje | Salida | ¿Es esta la forma correcta de representar zonas horarias en Liquid? |
|---|---|---|
{{canvas_entry_properties.${timestamp_property}}} |
2025-08-05T08:15:30:250-0800 |
No |
{{canvas_entry_properties.${timestamp_property} | date: "%Y-%m-%d %l:%M %p"}} |
2025-08-05 4:15pm |
No |
{{canvas_entry_properties.${timestamp_property} | time_zone: "America/Los_Angeles" | date: "%Y-%m-%d %l:%M %p"}} |
2025-08-05 8:15am |
Sí |
¿Cuál es un ejemplo práctico de cómo el nuevo comportamiento de las marcas de tiempo podría afectar a mis mensajes?
Supongamos que tenemos un Canvas basado en acciones con el siguiente contenido en un paso Mensaje:
Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!
Esto da como resultado el siguiente mensaje:
Your appointment is scheduled for 2025-08-05 4:15 PM, we’ll see you then!
Como no se especifica ninguna zona horaria con Liquid, la marca de tiempo está en UTC.
Para especificar claramente una zona horaria, podemos utilizar los filtros time_zone de Liquid de esta forma:
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!
Esto da como resultado el siguiente mensaje:
Your appointment is scheduled for 2025-08-05 8:15 AM, we'll see you then!
Como la zona horaria America/Los Angeles se especifica con Liquid, la marca de tiempo está en PST.
La zona horaria preferida también puede enviarse en la carga útil de propiedades del evento y utilizarse en la lógica de Liquid:
{
"appointment_time": "2025-08-05T08:15:30:250-0800"
"user_timezone": "America/Los_Angeles"
}
¿En qué se diferencian las variables de contexto de las propiedades de entrada en Canvas?
Las propiedades de entrada en Canvas se incluyen como variables de contexto de Canvas. Esto significa que puedes enviar propiedades de entrada en Canvas mediante la API de Braze y hacer referencia a ellas en otros pasos, de forma similar a usar una variable de contexto con el fragmento de código de Liquid.
¿Pueden las variables hacer referencia unas a otras en un único paso Contexto?
Sí. Todas las variables de un paso Contexto se evalúan en secuencia, lo que significa que podrías tener configuradas las siguientes variables de contexto:
| Variable de contexto | Valor | Descripción |
|---|---|---|
favorite_cuisine |
{{custom_attribute.${Favorite Cuisine}}} |
El tipo de cocina favorito de un usuario. |
promo_code |
EATFRESH |
El código de descuento disponible para un usuario. |
personalized_message |
"Enjoy a discount of" {{context.${promo_code}}} "on delivery from your favorite" {{context.${favorite_cuisine}}} restaurants!" |
Un mensaje personalizado que combina las variables anteriores. En un paso Mensaje, podrías utilizar el fragmento de código de Liquid {{context.${personalized_message}}} para hacer referencia a la variable de contexto y entregar un mensaje personalizado a cada usuario. También podrías utilizar un paso Contexto para guardar el valor del código de promoción y usarlo como plantilla en otros pasos a lo largo de un Canvas. |
Esto también se aplica a varios pasos Contexto. Por ejemplo, imagina esta secuencia:
- Un paso Contexto inicial crea una variable llamada
JobInfocon el valorjob_title. - Un paso Mensaje hace referencia a
{{context.${JobInfo}}}y muestrajob_titleal usuario. - Más adelante, un paso Contexto actualiza la variable de contexto y cambia el valor de
JobInfoajob_description. - Todos los pasos posteriores que hacen referencia a
JobInfoutilizan ahora el valor actualizadojob_description.
Las variables de contexto utilizan su valor más reciente a lo largo de todo el Canvas, y cada actualización afecta a todos los pasos siguientes que hacen referencia a esa variable.