## Overview

Smart Fields allow **Chat Agent workflows** to automatically extract and use system-level user information collected from chat interactions, even for non-logged-in users. This is particularly powerful for technical troubleshooting, personalized experiences, and intelligent routing.

⚠️ **Important**: This feature is specifically for **Chat Agent workflows only**. It does not apply to Email Agent or other workflow types.

⚠️ **Preview/testing environments** may not populate all data automatically, but this works in embedded and public chat interfaces.

## What Data is Available "For Free"

The system automatically collects rich user data from every chat interaction through browser detection. This can be accessed via Smart Fields with minimal additional setup.

### Browser & Device Information

- **Browser name** and version (Chrome, Firefox, Safari, etc.)
- **Operating system** (macOS, Windows, iOS, Android, etc.)
- **Device type** (Desktop, Mobile, Tablet)

### Page Context

- **Current URL** where chat was initiated
- **Page title**
- **Meta description**

## Complete Setup Guide

This setup requires **three distinct steps** in different parts of the system:

## Step 1: Create Smart Fields

**Navigation:**`Settings → AI Support → Chat agent → Smart fields`

1. **Click "Create smart field"**
2. **For each field below**, create a new Smart Field with these exact specifications:

| **Field Name** | **Field Type** | **Description** |
| --- | --- | --- |
| `browser_name` | **Text** | User's browser (Chrome, Firefox, etc.) |
| `operating_system` | **Text** | User's OS (macOS, Windows, etc.) |
| `device_type` | **Dropdown** | Device type (Desktop, Mobile, Tablet) |
| `browser_version` | **Text** | Browser version number |
| `current_url` | **Text** | Page where chat was opened |
| `page_title` | **Text** | Title of the page where chat was opened |

### Creating Each Smart Field:

1. **Name**: Enter the exact field name (e.g., `browser_name`)
2. **Type**: Select the field type from the table above
3. **Description**: Copy the description from the table
4. **For**`device_type` **dropdown**, add these options:
   - `Desktop`
   - `Mobile`
   - `Tablet`
5. **Click "Save"**

Repeat this process for all 6 fields.

## Step 2: Configure User Data Mappings

**Navigation:**`Settings → AI Support → Chat agent → Chat settings`

1. **Scroll down** to find the **"User data mapping"** section
2. **Click "Add variable"** for each mapping below
3. **Enter these exact JSON paths and Smart Field names:**

| **JSON Path** | **Smart Field** |
| --- | --- |
| `current_page_data.browser_name` | `browser_name` |
| `current_page_data.operating_system` | `operating_system` |
| `current_page_data.device_type` | `device_type` |
| `current_page_data.browser_version` | `browser_version` |
| `current_page_data.url` | `current_url` |
| `current_page_data.title` | `page_title` |

### Adding Each Mapping:

1. **JSON path field**: Enter the exact path (e.g., `current_page_data.browser_name`)
2. **Smart field dropdown**: Select the corresponding Smart Field you created
3. **Repeat** for all 6 mappings
4. **Save** the chat settings

## Step 3: Add "Collect Information" Step to Your Workflow

**Navigation:**`Workflows → [Your Chat Agent Workflow] → Build`

1. **Click the "+" button** to add a new step
2. **Select "Collect information"** from the step types
3. **Configure the step:**
   - **Step name** (optional): "Gather User Data"
   - **Fields to collect**: Select all the Smart Fields you created:
     - ✅ `browser_name`
     - ✅ `operating_system`
     - ✅ `device_type`
     - ✅ `browser_version`
     - ✅ `current_url`
     - ✅ `page_title`
4. **Save the step**

## Step 4: Use Data in Subsequent Steps

After the "Collect information" step, all subsequent workflow steps can reference the data using variable syntax:

### In Guide Steps:

Add these variables to your response instructions:

- `{{browser_name}}` \- User's browser
- `{{operating_system}}` \- User's OS
- `{{device_type}}` \- Device type
- `{{browser_version}}` \- Browser version
- `{{current_url}}` \- Current page URL
- `{{page_title}}` \- Page title

### In Condition Steps:

Use these variables in your condition logic:

```auto
if device_type == "Mobile"
if browser_name == "Chrome"
if current_url contains "products"
```

## Example Use Cases

### Technical Troubleshooting

```auto
I can see you're using {{browser_name}} on {{operating_system}}.
For this issue, try these {{device_type}}-specific steps:
```

### Intelligent Routing

```auto
conditions:
  - if: device_type == "Mobile"
    route_to: mobile_support_team
  - if: browser_name == "Internet Explorer"
    route_to: legacy_browser_team
```

### Page-Specific Help

```auto
I can see you're on our {{page_title}} page. Let me help you with
that specific product...
```

### Context-Aware Responses

```auto
I can see you're on our {{current_url}} page. Let me help you with
that specific product...
```

## Complete Data Structure Reference

The full `CalPublicChatUserData` structure contains:

```auto
{
  "user_id": "anonymous_12345",
  "email": null,
  "name": null,
  "current_page_data": {
    "url": "<https://example.com/products/widgets>",
    "title": "Premium Widgets | Example Corp",
    "meta_description": "High-quality widgets for...",
    "meta_keywords": "widgets, premium, quality",
    "main_heading": "Our Premium Widget Collection",
    "device_type": "Desktop",
    "operating_system": "macOS",
    "browser_name": "Chrome",
    "browser_version": "120.0.6099.129"
  },
  "metadata": {}
}
```

## Common Pitfalls & Troubleshooting

### ❌ **Problem:** Smart Fields show `[DATA:field_name]` instead of actual values

**Cause:** Missing "Collect Information" step or it's not the first step

**Solution:** Add "Collect Information" step as the **first step** after your trigger

### ❌ **Problem:** Fields remain empty even with correct mappings

**Cause:** Incorrect JSON paths in user data mapping

**Solution:** Double-check the exact paths:

- `current_page_data.browser_name` (not `browser_name`)
- `current_page_data.device_type` (not `device_type`)

### ❌ **Problem:** Smart Fields not appearing in "Collect Information" step

**Cause:** Smart Fields weren't created properly or user data mappings missing

**Solution:**

1. Verify Smart Fields exist in `Settings → AI Support → Chat agent → Smart fields`
2. Verify mappings exist in `Settings → AI Support → Chat agent → Chat settings`

### ❌ **Problem:** Variables not working in Guide steps

**Cause:** "Collect Information" step not configured to collect the specific fields

**Solution:** Edit the "Collect Information" step and ensure all needed Smart Fields are selected

### ✅ **Setup Checklist:**

- \[ \] Smart Fields created with exact names
- \[ \] User data mappings configured with `current_page_data.` prefix
- \[ \] "Collect Information" step is **first** in workflow
- \[ \] "Collect Information" step includes all needed Smart Fields
- \[ \] Variables used with correct syntax: `{{field_name}}`

## Technical Notes

- Data collection works in **embedded chat widgets** and **public chat** interfaces
- **Preview/testing environments** may not populate all data automatically
- User data is collected **immediately** when chat session starts
- Data persists throughout the **entire conversation**
- Browser and device detection works for **all modern browsers** and mobile devices

## Security & Privacy

- Only browser/device information and page context is collected
- **No geographic or IP address data** is stored
- All data collection follows **GDPR and privacy regulations**
- Users can **opt out** of data collection via privacy settings

* * *

_This feature enables powerful personalization and technical troubleshooting capabilities while maintaining user privacy and requiring minimal additional setup._