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

# Automation

> High-level automation commands: swipe gestures, coordinate clicks, multi-device synchronization, and UI waiting routines.

## 1.Automation Operations

iClick provides rich automation operation interfaces to remotely control iOS devices for clicking, swiping, input, and other operations.

⚠️ Prerequisites

Before using automation features, you must enable AssistiveTouch on the iOS device, otherwise operations will not work

## 2.Send Action

Execute system-level quick actions, such as returning to home screen, opening app switcher, controlling volume and brightness, etc.

### Endpoint Description

#### Endpoint Type

```
sendAction
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |
| `action` | string | ✅ | Action type (see supported actions list below) |

#### Response Payload

```
true  // Returns true on successful operation
```

### Supported Actions

| Action Value | Category | Description |
| - | - | - |
| `home` | Navigation | Return to home screen (Home button) |
| `switcher` | Navigation | Open app switcher (multitasking interface) |
| `spotlight_search` | Navigation | Open Spotlight search |
| `screen_keyboard` | Input | Show/hide on-screen keyboard |
| `inputmethod_switch` | Input | Switch input method |
| `volume_mute` | Volume Control | Mute/unmute |
| `volume_increment` | Volume Control | Increase volume |
| `volume_decrement` | Volume Control | Decrease volume |
| `brightness_increment` | Brightness Control | Increase screen brightness |
| `brightness_decrement` | Brightness Control | Decrease screen brightness |

### Usage Examples

#### Return to Home and Open App Switcher

```
// Return to home screen
await apiInvoke('sendAction', {
    deviceId: 'P72578581E07',
    action: 'home'
});

// Wait 1 second
await new Promise(resolve => setTimeout(resolve, 1000));

// Open app switcher
await apiInvoke('sendAction', {
    deviceId: 'P72578581E07',
    action: 'switcher'
});
```

## 3.Open App

Open a specified iOS application via Spotlight search.

### Endpoint Description

#### Endpoint Type

```
openApp
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |
| `name` | string | ✅ | Application name (supports fuzzy search, Chinese will be automatically converted to Pinyin for search) |

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

#### Open Application

```
// Open WeChat app
await apiInvoke('openApp', {
    deviceId: 'P72578581E07',
    name: 'WeChat'
});
```

### How It Works

This interface opens the application through the following steps:

1. Invoke Spotlight
2. Enter application name
3. Automatically open the application

## 4.Kill Recents

Clear all background running applications on iOS device.

### Endpoint Description

#### Endpoint Type

```
killRecents
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

#### Kill Recent Apps

```
// Clear all background apps on device
await apiInvoke('killRecents', {
    deviceId: 'P72578581E07'
});
```

### How It Works

This interface clears background applications through the following steps:

1. Open app switcher
2. Clear background app cards through swipe operations

Performance Tip

* This interface performs multiple swipe operations
* If there are many background apps, it may take longer

## 5.Click Operation

Execute click operation at specified coordinate position.

### Endpoint Description

#### Endpoint Type

```
click
```

#### Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `deviceId` | string | ✅ | - | Device ID |
| `x` | number | ✅ | - | Click X coordinate (pixels) |
| `y` | number | ✅ | - | Click Y coordinate (pixels) |
| `focus` | boolean | ❌ | `false` | Whether to attempt focus before clicking |
| `delay` | number | ❌ | `false` | Click to release delay |

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

#### Simple Click

```
// Click screen coordinate (100, 200)
await apiInvoke('click', {
    deviceId: 'P72578581E07',
    x: 100,
    y: 200
});
```

#### focus Parameter?

> [!WARNING]
>
> ⚠️ Use in Specific Scenarios
>
> The `focus` parameter is **only for specific scenarios**

**✅ Applicable Scenarios: System-level Alert Buttons**

System-level alert boxes (such as permission requests, system popups, etc.) buttons sometimes cannot respond to normal click events. In this case, use `focus: true`:

**Examples of Applicable System-level Alerts:**

* 📱 Permission request popups (camera, location, notifications, etc.)
* 🔐 System security alerts
* ⚙️ System settings related popups
* 🔔 iOS system-level confirmation dialogs

**❌ Not Applicable: Normal App Interfaces**

For normal buttons and UI elements in apps, **do not use** `focus: true`

#### ❓ Does focus: true Affect Performance?

It will slightly increase execution time.

## 6.Move Cursor

Move device cursor to specified coordinate position.

### Endpoint Description

#### Endpoint Type

```
mouseMove
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |
| `x` | number | ✅ | Target X coordinate (pixels) |
| `y` | number | ✅ | Target Y coordinate (pixels) |

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

