Browse the docs

intents

Exposes an extension's action, or its own code, to Shortcuts and the switchboard://intent URL.

Details #

An intent makes something your extension does reachable from outside Switchboard: a Shortcut, a link, a script or another app. It either runs one of the extension's actions or runs code of its own.

Declare it in switchboard.json under adds.intents. Every entry has an id (lowercase, digits and . _ -, up to 64 characters, starting with a letter), a title (1 to 80 characters) and an optional description. Ids must be unique within the list.

An intent either names one of the extension's actions with action, or has code of its own written with intent(id, handler) from @switchboard/sdk. An intent that names an action needs no builder.

{
  "adds": {
    "intents": [
      { "id": "count-words", "title": "Count words", "action": "count",
        "params": { "type": "object", "properties": { "text": { "type": "string" } }, "required": ["text"] } }
    ]
  }
}

Gotchas #

  • The key is the engine's URL key, the same one switchboard://run needs (Settings > Advanced). Without it the URL is refused.

  • An intent without action needs an intent(id, handler) of the same id, or the extension doesn't load.

  • A call that takes more than 30 seconds without answering fails.

  • Unknown keys in an entry are refused.

The sample below can be downloaded from the Full example section and edited into your own. It has one intent that names an action and one with its own code.

Where it shows up #

There are three ways in, all running the same intent:

  • URL: switchboard://intent?ext=<extension id>&id=<intent id>&key=<URL key>. Every other query item is a parameter; numbers and booleans are read by the types you declare in params, and params={json} passes a whole object. Shortcuts' Open URLs action opens it. The result is not returned to the Shortcut.

  • Command line: switchboard ext intent <extension id> <intent id> --name Kyle, for Shortcuts' Run Shell Script. The result is printed.

  • API: POST /extensions/<extension id>/intent/<intent id> with the parameters as JSON. GET /extensions/intents lists every intent.

An intent cannot appear as its own named action in the Shortcuts library: Shortcuts reads its action list from the app at build time, so extensions installed later are reached through the three ways above.

The handler #

With action, the engine runs that action with the parameters, exactly as a macro step would. Without it, your intent(id, handler) gets the parameters and returns JSON. Running an intent is a real run, not a dry run, so the action runs even if it is not dryRunSafe.

Full example #

See also #