Variables and context

Every workflow execution maintains data in four organized namespaces. This data flows between nodes, gets updated by user interactions, and drives workflow logic.

Data structure

vars namespace - User-defined variables

Read/write access
Store custom data, user responses, API results
Persists throughout workflow execution

system namespace - System-managed data

Read-only access
Workflow metadata, timing, execution details
Automatically maintained by the platform

context namespace - Contextual information

Mostly read-only (set at workflow start)
Channel info, user details, trigger context
Provides execution environment details

metadata namespace - Request metadata

Read-only access
API request details, timestamps, caller info
Available for API-triggered workflows

Initial data

WhatsApp trigger workflow starts with:

# System variables
{{system.trigger_type}}                # "inbound_message"
{{system.workflow_id}}                 # Workflow UUID
{{system.started_at}}                  # ISO timestamp

# WhatsApp config data
{{system.whatsapp_config.id}}          # WhatsApp config ID
{{system.whatsapp_config.phone_number_id}}  # Meta phone number ID
{{system.whatsapp_config.display_phone_number}}  # Host phone number (formatted)
{{system.whatsapp_config.display_phone_number_normalized}}  # Host phone (normalized)
{{system.whatsapp_config.business_account_id}}  # WhatsApp Business Account ID
{{system.whatsapp_config.name}}        # Config name
{{system.whatsapp_config.kind}}        # "production" or "sandbox"

# Customer data (when WhatsApp config is linked to a Customer)
{{system.customer.id}}                 # Customer UUID
{{system.customer.external_customer_id}}  # Your external customer ID
{{system.customer.name}}               # Customer name

# Context variables
{{context.phone_number}}               # User's phone number "+1234567890"
{{context.whatsapp_business_scoped_user_id}}  # User BSUID (may be null)
{{context.whatsapp_parent_business_scoped_user_id}}  # Parent BSUID (may be null)
{{context.whatsapp_username}}          # WhatsApp username (may be null)
{{context.channel}}                    # "whatsapp"
{{context.conversation_id}}            # WhatsApp conversation ID

# Contact data
{{context.contact.id}}                 # Contact UUID (when known)
{{context.contact.wa_id}}              # Normalized WhatsApp ID
{{context.contact.business_scoped_user_id}}  # User BSUID (may be null)
{{context.contact.parent_business_scoped_user_id}}  # Parent BSUID (may be null)
{{context.contact.username}}           # WhatsApp username (may be null)
{{context.contact.name}}               # Contact name (or phone number fallback)
{{context.contact.profile_name}}       # WhatsApp profile name (may be null)
{{context.contact.display_name}}       # Display name (may be null)

# Workflow variables
{{last_user_input}}                    # Initial message content

API trigger workflow starts with:

# System variables
{{system.trigger_type}}                     # "api_call"
{{system.tracking_id}}                      # Unique execution ID
{{system.api_key_id}}                       # API key used
{{system.workflow_id}}                      # Workflow UUID
{{system.trigger_whatsapp_config_id}}       # WhatsApp config ID (if provided in request)

# Context variables
{{context.phone_number}}                    # From request (normalized)
{{context.channel}}                         # "api"

# Custom variables (from API request)
{{your_variable}}                           # From variables object
{{another_variable}}                        # From variables object

# Metadata
{{metadata.request_ip}}                     # Caller IP
{{metadata.request_timestamp}}              # Request time

WhatsApp event trigger workflow starts with:

# System variables
{{system.trigger_type}}                     # "whatsapp_event"
{{system.observer_mode}}                    # true
{{system.allow_outbound}}                   # false
{{system.workflow_id}}                      # Workflow UUID
{{system.started_at}}                       # ISO timestamp

# Event data
{{system.event.type}}                         # Event type (e.g. "whatsapp.message.sent")
{{system.event.payload}}                      # Full event payload

# Conversation snapshot
{{system.event.conversation.id}}              # Conversation ID
{{system.event.conversation.phone_number}}    # Customer phone "+1234567890"
{{system.event.conversation.business_scoped_user_id}}  # User BSUID (may be null)
{{system.event.conversation.parent_business_scoped_user_id}}  # Parent BSUID (may be null)
{{system.event.conversation.username}}        # WhatsApp username (may be null)
{{system.event.conversation.status}}          # "active" or "ended"
{{system.event.conversation.phone_number_id}} # Meta phone number ID