```
// Move cursor to coordinate (300, 400)
await apiInvoke('mouseMove', {
    deviceId: 'P72578581E07',
    x: 300,
    y: 400
});
```

## 7.Reset Cursor

Reset device cursor to top-left initial position (0, 0).

### Endpoint Description

#### Endpoint Type

```
mouseReset
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

```
// Reset cursor to origin
await apiInvoke('mouseReset', {
    deviceId: 'P72578581E07'
});
```

#### Execution Scenario

🔄 If pointer drift or abnormal behavior occurs, manual reset can solve the issue

## 8.Mouse Down

Press mouse button at specified coordinate position (without releasing).

### Endpoint Description

#### Endpoint Type

```
mouseDown
```

#### Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `deviceId` | string | ✅ | - | Device ID |
| `x` | number | ✅ | - | Press X coordinate (pixels) |
| `y` | number | ✅ | - | Press Y coordinate (pixels) |
| `key` | string | ❌ | `'LEFT'` | Mouse button type |
| `autoRelease` | boolean | ❌ | `false` | Auto release button |

#### key Parameter Values

| Value | Description |
| - | - |
| `LEFT` | Left button (default) |
| `RIGHT` | Right button |
| `MIDDLE` | Middle button |
| `EXTRA1` | Extra button 1 |
| `EXTRA2` | Extra button 2 |
| `EXTRA3` | Extra button 3 |
| `EXTRA4` | Extra button 4 |
| `EXTRA5` | Extra button 5 |

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

```
// Press left button at coordinate (200, 300)
await apiInvoke('mouseDown', {
    deviceId: 'P72578581E07',
    x: 200,
    y: 300
    // key defaults to 'LEFT'
});
```

### Auto Release Button

```
// Press left button and auto release
await apiInvoke('mouseDown', {
    deviceId: 'P72578581E07',
    x: 200,
    y: 300,
    autoRelease: true  // Auto release button
});
```

## 9.Mouse Up

Release mouse button at specified coordinate position.

### Endpoint Description

#### Endpoint Type

```
mouseUp
```

#### Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `deviceId` | string | ✅ | - | Device ID |
| `x` | number | ✅ | - | Release X coordinate (pixels) |
| `y` | number | ✅ | - | Release Y coordinate (pixels) |
| `key` | string | ❌ | `'LEFT'` | Mouse button type |

#### key Parameter Values

| Value | Description |
| - | - |
| `LEFT` | Left button (default) |
| `RIGHT` | Right button |
| `MIDDLE` | Middle button |
| `EXTRA1` | Extra button 1 |
| `EXTRA2` | Extra button 2 |
| `EXTRA3` | Extra button 3 |
| `EXTRA4` | Extra button 4 |
| `EXTRA5` | Extra button 5 |

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

```
// Release left button at coordinate (200, 300)
await apiInvoke('mouseUp', {
    deviceId: 'P72578581E07',
    x: 200,
    y: 300
    // key defaults to 'LEFT'
});
```

## 10.Mouse Wheel

Execute mouse wheel scroll operation, used to scroll pages or content areas.

### Endpoint Description

#### Endpoint Type

```
mouseWheel
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |
| `tilt` | number | ✅ | Scroll amount, positive scrolls up, negative scrolls down |

#### tilt Parameter Description

| Value Range | Description | Scroll Direction |
| - | - | - |
| Positive (e.g., `120`) | Scroll up | ⬆️ Page scrolls up (content moves down) |
| Negative (e.g., `-120`) | Scroll down | ⬇️ Page scrolls down (content moves up) |

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

```
// Scroll down
await apiInvoke('mouseWheel', {
    deviceId: 'P72578581E07',
    tilt: -120  // Negative = scroll down
});

// Scroll up
await apiInvoke('mouseWheel', {
    deviceId: 'P72578581E07',
    tilt: 120  // Positive = scroll up
});
```

## 11.Swipe Operation

Execute a swipe operation from starting coordinates to ending coordinates.

### Endpoint Description

#### Endpoint Type

```
swipe
```

#### Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `deviceId` | string | ✅ | - | Device ID |
| `start` | array | ✅ | - | Starting coordinates `[x, y]` |
| `end` | array | ✅ | - | Ending coordinates `[x, y]` |
| `key` | string | ❌ | `'LEFT'` | Key type, `'LEFT'` or `'RIGHT'` |
| `pressTime` | number | ❌ | `58` | Press delay before swipe (milliseconds) |
| `releaseTime` | number | ❌ | `null` | Release delay before ending (increase or decrease adjustable inertia) |

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

#### Simple Swipe

```
// Simulate pull down to open notification center
await apiInvoke('swipe', {
    deviceId: 'P72578581E07',
    start: [screenWidth / 2, 0],
    end: [screenWidh / 2, screenHeight * 0.8]
});
```

