> ## 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.

# IOS Shortcuts

> Programmatic execution and status polling of iOS Shortcuts workflows across tethered iPhones.

## 1.Overview

### Shortcuts

Due to iOS privacy protection restrictions, some iClick functions such as writing to clipboard need to be implemented with shortcuts. You need to install and bind iClick shortcuts to use them.

### Unified Interface

All shortcuts are called through `execShortcut`

Please note that this interface does not support concurrent calls

### Notes

iClick has built-in some common functions for developers, such as reading/writing clipboard, sending SMS, etc.

However, we will not integrate too many functions into official shortcuts, because it is not perfect and may have the possibility of freezing or no response

If you need more functions, you can try to create custom shortcuts. See [Extended Shortcuts](#extended-shortcuts) for details.

> [!WARNING]
>
> Notes
>
> Device Requirements
>
> * Device must be online and USB ready
> * Corresponding shortcuts must be pre-configured on iOS device

## 2.Write Clipboard

Write text content to the iOS device's system clipboard.

### Endpoint Description

#### Endpoint Type

```
execShortcut
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |
| `directive` | string | ✅ | `'writeClipboard'` |
| `payload` | string | ✅ | Text content to write to clipboard |

#### Response Payload

```
true  // Returns true on successful write
```

### Basic Usage

```
// Write fixed text
await apiInvoke('execShortcut', {
    deviceId: 'P72578581E07',
    directive: 'writeClipboard',
    payload: 'Hello iClick!'
})
// Simulate paste (Command+V)
await apiInvoke('sendKey', {
    deviceId: 'P72578581E07',
    key: 'v',
    fnkey: 'command'
})
```

## 3.Read Clipboard

Read text content from the iOS device's system clipboard.

### Endpoint Description

#### Endpoint Type

```
execShortcut
```

#### Parameters

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

#### Response Payload

```
"Clipboard text content"  // Returns clipboard text content
```

### Basic Usage

```
// Read clipboard content
const clipboardText = await apiInvoke('execShortcut', {
    deviceId: 'P72578581E07',
    directive: 'readClipboard'
});

console.log('Clipboard content:', clipboardText);
```

## 4.Send SMS

Send SMS messages through the iOS device.

### Endpoint Description

#### Endpoint Type

```
execShortcut
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |
| `directive` | string | ✅ | Fixed value `'sendSms'` |
| `payload` | object | ✅ | SMS parameters object |
| `payload.to` | string/number | ✅ | Recipient phone number |
| `payload.content` | string | ✅ | SMS content |

#### Response Payload

```
true  // Returns true on successful send
```

### Basic Usage

```
// Send SMS
await apiInvoke('execShortcut', {
    deviceId: 'P72578581E07',
    directive: 'sendSms',
    payload: {
        to: '13800138000',
        content: 'Hello World!'
    }
});
```

## 5.Play Beep

Play the iOS device's system beep sound.

### Endpoint Description

#### Endpoint Type

```
execShortcut
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |
| `directive` | string | ✅ | Fixed value `'playBeep'` |

#### Response Payload

```
true  // Returns true on successful playback
```

### Basic Usage

```
// Play beep sound
await apiInvoke('execShortcut', {
    deviceId: 'P72578581E07',
    directive: 'playBeep'
});
```

## 6.Open URL

Open a specified URL in the iOS device's Safari browser.

### Endpoint Description

#### Endpoint Type

```
execShortcut
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |
| `directive` | string | ✅ | Fixed value `'openUrl'` |
| `payload` | string | ✅ | URL address to open |

#### Response Payload

```
true  // Returns true on successful opening
```

⚠️ Notice

Avoid using this interface to open apps via scheme URLs unless necessary!

If you use a Scheme URL to open an app, the following issues may rarely occur when running frequently for extended periods:

1. **Cause the app to be in a "defocused" state**
2. **Cause Shortcuts to freeze**

**Recommendation:** If you need to open an app, please use the [Open App](https://docs.phones.farm/api-reference/automation.md#3open-app) interface.

### Basic Usage

```
// Open webpage
await apiInvoke('execShortcut', {
    deviceId: 'P72578581E07',
    directive: 'openUrl',
    payload: 'https://phones.farm'
});
```

### Notes

Tips

* Opening an unauthorized URL will trigger a permission request, which developers need to handle themselves

## 7.Show WebView

Pop up a WebView in the current app to open the specified URL.

### Endpoint Description

#### Endpoint Type

```
execShortcut
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |
| `directive` | string | ✅ | Fixed value `'showWebview'` |
| `payload` | string | ✅ | URL address to open |

#### Response Payload

```
true  // Returns true on successful opening
```

### Basic Usage

```
// Open webpage in WebView
await apiInvoke('execShortcut', {
    deviceId: 'P72578581E07',
    directive: 'showWebview',
    payload: 'https://phones.farm'
});
```

### Difference from openUrl

| Feature | openUrl | showWebview |
| - | - | - |
| Opening Method | Open in Safari | Pop up WebView in app |
| App Switching | Switches to Safari | Stays in current app |

Tips

* Opening an unauthorized URL for the first time will trigger a permission request, which developers need to handle themselves

## 10.Extended Shortcuts

Through iClick's extended mouse button feature, developers can create custom shortcuts.

💡 Unlimited Possibilities

iOS Shortcuts can control most device functions, such as enabling WIFI, turning VPN on/off, setting Bluetooth, accessing networks, etc.

By leveraging the mechanism of triggering shortcuts with iOS mouse buttons, you can implement countless complex workflows

### How It Works

iClick's shortcuts system essentially works by **triggering specific mouse buttons** to activate corresponding shortcuts.

When you call a shortcut:

1. Simulate pressing specified mouse button (e.g., EXTRA1)
2. iOS shortcuts on device listen to button event
3. Execute corresponding shortcut logic

### Extended Mouse Buttons

iClick extends **5 additional mouse buttons** for developers:

| Button Name | Description |
| - | - |
| `EXTRA1` | Extended button 1 |
| `EXTRA2` | Extended button 2 |
| `EXTRA3` | Extended button 3 |
| `EXTRA4` | Extended button 4 |
| `EXTRA5` | Extended button 5 |

### Creating Custom Shortcuts

#### Step 1: Create iOS Shortcut

Create a shortcut on iOS device, for example `Quick Toggle VPN`.

#### Step 2: Add Button

Open Settings -> Accessibility -> Touch -> AssistiveTouch -> Devices -> Click PHOMATRIX+ -> Customize more buttons and send the button you want

#### Step 3: Bind Shortcut

For example, if you added `Button 5`, click `Button 5` and select the `Quick Toggle VPN` shortcut you just created

#### Step 4: Trigger Shortcut

In your program, you can trigger the VPN toggle shortcut by using the mouse button API to press `Button 5`

### Practical Applications

💡

iOS Shortcuts can access networks. In practical applications, you can create a command service API and execute different functions through different commands issued by the server


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