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

# Interaction Actions

> Clicking, typing, and navigating web pages

Interaction actions represent user interactions with the browser: clicking buttons, filling forms, navigating pages, and more.

## Available Actions

| Action                | Purpose                        |
| --------------------- | ------------------------------ |
| `click_element`       | Click buttons, links, elements |
| `input_text`          | Type into text fields          |
| `select_option`       | Select from dropdowns          |
| `check`               | Check/uncheck checkboxes       |
| `upload_file`         | Upload files                   |
| `go_to_url`           | Navigate to a URL              |
| `go_back`             | Go back in history             |
| `close_tabs_until`    | Close tabs until condition met |
| `download_url_as_pdf` | Save page as PDF               |
| `key_press`           | Press keyboard keys            |
| `agentic_task`        | AI agent for complex tasks     |
| `close_overlay_popup` | Dismiss popups/modals          |

## Common Properties

All element-targeting actions share these properties:

| Property                      | Type          | Default  | Description                                        |
| ----------------------------- | ------------- | -------- | -------------------------------------------------- |
| `command`                     | `str \| None` | `None`   | Playwright locator (e.g., `get_by_role("button")`) |
| `xpath`                       | `str \| None` | `None`   | XPath selector (alternative to command)            |
| `prompt_instructions`         | `str`         | Required | Description for AI fallback                        |
| `skip_prompt`                 | `bool`        | `False`  | Skip AI if locator fails (for optional elements)   |
| `assert_locator_presence`     | `bool`        | `False`  | Skip action if element doesn't exist               |
| `max_tries`                   | `int`         | `10`     | Maximum retry attempts                             |
| `max_timeout_seconds_per_try` | `float`       | `1.0`    | Timeout per attempt                                |

<Tip>
  Use `command` for deterministic element finding (fast, no LLM tokens). The AI uses `prompt_instructions` as fallback when locators fail.
</Tip>

***

## Click Element

```json theme={null}
{
  "interaction_action": {
    "click_element": {
      "command": "get_by_role(\"button\", name=\"Submit\")",
      "prompt_instructions": "Click the submit button"
    }
  }
}
```

### Click Properties

| Property            | Type          | Default        | Description                    |
| ------------------- | ------------- | -------------- | ------------------------------ |
| `double_click`      | `bool`        | `False`        | Double-click instead of single |
| `expect_download`   | `bool`        | `False`        | Click triggers file download   |
| `download_filename` | `str \| None` | Auto-generated | Filename for download          |

### Examples

**Double-click:**

```json theme={null}
{
  "click_element": {
    "command": "get_by_role(\"row\", name=\"Item 1\")",
    "double_click": true
  }
}
```

**Download trigger:**

```json theme={null}
{
  "click_element": {
    "command": "get_by_role(\"button\", name=\"Export\")",
    "expect_download": true,
    "download_filename": "report.pdf"
  }
}
```

***

## Input Text

```json theme={null}
{
  "interaction_action": {
    "input_text": {
      "command": "get_by_label(\"Email\")",
      "input_text": "{email[0]}",
      "prompt_instructions": "Enter the email address"
    }
  }
}
```

### Input Properties

| Property       | Type               | Default  | Description                        |
| -------------- | ------------------ | -------- | ---------------------------------- |
| `input_text`   | `str \| None`      | `None`   | Text to enter (supports variables) |
| `fill_or_type` | `"fill" \| "type"` | `"fill"` | How to enter text                  |
| `is_slider`    | `bool`             | `False`  | Element is a slider                |
| `press_enter`  | `bool`             | `False`  | Press Enter after input            |

### Fill vs Type

| Mode   | Behavior                     | Use When                              |
| ------ | ---------------------------- | ------------------------------------- |
| `fill` | Sets value instantly         | Standard form fields                  |
| `type` | Types character by character | Autocomplete, search with suggestions |

**Autocomplete example:**

```json theme={null}
{
  "input_text": {
    "command": "get_by_label(\"Search\")",
    "input_text": "laptop",
    "fill_or_type": "type"
  }
}
```

**Slider example:**

```json theme={null}
{
  "input_text": {
    "command": "get_by_role(\"slider\", name=\"Price\")",
    "input_text": "500",
    "is_slider": true
  }
}
```

<Info>
  If `input_text` references an empty variable, the action is skipped automatically.
</Info>

***

## Select Option

