App Intents: Start a Workout from Siri and Shortcuts

A workout is the one thing a fitness app does that people want to start without looking at a screen: hands full, gloves on, already moving. App Intents is how Apple lets the system start it for them, and the framework has a small set of types made specifically for workout apps alongside the general machinery every app uses for Siri and Shortcuts.

The types, from Apple's symbol metadata#

Apple's "Hardware interactions" topic lists exactly the first three under workout support. It lists no end or cancel counterpart, and we found no such symbol in Apple's App Intents documentation. Apple's HKWorkoutSession documentation separately says that Siri support extends to the Lock Screen so people can start, pause, resume or cancel workouts hands-free, and that you can integrate Siri intents to enable it, but it does not say which intent types those Siri requests map to. We could not verify that mapping from Apple's pages, so this page does not claim one.

Apple Watch Ultra's Action button: the rules Apple states#

Apple's article "Responding to the Action button on Apple Watch Ultra" is the primary reference here, and it is unusually specific.

Where the code lives. Apple says not to implement Action button intents in an App Intents extension; implement them directly in the watchOS app.

What you define. An AppEnum or AppEntity listing the workout styles you support, with a display representation for each, which the watch shows under the First Press setting. Then a StartWorkoutIntent with a title, a workoutStyle declared with the @Parameter property wrapper, a list of suggestedWorkouts, a displayRepresentation and a perform() method. If the list of suggested workouts changes, call invalidateSuggestedWorkouts() so the system rereads it.

The 30-second rule. Apple states that perform() has 30 seconds to start a workout session and return. If it does not, the system shows an error and the app stays in the foreground, and without a session the app goes to the background the next time the person drops their wrist.

It works before first launch. The start intent is available as soon as the app is installed, so someone can assign it to the Action button and run it without ever opening your app. Apple's guidance is therefore to start the session first and schedule the HealthKit authorization request in a Task from inside perform(), because the authorization sheet can take arbitrarily long. One exception is documented and easy to trip over: if your app has never requested authorization for any HealthKit data types, pressing the button only launches the app and the system does not call perform() at all.

Leave openAppWhenRun alone. Apple says the system always launches your app before running a start workout intent, that these intents set openAppWhenRun to true by default, and that you should not change it.

The next action. Once your session is running, a further press runs whatever intent you last donated as the next action, such as marking a lap. You can return it from perform() with result(actionButtonIntent:), but Apple recommends returning a plain result and donating the next action as soon as the session starts, so it is set whether the workout began from the button or from your own interface. Only the most recently donated intent counts.

Pause and resume are opt-in. If the app implements neither protocol, Apple says the system ignores the simultaneous press.

import AppIntents

enum RunStyle: String, AppEnum {
    case outdoorRun
    case treadmillRun

    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Workout"
    static var caseDisplayRepresentations: [RunStyle: DisplayRepresentation] = [
        .outdoorRun: DisplayRepresentation(title: "Run", subtitle: "Outdoor"),
        .treadmillRun: DisplayRepresentation(title: "Run", subtitle: "Treadmill")
    ]
}

struct StartRunIntent: StartWorkoutIntent {
    static var title: LocalizedStringResource = "Start Run"
    static var suggestedWorkouts: [StartRunIntent] = [
        StartRunIntent(style: .outdoorRun),
        StartRunIntent(style: .treadmillRun)
    ]

    @Parameter(title: "Workout")
    var workoutStyle: RunStyle

    init() { workoutStyle = .outdoorRun }

    var displayRepresentation: DisplayRepresentation {
        RunStyle.caseDisplayRepresentations[workoutStyle]
            ?? DisplayRepresentation(title: "Run")
    }

    func perform() async throws -> some IntentResult {
        // Create and start the HKWorkoutSession here, inside 30 seconds.
        try await WorkoutManager.shared.startSession(style: workoutStyle)
        // Authorization can block on a sheet, so it runs after perform() returns.
        Task { await WorkoutManager.shared.requestAuthorizationThenCollect() }
        return .result()
    }
}

struct PauseRunIntent: PauseWorkoutIntent {
    static var title: LocalizedStringResource = "Pause Run"

