Skip to main content
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.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.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.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.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 variablesEnvironment variables
Syntax{{var_name}}${ENV:VAR_NAME}
ScopeSingle executionProject or flow
Set byWorkflow runtimeSettings
ValuesDynamicStatic (per environment)