```json theme={null}
{
  "interaction_action": {
    "select_option": {
      "command": "get_by_label(\"Country\")",
      "select_values": ["United States"],
      "prompt_instructions": "Select country"
    }
  }
}
```

### Select Properties

| Property            | Type          | Default        | Description                 |
| ------------------- | ------------- | -------------- | --------------------------- |
| `select_values`     | `list[str]`   | Required       | Values to select            |
| `expect_download`   | `bool`        | `False`        | Selection triggers download |
| `download_filename` | `str \| None` | Auto-generated | Filename for download       |

<Tip>
  Optexity supports fuzzy matching for select values—"United States" will match "UNITED STATES OF AMERICA".
</Tip>

***

## Check (Checkbox/Radio)

```json theme={null}
{
  "interaction_action": {
    "check": {
      "command": "get_by_label(\"I agree to the terms\")",
      "prompt_instructions": "Check the terms agreement"
    }
  }
}
```

***

## Navigation Actions

### Go to URL

| Property  | Type   | Default  | Description        |
| --------- | ------ | -------- | ------------------ |
| `url`     | `str`  | Required | URL to navigate to |
| `new_tab` | `bool` | `False`  | Open in new tab    |

```json theme={null}
{
  "interaction_action": {
    "go_to_url": {
      "url": "https://example.com/dashboard",
      "new_tab": true
    }
  }
}
```

### Go Back

```json theme={null}
{
  "interaction_action": {
    "go_back": {}
  }
}
```

### Close Tabs Until

Close tabs until reaching a specific URL or tab index:

| Property       | Type          | Default | Description                      |
| -------------- | ------------- | ------- | -------------------------------- |
| `matching_url` | `str \| None` | `None`  | Stop at this URL                 |
| `tab_index`    | `int \| None` | `None`  | Stop at this tab index (0-based) |

```json theme={null}
{
  "interaction_action": {
    "close_tabs_until": {
      "matching_url": "https://example.com/dashboard"
    }
  }
}
```

***

## File Operations

### Upload File

The file source must be **exactly one** of `file_path` (local file) or `file_url` (public `http(s)://` URL — downloaded to a temp file just before upload, then cleaned up).

| Property    | Type          | Description                                                                                                                                          |
| ----------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file_path` | `str \| None` | Absolute or relative local path                                                                                                                      |
| `file_url`  | `str \| None` | Public `http://` or `https://` URL; downloaded with a 120s timeout. If the download fails (network error or non-2xx response), the automation fails. |

Upload from a local path:

```json theme={null}
{
  "interaction_action": {
    "upload_file": {
      "command": "get_by_label(\"Upload Document\")",
      "file_path": "/path/to/document.pdf",
      "prompt_instructions": "Upload the document"
    }
  }
}
```

Upload from a public URL:

```json theme={null}
{
  "interaction_action": {
    "upload_file": {
      "command": "get_by_label(\"Upload Document\")",
      "file_url": "https://example.com/files/document.pdf",
      "prompt_instructions": "Upload the document"
    }
  }
}
```

### Download Page as PDF

Capture the current page or a specific URL as PDF:

| Property            | Type          | Default        | Description      |
| ------------------- | ------------- | -------------- | ---------------- |
| `download_filename` | `str \| None` | Auto-generated | Filename for PDF |
| `url`               | `str \| None` | Current page   | URL to download  |

```json theme={null}
{
  "interaction_action": {
    "download_url_as_pdf": {
      "download_filename": "page_snapshot.pdf"
    }
  }
}
```

***

## Handling New Tabs

When an action opens a new tab, set `expect_new_tab` on the action node:

```json theme={null}
{
  "type": "action_node",
  "interaction_action": {
    "click_element": {
      "command": "get_by_role(\"button\", name=\"Open Details\")",
      "prompt_instructions": "Click to open in new tab"
    }
  },
  "expect_new_tab": true
}
```

This automatically waits up to 10 seconds for the new tab and switches to it.

***

## Retry Configuration

For slow-loading elements, increase retry attempts:

```json theme={null}
{
  "interaction_action": {
    "max_tries": 15,
    "max_timeout_seconds_per_try": 2.0,
    "click_element": {
      "command": "get_by_role(\"button\", name=\"Submit\")",
      "prompt_instructions": "Click submit"
    }
  }
}
```

<Tip>
  Increase `max_tries` rather than timeout per try. This finds elements faster when they appear while still allowing for slow pages.
</Tip>