# System Variables

System variables are **predefined, read-only variables** that are automatically managed by the indigo.ai platform. Unlike custom variables, they **cannot be edited** using blocks like [Set Value](/getting-started/agents-workflows-and-triggers/blocks/logic-blocks/set-values-block.md) or [Capture](/getting-started/agents-workflows-and-triggers/blocks/logic-blocks/capture-block.md). Instead, they provide **real-time context** about the user, session, platform environment, and conversation history, allowing you to create more intelligent and personalized experiences.

**They are always identified by the prefix `$`, e.g. `$project_id`.**

System variables help your AI Agents:

* Identify users, channels, and environments
* React based on the time and date
* Track conversation flow and user behavior
* Dynamically adapt logic based on platform state
* Access content retrieved via document search (RAG) or current workflow status

Use them to build smarter flows, trigger conditional logic, and create more relevant, responsive interactions.

## Categories and Variables

### 🌐 Platform & Session Context

* **`$install_url`** – The URL where the widget is installed (useful for multi-site setups).
* **`$platform_endpoint`** – Base URL of the indigo.ai platform the assistant is running on. Useful when the same agent configuration is deployed across multiple environments and you need to build absolute links back to the platform (e.g. in API block payloads or external integrations).
* **`$project_id`** – Your workspace's unique identifier.
* **`$env`** – Returns `TEST` or `PRODUCTION`, depending on where the assistant is running.
* **`$lang`** – Language code set for the workspace (e.g., `en`, `it`).
* **`$detected_language`** – Language **name** detected from the user's latest message (e.g., `italian`, `english`). Falls back to the language of the website hosting the widget when detection is not conclusive.
* **`$detected_language_iso`** – ISO code of the detected language (e.g., `IT`, `EN`). Same fallback behaviour as `$detected_language`, but in code form — useful when you need to pass the language to an external API that expects an ISO 639-1 code.
* **`$fallback_language`** – Language used as a fallback when `$detected_language` cannot determine a reliable value. Defaults to the site language on the web channel.

### 👤 User Identification

Both identifiers are **persistent across sessions** for the same end user — neither rotates when a new session starts. See [Sessions](/integrating-with-our-platform-api/sessions.md) for the full session/conversation model.

* **`$user_id`** – Internal numeric ID assigned by the platform the first time a `$user_ref` interacts with the Workspace. Stable across sessions for that user.
* **`$user_ref`** – External identifier provided by the integration (Web Chat cookie, channel-native sender ID, or a value you set explicitly from your CRM). Stable across sessions and ideal for CRM matching.

### 🕒 Time & Date

* **`$timestamp`** – Current time in seconds (Unix timestamp).
* **`$date`** – Full timestamp in your workspace’s timezone (`YYYY-MM-DD hh:mm:ss`).
* **`$date_year`, `$date_month`, `$date_weekday`, `$date_hour`** – Individual date components useful for business logic (e.g., trigger actions only during working hours).

### 🧠 Conversation & Context

* **`$last_user_message`** – Content of the user's most recent message or button click.
* **`$intent`** – Last recognized intent label.
* **`$message_id`** – ID of the most recent inbound message (for tracking or referencing externally).
* **`$total_interactions`** – Number of user turns that received a bot reply in the **current session**. Returns `0` for new users before the first interaction, and resets at every new session. Useful for branching logic that depends on how far along the conversation is (e.g., show a hint after the third turn, or escalate to a human after N exchanges).
* **`$conversation`** – Plain-text rendering of the current session, capped at the last 100 user turns and their interleaved bot replies. Each line is formatted as `sender: text`, with `sender` being `user`, `bot`, or `human` (during human takeover). Useful as short-term memory in Prompt Blocks.

  ```
  user: I'd like to change my booking
  bot: Sure — what's your booking reference?
  user: ABC-123
  bot: Got it. Which date would you like to switch to?
  ```
* **`$context`** – Full plain-text rendering of the current session, with role-prefixed lines (`User: ...`, `AI Chatbot: ...`). Unlike `$conversation`, it is not capped at 100 turns. Use it when you want every turn of the current session as a prompt input.

{% hint style="warning" %}
Both `$conversation` and `$context` are **scoped to the current session** and reset every time a new session starts. They are not long-term memory across sessions. To persist facts about a user across sessions, save them as user-profile variables and re-inject them into your prompts. See [Sessions](/integrating-with-our-platform-api/sessions.md) for details.
{% endhint %}

* `$context_1` to `$context_5` – Last 1 to 5 user/agent pairs of the current session, in plain text. Useful when you need a tight context window or a lightweight short-memory.

#### Behavior of the $last\_user\_message variable

**The `last_user_message` variable has a specific behavior:**

* It is aligned with other system variables by adding the `$` prefix → **`$last_user_message`**.
* It updates automatically:
  * after each user message,
  * even after a **capture block**.
* It can be used in agents and prompts always with the latest consistent value.

**Exception in the capture block**

If a capture block collects exactly the value of **`$last_user_message`**:

* a **dummy variable** is used,
* its only purpose is to allow the capture block to work,
* the captured value is **not** used later in the flow.

### 📚 Content & Workflow State

* **`$documents`** – A list of documents retrieved from your knowledge base. Use this to:
  * Display matched sources
  * Trigger logic based on content relevance
  * Chain actions across workflows using retrieved data
* **`$current_workflow`** – Label of the currently executing workflow.
* **`$previous_workflow`** – Label of the workflow executed immediately prior to the current one.

### ✅ Utility

* **`$true`** – A constant that always returns `true`. Handy for testing or creating unconditional branches in [Condition Blocks](/getting-started/agents-workflows-and-triggers/blocks/logic-blocks/condition-block.md).

{% hint style="info" %}
It is possible to create **custom variables with the same name as a system variable**, but:

* modifying them does not update the system variable
* using them is not linked to the corresponding system variable
  {% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://guide.indigo.ai/getting-started/workspace/variables/system-variables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.