--- title: Variables in AI Agents slug: intelligent-chat-agent/variables-in-ai-agents docTags: createdAt: 2026-10-15T07:36:19.498Z --- # Variables in Bot Mandate (AI Agent) Variables let your bot remember a value, such as a phone number or an order ID, and reuse it anywhere in the conversation.  Variables already work in NLP flows. They are now available in AI Agents too, so one value can travel from an NLP flow to an AI Agent, into an API call, and back into another flow. This guide covers what variables are, how to create and use them, and a full API example. ## What are variables? A variable is a named slot that holds one value. Your bot has a single shared list of variables, used by both NLP flows and AI Agents. A variable created in one place is visible in the other, so a customer is never asked for the same detail twice. Variables can be filled from four sources: details your website or channel already knows, the customer's own answers, an NLP flow, and API responses. Once filled, a value can be used in your AI Agent instructions, sent to an API, and read by any flow. ## Create a variable in AI Agent **Option 1: ** **While writing.** In an Objective, type **/** and choose **Variable**. Search the list, or choose **+ Create new variable** at the end. **Option 2: ** **From the Available Variables section **on the RHS panel**.** Expand **Available Variables** (collapsed by default), then click **Create Variable**. The section also lists every variable in the bot, with search. | Setting | What it does | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Name | Must be unique in the bot, with no spaces, for example mobilePhone. To pre-fill it automatically, use exactly the name your website or channel sends. | | Type | String, Number, Boolean, Object or Array, as in NLP flows. | | Initial value | Optional starting value. | | Is Cached | On: the value is kept for the whole conversation and is guaranteed to carry between NLP flows and AI Agents. Off: the AI Agent still remembers it during its own conversation, but it is not guaranteed to carry across. | Variables cannot be edited or deleted after they are created, so check the name, type and Is Cached setting before you save. For anything shared between flows and agents, turn Is Cached on. ## Use variables in an AI Agent Variables can be inserted in 3 places:  - The Supervisor Objective - Type **/**, choose **Variable**, and pick one. It appears as a chip in your text. Hover over the chip to see its type, cache setting and source. Press Backspace once to remove it. In the examples below, **bold words** mark variable chips. - The AI Agent Objective - Same flow as the Supervisor Objective - Argument Description - Choose whether you want to describe the rule for the argument or mention the Variable to it. Example Objective: "Greet the customer by **firstName**. If **accountType** is premium, offer priority support." ## Fill variables automatically - **Website:** your website passes details such as mobilePhone or customerId when the chat loads (your developer can use EasyChat.init, and your Exotel contact can share the snippet). Matching variables are filled before the first message. - **Channel:** trusted details from the channel, such as the verified WhatsApp sender number, fill a variable with the matching name. - **The customer:** tell the agent to ask for a missing value and save it. - **An API response:** covered below. Text a customer types is never treated as trusted channel information. ## Share variables between NLP and AI Agents, and back Variables are read and written the same way on both sides, so values follow the customer. Example journey: 1. An NLP flow collects **orderId** and the customer taps a Quick Reply button with the action (which Transfers to AI Agent**)**. 2. The AI Agent starts with the conversation so far and the collected variables. It uses **orderId** without asking again. 3. The agent shows a button with the type **Trigger Flow**, such as "Raise a complaint". The complaint flow starts and reads **orderId** and any values the agent saved, such as **orderStatus**. | **Customer moves from** | **To** | **Cached variable** | **Non-cached variable** | | ----------------------- | -------- | ------------------- | ----------------------- | | AI Agent | AI Agent | Kept | Kept | | AI Agent | NLP flow | Kept | Not guaranteed | | NLP flow | AI Agent | Kept | Not guaranteed | | NLP flow | NLP flow | Kept | Works as it does today | ## Use variables with APIs: full example An order-tracking bot should answer "Where is my order?" using the customer's phone number and order ID, then reuse the result in a complaint flow. There are three parts:  - pass values into the call - save the response in variable - use the saved values ### Step 1. Create the variables | **Variable** | **Type** | **Is Cached** | **Filled by** | | ------------ | -------- | ------------- | ---------------------------- | | mobilePhone | String | On | Website, when the chat loads | | orderId | String | On | The customer, or an NLP flow | | orderStatus | String | On | API response | | deliveryDate | String | On | API response | | trackingUrl | String | On | API response | ### Step 2. Pass variables into the API call - In the AI Agent, open the action **Get order details**. Fill in the Action Description, request type, URL and headers as usual.  - Then list the arguments.  - For each one, the Argument Description says which variable supplies it and what to do if it is empty. | **Argument** | Argument Description (type / to insert variable chips) | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **mobile\_number** | Use **mobilePhone**. If it is missing, ask the customer for their registered mobile number, save it, then continue. | | **order\_id** | Use **orderId** if it already has a value. Otherwise ask the customer for their order ID and save it. If they want to check a different order, confirm and replace it. | The Action Description can say when to call it, for example "Use this when the customer asks about the status or delivery of an order." Headers stay simple name and value pairs. ### Step 3. Save the API response into variables Open the **Response Variable** section. Under **Complete response**, select a variable such as orderResult to keep the whole answer. Then turn on **Save response fields to variables** and add one row per value you need. Your API answers like this: \{ "status": "Shipped", "delivery": \{ "expected\_date": "18 Oct" }, "tracking": \{ "url": "https\://track.example.com/AB123" } } | Response path | Save to variable | | ----------------------- | ---------------- | | status | orderStatus | | delivery.expected\_date | deliveryDate | | tracking.url | trackingUrl | Paths can be a top-level field (status), a nested field with dots (delivery.expected\_date) or an item in a list by position (items\[0].name). If a path is not found, the conversation continues and that variable stays empty. Rows with only one side filled are not saved. ### Step 4. Use the saved values - In the AI Agent Objective: "After the Get order details action, tell the customer the order status, **orderStatus**, and the expected delivery date, **deliveryDate**. Offer the tracking link, **trackingUrl**." - In an NLP flow such as "Raise a complaint", use **orderId** and **orderStatus** in messages and API calls the same way you already use NLP variables. No extra set-up is needed, because the list is shared. ### What the customer sees - A logged-in customer asks "Where is my order?". The bot already has mobilePhone and asks only for the order ID. - The bot calls the API, saves the values, and replies: "Your order is Shipped and expected on 18 Oct. Track it here: https\://track.example.com/AB123". - The customer taps "Raise a complaint". The complaint flow starts with the order ID and status already filled in. - A second question about the same order skips the questions, because the values are kept. ## Best practices, limits and rules - Search the variable list before you create a new one, and choose names carefully because they cannot be changed yet. - Turn Is Cached on for anything shared across flows and agents. - For every API argument, say what to do when the value is missing, and whether to reuse, confirm or replace an existing value. - Save only the response fields you will reuse. | Rule | Detail | | --------------- | ---------------------------------------------------------------------------------------------------------------- | | Names | Unique in the bot. Invalid names are not accepted. Must match exactly for automatic pre-fill. | | Edit and delete | Not available yet. You can only add or remove where a variable is used. | | Scope | One shared list for the whole bot. Values belong to one customer's conversation. | | API arguments | Variable use is described in the Argument Description. There are no separate value-source controls per argument. | | Response paths | Top-level, dotted nested, and list position. | | Privacy | Values follow your normal masking and retention rules. Sensitive values such as tokens stay hidden. | ## Troubleshooting | What you see | Likely cause and fix | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Variable not pre-filled | The name does not match what your website sends, or the variable does not exist. Compare names letter by letter and create it if missing. | | Bot asks for something it should know | The variable is empty at that point. Check its source in Available Variables and add "use it, if missing ask" to the Argument Description. | | Value empty after an API call | The response path was not found, the row is incomplete, or the toggle is off. Compare the path with your API's real answer. | | Value lost between a flow and an agent | Is Cached is off. Create a new variable with it on, and use that one. | | Cannot create a variable | The name is already used or invalid, or you do not have edit access to the bot. | ## FAQs **Are NLP variables and AI Agent variables different?** No. They are one shared list. **Do I need a developer?** Only to pass website details when the chat loads. Everything else is set up on the Bot Mandate screens. **Can I keep the whole API answer?** Yes. Enter a name under Complete response, and add field rows only for values you want separately. **What if my website sends a detail I have no variable for?** It is not used. Create a variable with the same name first.