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}}

​
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
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 at the project level. Available across all workflows in the project. Syntax: ${ENV:VARIABLE_NAME} Access from workflow canvas: Click the key icon in the header toolbar.

​
Development vs production values

Each variable has two values:
  • Development: Used during test runs
  • Production: Baked into published workflows

​
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 executionEntire project
Set byWorkflow runtimeProject settings
ValuesDynamicStatic (per environment)