# Message snapshot (for message events)
{{system.event.message.id}}                   # WhatsApp message ID
{{system.event.message.type}}                 # "text", "image", "video", etc.
{{system.event.message.timestamp}}            # Unix timestamp
{{system.event.message.from_user_id}}         # Inbound BSUID when available
{{system.event.message.to_user_id}}           # Outbound BSUID when available
{{system.event.message.username}}             # WhatsApp username when available
{{system.event.message.text.body}}            # Message text (when applicable)
{{system.event.message.kapso.direction}}      # "inbound" or "outbound"
{{system.event.message.kapso.status}}         # Message status

When phone_number_id is provided in the API request:

Automatically stored in {{system.trigger_whatsapp_config_id}}
Phone number normalized and stored in {{context.phone_number}}
Guarantees all messages use the same WhatsApp configuration

Accessing variables

Use {{variable_name}} syntax in messages, templates, and AI fields to access variables. Direct access (looks in vars namespace):

Hello {{customer_name}}

Explicit namespace access:

Your number is {{context.phone_number}}
Workflow started at {{system.started_at}}

Resume tracking

After a workflow resumes from a wait step, these system variables are available:

{{system.last_resume.reason}}          # "user_input" or "timeout"
{{system.last_resume.at}}              # When workflow resumed (ISO timestamp)
{{system.last_resume.step_id}}         # Step ID where workflow was waiting
{{system.last_resume.step_identifier}} # Step identifier where workflow was waiting

Use {{system.last_resume.reason}} to detect if a wait step timed out:

// In a decide node or function
if (system.last_resume.reason === "timeout") {
  // Handle timeout scenario
} else {
  // Handle normal user response
}

While a wait step with timeout is active, these variables are available:

{{system.pending_timeout.job_id}}         # Background job ID
{{system.pending_timeout.timeout_seconds}} # Timeout duration
{{system.pending_timeout.scheduled_for}}   # When timeout will fire (ISO timestamp)
{{system.pending_timeout.step_id}}        # Step the timeout applies to

Data flow between nodes

Send nodes (SendTextNode, SendTemplateNode, SendInteractiveNode)

Read: All variables for message content and parameters
Write: Nothing

Wait for response node

Read: Nothing (just waits)
Write: Sets {{last_user_input}} when user responds (not set on timeout). Sets {{system.last_resume}} metadata on resume. Sets {{system.pending_timeout}} when timeout is scheduled

Decide node

Read: All variables to evaluate conditions
Write: Nothing (just routes workflow)

Function node

Read: Sends entire execution context to function
Write: Can set variables via save_response_to or function return

Agent node

Read: Full access to all variables via get_variable tool
Write: Can set any variable via save_variable tool

Handoff node

Read: Nothing
Write: Nothing (just stops execution)

Variable naming

Use lowercase with underscores: user_name, order_total
Be descriptive: last_user_input not input
Avoid system reserved names: flow_id, started_at

Environment variables

Store sensitive values like API keys as environment variables. They use a distinct syntax to avoid conflicts with workflow variables. Syntax: ${ENV:VARIABLE_NAME} Each variable has two values:

Development: Used during test runs
Production: Baked into published workflows

Scopes

Project-level — Available across all workflows in the project. Access: Project Settings → Environment variables (or click the key icon in the workflow canvas toolbar). Flow-level — Scoped to a single workflow. Flow-level variables override project-level variables with the same key. Access: Workflow Settings → Environment variables.

Example usage

In webhook URLs:

https://api.example.com/v1/data?key=${ENV:API_KEY}

In agent MCP headers:

Authorization: Bearer ${ENV:MCP_API_KEY}

Key differences from workflow variables

	Workflow variables	Environment variables
Syntax	`{{var_name}}`	`${ENV:VAR_NAME}`
Scope	Single execution	Project or flow
Set by	Workflow runtime	Settings
Values	Dynamic	Static (per environment)

Getting started

Workflows

Functions

Workflows

Workflow Triggers

Functions

WhatsApp Conversations

Data structure

Initial data

Accessing variables

Resume tracking

Data flow between nodes

Variable naming

Environment variables

Scopes

Example usage

Key differences from workflow variables

​Data structure

​Initial data

​Accessing variables

​Resume tracking

​Data flow between nodes

​Variable naming

​Environment variables

​Scopes

​Example usage

​Key differences from workflow variables

Data structure

Initial data

Accessing variables

Resume tracking

Data flow between nodes

Variable naming

Environment variables

Scopes

Example usage

Key differences from workflow variables