Variables and Secrets

Upgrade to Pro →

Application Variables

Application variables are reusable values shared across all custom actions in your app.

Creating Variables

1. Open any custom action
2. Navigate to Variables tab
3. Click Add Variable

Variable Types

Using Variables

Reference variables with {{var.VARIABLE_NAME}} syntax:

https://{{var.API_DOMAIN}}/v{{var.API_VERSION}}/endpoint

Authorization: Bearer {{var.API_KEY}}
X-Workspace-ID: {{var.WORKSPACE_ID}}

{
  "api_key": "{{var.API_KEY}}",
  "environment": "{{var.ENVIRONMENT}}"
}

Variable Resolution

Variables can be used in:

• Exact match: Entire value is the variable
• Embedded: Variable within a larger string

{{var.API_KEY}}

Bearer {{var.API_KEY}}
https://{{var.DOMAIN}}/api/v{{var.VERSION}}

System Variables

System variables give your custom actions access to runtime context—information about the current conversation, user, and timing that the platform automatically provides. Unlike application variables (which you define), system variables are built-in and always available.

When to use system variables:

• Forward conversation context to external AI services
• Track which user triggered an action for audit logs
• Add timestamps to records you create via API

Available System Variables

Message History

What it is: The complete conversation between the user and your AI agent, formatted for the OpenAI Chat Completions API.

Why use it: Forward conversation context to another AI service, analyze sentiment, or log interactions to your backend.

Format:

[
  {
    "role": "system",
    "content": "You are a helpful assistant."
  },
  {
    "role": "user",
    "content": "What's the weather in NYC?"
  },
  {
    "role": "assistant",
    "content": "I'll check the weather for you."
  }
]

Available roles:

• system — Initial instructions (if configured)
• user — Messages from the human
• assistant — Responses from your AI agent

Example: Forward to OpenAI for additional processing

{
  "model": "gpt-4",
  "messages": {{system.message_history}},
  "temperature": 0.7
}

Example: Send to your analytics backend

{
  "event": "conversation_snapshot",
  "user_id": "{{system.user_id}}",
  "timestamp": "{{system.timestamp}}",
  "messages": {{system.message_history}}
}

User ID

What it is: A unique identifier for the person chatting with your agent.

Why use it: Track actions per user, create user-specific records, or implement per-user rate limiting in your backend.

Format: String (e.g., "user_abc123" or "clx9f2k...")

Example: Create a user-specific record

{
  "user_id": "{{system.user_id}}",
  "action": "submitted_feedback",
  "data": "{{feedbackText}}"
}

Example: Add to request headers for tracking

X-Chipp-User-ID: {{system.user_id}}

Timestamp

What it is: The current time when the action executes, as a Unix timestamp in milliseconds.

Why use it: Add "created at" timestamps to records, implement time-based logic, or track when actions were triggered.

Format: String containing milliseconds since Unix epoch (e.g., "1713552052000")

Example: Log when a record was created

{
  "created_at": "{{system.timestamp}}",
  "user_id": "{{system.user_id}}",
  "note": "{{noteContent}}"
}

Example: Append timestamped data to Google Sheets

{
  "values": [[
    "{{system.timestamp}}",
    "{{system.user_id}}",
    "{{eventDescription}}"
  ]]
}

Combining System Variables

System variables work alongside application variables and AI-generated parameters:

{
  "api_key": "{{var.API_KEY}}",
  "messages": {{system.message_history}},
  "metadata": {
    "user": "{{system.user_id}}",
    "timestamp": "{{system.timestamp}}",
    "query": "{{searchQuery}}"
  }
}

In this example:

• {{var.API_KEY}} — Your stored API key (application variable)
• {{system.message_history}} — Conversation context (system variable)
• {{system.user_id}} — Current user (system variable)
• {{system.timestamp}} — Current time (system variable)
• {{searchQuery}} — Value the AI determines from context (AI-generated)

Security Best Practices

1. Use Secret Type for Sensitive Data

Mark sensitive values as secret:

Type: secret
Name: API_KEY
Value: sk-abc123...

Type: string
Name: API_KEY
Value: sk-abc123...

2. Never Expose Secrets in URLs

https://api.example.com/auth?key={{var.API_KEY}}

Headers:
  Authorization: Bearer {{var.API_KEY}}

3. Scope Variables Appropriately

Variables are scoped to applications, not global:

• Each app has its own variable namespace
• No cross-app variable access
• User-specific isolation

4. Rotate Keys Regularly

Update variable values without changing actions:

1. Go to Variables tab
2. Update the value
3. All actions automatically use new value

Common Patterns

Environment Configuration

Manage different environments with variables:

API_DOMAIN = api.dev.example.com
ENVIRONMENT = development

API_DOMAIN = api.example.com
ENVIRONMENT = production

Multi-Tenant Setup

Use variables for tenant-specific values:

WORKSPACE_ID = ws_123456
TENANT_KEY = tenant_abc
ORG_ID = org_789

API Versioning

Control API versions centrally:

API_VERSION = v2
SCHEMA_VERSION = 2024-01-15
CLIENT_VERSION = 1.2.3

Variable Management

Viewing Variable Usage

See which actions use a variable:

• Green dot indicates usage in current action
• Check before deleting variables
• Update impacts all actions

Import/Export

When exporting actions to collections:

• Variable definitions included
• Variable values NOT exported
• Recipients set their own values

Testing Variables

Use the action tester to verify resolution:

URL: {{var.BASE_URL}}/users
Header: Bearer {{var.API_KEY}}

URL: https://api.example.com/users
Header: Bearer sk-abc123...

AI Placeholders

Simple placeholders without namespace become AI-generated:

{{userId}}          # AI determines user ID
{{searchQuery}}     # AI creates search term
{{emailSubject}}    # AI writes subject

{{var.API_KEY}}     # Application variable
{{system.user_id}}  # System variable

Troubleshooting

Variables Not Resolving

1. Check Variable Name

   • Case-sensitive
   • No spaces in names
   • Correct namespace (var. or system.)

2. Check Variable Definition

   • Variable exists in Variables tab
   • Has a value set
   • Correct variable type

3. Check Syntax

   • Double curly braces: {{}}
   • No extra spaces: {{var.NAME}}
   • Correct namespace prefix

Secret Values Not Visible

Secrets are encrypted and never shown after saving:

• ✓ This is expected behavior
• ✓ Update value to change
• ✓ Use tester to verify working

Cross-Action Dependencies

Variables are resolved per action:

• Define once, use everywhere
• Changes apply immediately
• No action rebuild required

Next Steps

• Test Your Actions →
• View Examples →
• Parameter Configuration →