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
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 or / |
| query | Must contain at least the action parameter |
| fragment | Must not be present |
Example¶
Query parameter values must be URL-encoded when they contain reserved characters. In particular, encode & and # inside a nested URL so they do not become query separators or a fragment of the Smart Link itself.
app:?action=navigate&tab=browser&relative=%2Fhelp%3Flang%3Den%26topic%3Dcalls%23audio
Here, relative decodes to /help?lang=en&topic=calls#audio.
Boolean parameters accept true or 1 for true, and false or 0 for false. Other values are treated as omitted, so the parameter's default applies.
Action names and enum values are case-sensitive.
Actions¶
All actions are defined in a shared format. Platforms may choose which actions to support.
Note
It is not guaranteed that a given platform will support all actions. For example, the mobile platforms cannot support the External Navigation type of the Navigate action.
Every action can include additional arguments specific to that action. All arguments are represented as additional query parameters.
Navigate¶
Navigates to a specific tab within the app or to an external location.
This can be either Tab Navigation, Settings Navigation, or External Navigation, depending on the provided arguments.
Provide one target parameter: tab, settings, or external. If several are present, tab takes precedence over external, which takes precedence over settings. An invalid higher-priority target does not fall back to another target.
Action: navigate
Tab Navigation¶
Navigates to a tab within the app.
| Name | Type | Required | Description |
|---|---|---|---|
tab |
String | Yes | The configured ID of the tab to navigate to. |
The Navigate Action also supports passing additional arguments to the tab it is navigating to. These depend on the configured tab type: browser tabs support browser options, and keypad tabs support keypad options. Other tab types have no additional options.
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. |
Keypad tab¶
| Name | Type | Default | Description |
|---|---|---|---|
enter |
String | null |
Replaces the current keypad input with the value. |
append |
String | null |
Appends the value to the current keypad input. |
press |
Enum | null |
Presses a keypad action button. |
Possible press values:
backspace- Deletes one character from the keypad input.call- Presses the default call button.gsm- Presses the GSM call button, if available.voicemail- Presses the voicemail button, if visible.
The keypad input is applied before press. If both enter and append are present, append is used.
An unknown press value makes the Smart Link invalid.
Example¶
Settings Navigation¶
Navigates to a specific settings screen.
| Name | Type | Required | Description |
|---|---|---|---|
settings |
String | Yes | The settings screen to navigate to. |
Example¶
External Navigation¶
Navigates to an external location.
| Name | Type | Required | Description |
|---|---|---|---|
external |
enum |
Yes | The location that will be navigated to. |
Possible external values:
recordings- The folder where recordings are stored (if applicable)logs- The folder where logs are stored (if applicable)
Example¶
Function¶
Invokes an exported function 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 resolution. |
Example¶
Provision¶
Triggers provisioning with a new account. The current user will be signed out and the new account will be added.
This is Smart Link-native version of the CSC Links.
Note
The provision action can also be used to trigger resets and logouts without signing into new account.
Action: provision
| Name | Type | Required | Description |
|---|---|---|---|
username |
String | No | Username for the new account. |
password |
String | No | Password for the new account. |
forced |
Boolean | No | If true, it resets and provisions the app even if the currently provisioned user is the same as the new one. Added in 26.1 |
cid |
String | No | CID for the new account. |
mode |
Enum | No | Reset mode, can be either reset or logout. If not provided the default from provisioning will be used. |
Additional parameters are passed as extras, same as in CSC Links. These include env, token, provider, and provider-specific extras.
Example¶
app:?action=provision&username=hello&password=there&cid=TEST&mode=logout
Reprovision¶
Triggers reprovisioning. Replaces the legacy provisioning-update and extprov-update commands.
Action: reprovision
| Name | Type | Default | Description |
|---|---|---|---|
only |
String[] | All items | Which items to update: provisioning, theme, extprov, global_extprov. If omitted, 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 omitted, all accounts are updated. Only applies when only is omitted or includes extprov. |
Unknown values in only are ignored. An explicitly empty only= or a list containing only unknown values selects nothing; omit only to update everything.
resetCache clears the provisioning cache when updating provisioning, theme, or global_extprov. It has no effect when only extprov is selected.
Example¶
app:?action=reprovision&only=extprov&accounts=hello,there
Balance update¶
Trigger balance update, new version of legacy balance-update
Action: balance-update
| Name | Type | Default | Description |
|---|---|---|---|
accounts |
String[] | null |
Account IDs to update. If null, all accounts are updated. |
Example¶
Quit¶
Triggers the app to quit.
Action: quit
| Name | Type | Default | Description |
|---|---|---|---|
mode |
Enum | soft |
Can be either soft, force, or restart. |
The mode parameter determines how the app will quit:
soft(default) - The app will attempt to quit gracefully. This may mean only minimizing to the task tray.force- The app will quit immediately without any cleanup. This may cause data loss. Mobile platforms may stop receiving push notifications until the app is opened again.restart- The app will quit and immediately restart.
Example¶
List Format¶
To embed lists in URL query parameters, use the following syntax:
Empty items are ignored, and whitespace is not trimmed. Use value1,value2, without spaces around the comma.
For accounts, omitting the parameter selects all accounts; an explicitly empty accounts= selects none.
Map Format¶
To embed key-value maps in URL query parameters, use the following syntax:
Where map is the parameter name, key is the map key, and value is the assigned value.