> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gnani.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamic Variables & Dynamic Messages

> Personalize your agent's responses

The **Dynamic Variables** feature in Gnani Agents allows you to insert placeholders in your bot’s **Greeting Message** or **System Prompt**, which get replaced with real-time data during a call.\
These variables are populated from an API configured in the **Dynamic Messages** settings.

***

### **Dynamic Messages Overview**

When you turn on **Dynamic Messages** in the agent settings, you will be asked to configure:

* **Method** — `GET` or `POST` (required)
* **API URL** — endpoint that returns the dynamic message and user context (required)
* **Headers** — optional key–value pairs (if applicable)

This API request will contain:

1. A **unique variable** (for example, the customer’s phone number).
2. Return:
   * **User context** — any key–value data needed for the call (e.g., `due_amount`, `customer_type`, `due_date`) in JSON format.
   * **Constructed greeting message** — the exact greeting to be used for that specific call.

⚠ **Important:**

* The Greeting Message configured in the agent will be **overridden** by the message returned from your API when Dynamic Messages is on.
* The API call has a **10-second timeout**. If it doesn’t respond in time, the call will fail.
* Currently, Gnani Agents does **not** have a built-in campaign manager. This feature is available only by contacting us to enable it for your deployed bot. We’re working to make it self-service soon.
* The **unique variable** can be something other than the phone number.

***

### **Using Dynamic Variables in the System Prompt**

Dynamic variables can also be used inside the **System Prompt**, but:

1. **Dynamic Messages** must be turned on.
2. In the **Customize** section, enable **Pre-Call Variables**.
3. Add the required variables you plan to use in your System Prompt.

**Testing behavior:**

* During test calls, you’ll be prompted to manually enter the test variable values.
* In production, these will be **auto-filled** from your Dynamic Messages API response.

***

### **Where Dynamic Variables Can Be Used**

✅ **Supported:**

* Greeting Message (overridden by API response)
* System Prompt

❌ **Not Supported:**

* Ending Message

***

### **API Specification**

**Request Body**

When the API is called, Gnani Agents sends:

```json theme={null}
{
  "conversation_id": "abc123",
  "mobile": "01234567890"
}
```

**Expected Response**

```json theme={null}
{
  "additional_info": {
    "inya_data": {
      "text": "Hi John Doe, your payment of ₹2500 is due on 2025-08-20.",
      "user_context": {
        "phone_number": "+911234567890",
        "name": "John Doe",
        "due_amount": "2500",
        "due_date": "2025-08-20",
        "customer_type": "Premium"
      }
    }
  }
}
```

* `text` → Greeting message to be used for the call (mandatory).
* `user_context` → Key–value pairs for use in the System Prompt (mandatory; user\_context can be an empty dictionary if no dynamic variables are used).

***

### Sample API in Python

```python theme={null}
@router.post("/initial_message")
async def bot_initial_message(request: Request):
    body = await request.json()
    mobile = body.get("mobile")
    
    # Example: fetch data from your CRM
    user_data = crm_query(mobile)
    
    response_data = {
        "additional_info": {
            "inya_data": {
                "text": "Hi {user_data.get('name')}, this is a test message",
                "user_context": {
                    "phone_number": mobile,
                    "name": user_data.get("name"),
                    "age": user_data.get("age")
                }
            }
        }
    }
    
    # Status code 200 → call will be triggered
    # Status code 400 → call will NOT be triggered
    return JSONResponse(content=response_data, status_code=200)
```

> This API can be built in any language. The above is a **Python** example.

***

## Best Practices

* Keep API latency low to avoid hitting the 10-second timeout.
* Return only the variables you need to keep payloads small.
* Always validate that your API returns both `text` and `user_context`.
* Use consistent naming for variables so they can be reliably inserted into prompts.