# Smart Links

Smart Links provide a URL-based mechanism to trigger actions within the application from external sources.

**Online tester:** [https://link-test.acrobits.cz/tools/smartLinks](https://link-test.acrobits.cz/tools/smartLinks)

## Format

The Smart Link format extends the AppPath format with additional capabilities from CSCommand. Smart Links can be embedded in CSCommand the same way as AppPath.

| Component | Requirement |
|-----------|-------------|
| **scheme** | Must be `app` |
| **authority** | Must be empty |
| **path** | Must be empty |
| **query** | Must contain at least the `action` parameter |
| **fragment** | Must not be present |

**Example:**

```
app:?action=navigate&tab=browser&relative=/ble/chicken&reload=true
```

---

## Actions

All actions are defined in a shared format. Platforms may choose which actions to support. Every action can include additional arguments as query parameters.

### Navigate

Navigates to a specific tab within the app.

**Action:** `navigate`

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `tab` | String | Yes | The tab to navigate to. |

The Navigate action also supports tab-specific arguments. For the **browser tab**:

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `relative` | String | `null` | Relative URL merged using AppPath merging rules. |
| `reload` | Boolean | `false` | If `true`, the tab is always reloaded. If `false`, only reloaded when the URL changes. |
| `reset` | Boolean | `false` | If `true`, the browser URL is reset to the default from PrefKeys. The `relative` field is ignored. |

---

### Function

Invokes an exported [function](function-reference.md) by ID. Functions cannot be triggered via Smart Links unless they are marked as `exported` in their definition.

**Action:** `function`

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | String | Yes | ID of the function to invoke. |
| `param` | Map | No | Key-value pairs passed as the `param` scope for [placeholder](scopes.md#supported-placeholders) resolution. |

```
app:?action=function&id=sendLinkupMessage¶m[from]=Me¶m[message]=Hello
```

---

### Reprovision

Triggers reprovisioning. Replaces the legacy `provisioning-update` and `extprov-update` commands.

**Action:** `reprovision`

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `only` | String[] | `null` | Which items to update: `provisioning`, `theme`, `extprov`, `global_extprov`. If `null`, everything is updated. |
| `resetCache` | Boolean | `null` | If `true`, provisioning endpoints and other cached values are reset. |
| `accounts` | String[] | `null` | Account IDs to update External Provisioning for. If `null`, all accounts are updated. Only applies when `only` is `null` or includes `extprov`. |

```
app:?action=reprovision&only=provisioning,extprov&resetCache=true&accounts=hello,there
```

---

### Balance Update

Triggers a balance update. Replaces the legacy `balance-update` command.

**Action:** `balance-update`

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `accounts` | String[] | `null` | Account IDs to update. If `null`, all accounts are updated. |

```
app:?action=balance-update&accounts=hello,there
```

---

## Map Format

To embed key-value maps in URL query parameters, use the following syntax:

```
map[key]=value
```

Where `map` is the parameter name, `key` is the map key, and `value` is the assigned value.