    func perform() async throws -> some IntentResult {
        await WorkoutManager.shared.pause()
        return .result()
    }
}

struct ResumeRunIntent: ResumeWorkoutIntent {
    static var title: LocalizedStringResource = "Resume Run"

    func perform() async throws -> some IntentResult {
        await WorkoutManager.shared.resume()
        return .result()
    }
}

WorkoutManager stands in for whatever owns your HKWorkoutSession; the session itself is covered in the anatomy of a watchOS workout app. To test, Apple's steps are to build and run, send the app to the background, assign it under Settings, then press the button; logging and breakpoints from the intents reach Xcode.

Siri, Spotlight and the Shortcuts app: App Shortcuts#

For everything that is not the Watch Ultra button, the mechanism is an App Shortcut. Apple describes it as your intent combined with a title, an image and the spoken phrases someone might use, optionally with preconfigured parameters so it runs without follow-up questions. You declare shortcuts in code on a type that adopts AppShortcutsProvider, the compiler generates what the system needs, and Apple states that they are available as soon as someone installs the app, without registering anything yourself.

import AppIntents

struct StartPhoneRunIntent: AppIntent {
    static let title: LocalizedStringResource = "Start a Run"
    static let openAppWhenRun: Bool = true

    @MainActor
    func perform() async throws -> some IntentResult {
        try await PhoneWorkoutController.shared.startRun()
        return .result()
    }
}

struct FitnessShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: StartPhoneRunIntent(),
            phrases: [
                "Start a run in \(.applicationName)",
                "Start my \(.applicationName) run"
            ],
            shortTitle: "Start Run",
            systemImageName: "figure.run"
        )
    }
}

Points from Apple's documentation and its App Intents sample, which happens to be a trail app with workout tracking on Apple Watch:

• Apple's sample writes \(.applicationName) into every phrase, and Apple says the system uses a semantic similarity index, so similar wordings match without listing each one.
• The AppShortcut initializer used above, init(intent:phrases:shortTitle:systemImageName:), is listed from iOS 17.0 and watchOS 10.0, and Apple says shortcuts built with it can be run from the Action button on supported iPhone models.
• Apple's stated best practice is App Shortcuts for only the most common actions, usually two to five intents and not more than ten. For a fitness app, start and log are candidates; settings screens are not.
• The sample calls updateAppShortcutParameters() on its provider during app initialization, and teaches the phrase with a SiriTipView placed where the action lives in the app.
• On iOS 26 and later Apple also documents supportedModes for choosing whether an intent runs in the foreground or background; openAppWhenRun remains the property listed back to iOS 16.

Starting the Live Activity from the same intent#

Apple's design guidance for Live Activities recommends offering an App Shortcut that starts your Live Activity, for example from the Action button on iPhone. The catch is that an app generally has to be in the foreground to start a Live Activity. LiveActivityIntent is the documented exception: Apple says that when the system performs one, it launches your app's process without opening the app, runs perform(), and starts the Live Activity from there.

import AppIntents

struct StartRunWithLiveActivityIntent: LiveActivityIntent {
    static var title: LocalizedStringResource = "Start Run"

    func perform() async throws -> some IntentResult {
        let startedAt = Date.now
        try await PhoneWorkoutController.shared.startRun(at: startedAt)
        // Starts the Live Activity; see the ActivityKit page for this function.
        _ = try startWorkoutActivity(name: "Run", startedAt: startedAt)
        return .result()
    }
}

startWorkoutActivity is the function from the ActivityKit workout Live Activity page, which also covers the LiveActivityIntent that powers a pause button inside the activity.

One session owner, many doors#

Count the entry points: the app's own start button, the Watch Ultra Action button, a Siri phrase, a Shortcuts automation, the iPhone Action button and a button in a Live Activity. Our recommendation is that every one of them calls the same session owner and none of them holds state of its own. That is the same discipline mirroring a workout to iPhone recommends for Siri control, for the same reason: state changes arrive from places you did not draw, and an interface that follows session state handles all of them with one code path.

Every type, version and rule above comes from Apple's App Intents, ActivityKit and HealthKit documentation and Apple's Human Interface Guidelines as of this page's review date. App Intents gains types with most releases, so check the symbol pages for your deployment target.