## 12.Key Down

Press keyboard key (without releasing).

### Endpoint Description

#### Endpoint Type

```
keyDown
```

#### Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `deviceId` | string | ✅ | - | Device ID |
| `key` | string | ✅ | - | Key name |

#### key Parameter Values

Supported function keys:

| Key | Description | Example Use |
| - | - | - |
| `RIGHT` | Right arrow | Navigate right |
| `LEFT` | Left arrow | Navigate left |
| `DOWN` | Down arrow | Navigate down |
| `UP` | Up arrow | Navigate up |
| `ENTER` | Enter key | Confirm, line break |
| `DEL` | Delete key | Delete content |
| `BACKSPACE` | Backspace key | Delete character |
| `END` | End key | Jump to end |
| `HOME` | Home key | Jump to beginning |
| `PAGEDOWN` | PageDown key | Page down |
| `PAGEUP` | PageUp key | Page up |
| `ESC` | Esc key | Cancel, exit |
| `TAB` | Tab key | Switch focus |
| `CTRL` | Ctrl key | Control key (combination) |
| `SHIFT` | Shift key | Shift key (combination) |
| `ALT` | Alt key | Alt key (combination) |
| `COMMAND` | Command key | macOS combination key |
| `F1` - `F12` | Function keys | System function shortcuts |

💡 Letter and Number Keys

For letter keys (A-Z) and number keys (0-9), use the [sendKey](#send-key) interface, which automatically handles press and release.

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

```
// Press Enter key
await apiInvoke('keyDown', {
    deviceId: 'P72578581E07',
    key: 'ENTER'
});

// Note: Must be used with keyUp
await apiInvoke('keyUp', {
    deviceId: 'P72578581E07',
    key: 'ENTER'
});
```

## 13.Key Up

Release keyboard key.

### Endpoint Description

#### Endpoint Type

```
keyUp
```

#### Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `deviceId` | string | ✅ | - | Device ID |
| `key` | string | ✅ | - | Key name |

#### key Parameter Values

Same as [keyDown](#key-down), supports all standard keyboard keys.

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

```
// Release Enter key
await apiInvoke('keyUp', {
    deviceId: 'P72578581E07',
    key: 'ENTER'
});

// Note: Must call keyDown first
```

## 14.Send Key

Send complete key events, automatically handles press and release, supports single keys, multiple keys, and combination keys.

> ⚠️ Note: `sendKey` can only input keyboard characters (English letters, digits, and common symbols). It does not support other languages or arbitrary text. To send any text to the device, see [Send Text](#send-text).

### Endpoint Description

#### Endpoint Type

```
sendKey
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |
| `key` | string | ✅ | Key (supports + concatenation) |
| `fnkey` | string | ❌ | Function key/modifier key (such as `CTRL`, `SHIFT`, etc., supports + concatenation) |

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

#### Input Single Character

```
// Input letter A
await apiInvoke('sendKey', {
    deviceId: 'P72578581E07',
    key: 'A'
});
```

#### Input Multiple Characters

```
// Input "HELLO"
await apiInvoke('sendKey', {
    deviceId: 'P72578581E07',
    key: 'HELLO'
});

// Equivalent to inputting H, E, L, L, O sequentially
```

### Combination Key Usage

#### With Modifier Keys

```
// COMMAND + C (Copy)
await apiInvoke('sendKey', {
    deviceId: 'P72578581E07',
    key: 'C',
    fnkey: 'COMMAND'
});

// COMMAND + V (Paste)
await apiInvoke('sendKey', {
    deviceId: 'P72578581E07',
    key: 'V',
    fnkey: 'COMMAND'
});

// COMMAND + A (Select All)
await apiInvoke('sendKey', {
    deviceId: 'P72578581E07',
    key: 'A',
    fnkey: 'COMMAND'
});
```

## 15.Send Text

The `sendText` API can send arbitrary text to devices, supporting Chinese, English, numbers, symbols, and emojis.

### API Description

The `sendText` API automatically handles different types of text:

* **Regular characters** (letters, numbers, common symbols): Input directly via keyboard
* **Other characters** (Chinese, emojis, etc.): Automatically write to clipboard via Shortcuts and paste

> ⚠️ Note: When sending non-regular characters, you need to install and bind the official Shortcut on the target device. See [Shortcut APIs](https://docs.phones.farm/api-reference/ios-shortcuts.md).

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| deviceId | string | Yes | Target device ID |
| text | string | Yes | Text content to send |

### Example

```
// Send text with emoji
await apiInvoke('sendText', {
    deviceId: 'P72578581E07',
    text: '你好，Hello iClick! 😄'
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.