# Variables and Secrets Manage reusable values and secure credentials across your custom actions Custom actions require a Pro plan or higher. 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** | Field | Description | Example | | --------------- | -------------------------------------- | -------------------------------- | | **Name** | Variable identifier (UPPER_SNAKE_CASE) | `API_KEY` | | **Label** | Display name | `API Key` | | **Type** | Data type | `secret` | | **Value** | Actual value | `sk-abc123...` | | **Description** | Usage notes | `OpenAI API key for completions` | ### Variable Types | Type | Use Case | Storage | | ----------- | -------------------- | -------------------------- | | **string** | Text values, URLs | Plain text | | **number** | Numeric values | Plain text | | **boolean** | True/false flags | Plain text | | **secret** | API keys, passwords | Encrypted | | **url** | Base URLs, endpoints | Plain text with validation | ### Using Variables Reference variables with `{{var.VARIABLE_NAME}}` syntax: ```bash 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 ```bash {{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 | Variable | Type | Description | | ---------------------------------- | ------ | -------------------------------------------------------- | | `{{system.message_history}}` | Array | The full conversation up to this point | | `{{system.message_history_light}}` | Array | Compact conversation without tool outputs (smaller size) | | `{{system.user_id}}` | String | Unique identifier for the current user | | `{{system.timestamp}}` | String | Current time in Unix milliseconds | | `{{system.session_id}}` | String | Unique identifier for the current chat session | | `{{system.chat_url}}` | String | Direct link to the current chat session on Chipp | | `{{system.chat_transcript_url}}` | String | API endpoint URL to fetch the chat transcript as JSON | | `{{system.consumer_access_token}}` | String | OAuth access token from consumer authentication | --- ### 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:** ```json [ { "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** ```json { "model": "gpt-4", "messages": {{system.message_history}}, "temperature": 0.7 } ``` **Example: Send to your analytics backend** ```json { "event": "conversation_snapshot", "user_id": "{{system.user_id}}", "timestamp": "{{system.timestamp}}", "messages": {{system.message_history}} } ``` **Size consideration:** Message history includes the entire conversation including full tool outputs. For long chats with many tool calls, this can be several KB of data. If your target API has request size limits, consider using `{{system.message_history_light}}` instead. --- ### Message History Light **What it is:** A compact version of the conversation that preserves message structure but strips large tool outputs. **Why use it:** When you need conversation context but don't need full tool results—significantly reduces payload size for APIs with request limits. **What's included:** - All message `role` and `content` fields - Tool invocation metadata (`toolCallId`, `toolName`, `state`) **What's excluded:** - Tool `input` arguments - Tool `output` results (the largest component) - Provider metadata **Format:** ```json [ { "role": "user", "content": "Search for flights to NYC" }, { "role": "assistant", "content": "I found several options...", "toolInvocations": [ { "toolCallId": "call_abc123", "toolName": "search_flights", "state": "output-available" } ] } ] ``` **Example: Forward context to an LLM with size limits** ```json { "model": "gpt-3.5-turbo", "messages": {{system.message_history_light}}, "max_tokens": 500 } ``` **Example: Log conversation flow without bloating logs** ```json { "event": "conversation_flow", "user_id": "{{system.user_id}}", "messages": {{system.message_history_light}} } ``` **When to use each variant:** - Use `message_history` when you need complete tool results (e.g., forwarding to another AI for analysis) - Use `message_history_light` when you only need conversation flow (e.g., logging, analytics, APIs with size limits) --- ### 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** ```json { "user_id": "{{system.user_id}}", "action": "submitted_feedback", "data": "{{feedbackText}}" } ``` **Example: Add to request headers for tracking** ``` X-Chipp-User-ID: {{system.user_id}} ``` The user ID is consistent across sessions for the same user, making it useful for building user-specific features in your integrations. --- ### 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** ```json { "created_at": "{{system.timestamp}}", "user_id": "{{system.user_id}}", "note": "{{noteContent}}" } ``` **Example: Append timestamped data to Google Sheets** ```json { "values": [[ "{{system.timestamp}}", "{{system.user_id}}", "{{eventDescription}}" ]] } ``` The timestamp is a string, not a number. If your API expects a numeric timestamp, you may need to handle the conversion on your backend. --- ### Session ID **What it is:** A unique identifier (UUID) for the current chat conversation. **Why use it:** Track specific conversations, create links back to chats in your CRM, or log interactions with session-level granularity. **Format:** String (UUID, e.g., `"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`) **Example: Send session reference to CRM** ```json { "session_id": "{{system.session_id}}", "user_id": "{{system.user_id}}", "lead_status": "{{leadStatus}}" } ``` --- ### Chat URL **What it is:** A direct, clickable link to the current chat session on Chipp. **Why use it:** Include in webhook payloads so your team can click directly into the conversation from your CRM, Slack, or ticketing system. **Format:** String (e.g., `"https://app.chipp.ai/w/chat/YourApp-123/session/abc-123-def"`) **Example: Send chat link to CRM via webhook** ```json { "lead_name": "{{leadName}}", "chat_link": "{{system.chat_url}}", "notes": "{{conversationSummary}}" } ``` The chat URL allows anyone with the link to view the conversation. Use it for internal team tools like CRMs, not for public-facing integrations. --- ### Chat Transcript URL **What it is:** A URL pointing to the JSON transcript API endpoint for the current chat session. **Why use it:** Include in webhook payloads so your backend can programmatically fetch the full conversation as structured JSON. Unlike `chat_url` (which links to a web view), this URL returns machine-readable JSON when called with your app's API key. **Format:** String (e.g., `"https://app.chipp.ai/api/v1/chat/transcript/3ace0bfc-6b75-..."`) **How to use it:** Your backend receives this URL in the webhook payload, then calls it with the app's API key: ```bash curl -X GET "https://app.chipp.ai/api/v1/chat/transcript/{sessionId}" \ -H "Authorization: Bearer YOUR_APP_API_KEY" ``` **Example: Send transcript URL to CRM via webhook** ```json { "lead_name": "{{leadName}}", "chat_link": "{{system.chat_url}}", "transcript_api_url": "{{system.chat_transcript_url}}", "session_id": "{{system.session_id}}" } ``` The transcript API requires authentication with your app's API key (found in the Share tab). See the [Chat Transcript API docs](/docs/api/chat-transcript) for full details on the response format. --- ### Consumer Access Token **What it is:** An OAuth access token from consumer authentication providers like Salesforce or Okta. **Why use it:** Forward the authenticated user's credentials to external APIs in custom action headers, enabling actions that operate on behalf of the logged-in user. **Format:** String (JWT or opaque token, e.g., `"eyJhbGciOiJSUzI1NiIs..."`) **Example: Forward user credentials to Salesforce API** ``` Authorization: Bearer {{system.consumer_access_token}} ``` This variable is only available when consumer authentication is configured for your app. It will resolve to an empty string if no OAuth provider is set up. --- ### Combining System Variables System variables work alongside application variables and AI-generated parameters: ```json { "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`: ```bash Type: secret Name: API_KEY Value: sk-abc123... Type: string Name: API_KEY Value: sk-abc123... ``` ### 2. Never Expose Secrets in URLs ```bash 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: ```bash API_DOMAIN = api.dev.example.com ENVIRONMENT = development API_DOMAIN = api.example.com ENVIRONMENT = production ``` ### Multi-Tenant Setup Use variables for tenant-specific values: ```bash WORKSPACE_ID = ws_123456 TENANT_KEY = tenant_abc ORG_ID = org_789 ``` ### API Versioning Control API versions centrally: ```bash 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: ```bash 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: ```bash {{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 →](/docs/custom-actions/testing) - [View Examples →](/docs/custom-actions/examples) - [Parameter Configuration →](/docs/custom-actions/parameters)