--- title: "App Intents: Start a Workout from Siri and Shortcuts" canonical: "https://aifitnessapi.com/engagement/app-intents-start-workout" cluster: "Engagement & Retention" primary_query: "app intents start workout siri shortcuts" last_reviewed: "2026-10-03" description: "StartWorkoutIntent, PauseWorkoutIntent and ResumeWorkoutIntent for the Action button, App Shortcuts for Siri, and LiveActivityIntent for the Lock Screen." publisher: "AIFitnessAPI — independent, not sponsored" cite_as: "\"App Intents: Start a Workout from Siri and Shortcuts\", AIFitnessAPI, https://aifitnessapi.com/engagement/app-intents-start-workout" --- # App Intents: Start a Workout from Siri and Shortcuts > Apple's App Intents framework has three system intents for workout apps, StartWorkoutIntent, PauseWorkoutIntent and ResumeWorkoutIntent, each listed in Apple's symbol metadata from iOS 16 and watchOS 9. On Apple Watch Ultra, StartWorkoutIntent puts your app on the Action button, and Apple documents that perform() has 30 seconds to start a workout session, that the intents must be implemented in the watchOS app rather than an App Intents extension, and that if the app has never requested HealthKit authorization the system only launches it without calling perform(). For Siri, Spotlight, the Shortcuts app and the iPhone Action button you expose an ordinary AppIntent through an AppShortcutsProvider, and Apple's sample writes the application name into every phrase. To show the workout on the Lock Screen at the same moment, a LiveActivityIntent, available from iOS 17, can start a Live Activity without opening the app. - Canonical: https://aifitnessapi.com/engagement/app-intents-start-workout - Last reviewed: 2026-10-03 - Publisher: AIFitnessAPI (https://aifitnessapi.com) — independent, not sponsored - Cite as: "App Intents: Start a Workout from Siri and Shortcuts", AIFitnessAPI, https://aifitnessapi.com/engagement/app-intents-start-workout --- 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 | Type | Apple's description | Available from | What runs it, as Apple documents | |---|---|---|---| | `StartWorkoutIntent` | An App Intent for starting a workout | iOS 16.0, watchOS 9.0, macOS 13.0, tvOS 16.0 | The Action button on Apple Watch Ultra, once the person picks your app in Settings | | `PauseWorkoutIntent` | Lets someone pause your app's current workout session | iOS 16.0, watchOS 9.0, macOS 13.0, tvOS 16.0 | Action button and side button pressed together during your workout session | | `ResumeWorkoutIntent` | Lets someone resume your app's paused workout session | iOS 16.0, watchOS 9.0, macOS 13.0, tvOS 16.0 | The same two-button press while your session is paused | | `AppShortcutsProvider` | Provides an app's preconfigured shortcuts | iOS 16.0, watchOS 9.0, macOS 13.0, tvOS 16.0 | Siri, Spotlight, the Shortcuts app, and the Action button on supported iPhone models | | `LiveActivityIntent` | An intent that starts, pauses, or otherwise modifies a Live Activity when it runs | iOS 17.0, iPadOS 17.0 | Buttons and toggles in a Live Activity, controls, and any intent that must start a Live Activity from the background | 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. ```swift 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](/watch-apps/watchos-workout-app-anatomy). 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. ```swift 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. ```swift 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](/engagement/activitykit-live-activity-workout), 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](/watch-apps/mirroring-workouts-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. ## FAQ ### Which App Intents protocol puts a workout app on the Apple Watch Ultra Action button? StartWorkoutIntent. Apple documents that on Apple Watch Ultra this intent registers a start workout action for the Action button, and that after installing the app a person selects it under Settings, Action Button, by setting the action to Workout and the app to yours. The implementation needs a title, a workoutStyle parameter backed by an AppEnum or AppEntity, a list of suggestedWorkouts, a display representation and a perform method. Apple's symbol metadata lists the protocol from iOS 16 and watchOS 9, alongside PauseWorkoutIntent and ResumeWorkoutIntent, which handle the Action button and side button pressed together. [Permalink](https://aifitnessapi.com/engagement/app-intents-start-workout#faq-1) ### Why does pressing the Action button open my watch app without starting the workout? Apple documents two causes. If the app has never requested authorization for any HealthKit data types, the system just launches the app when the button is pressed and does not call the intent's perform method. And if perform does not start a workout session within 30 seconds, the system shows an error and the app stays in the foreground without a session, then goes to the background at the next wrist drop. Apple's guidance is to create and start the session first inside perform, and to schedule the HealthKit authorization request in a Task so the sheet does not hold up the start. [Permalink](https://aifitnessapi.com/engagement/app-intents-start-workout#faq-2) ### How many App Shortcuts should a fitness app define for Siri and Spotlight? Apple's App Intents sample states the best practice as App Shortcuts for only the most common actions in an app, usually between two and five intents and not more than ten. For a fitness app that typically means starting a workout and perhaps logging one, not settings or browsing screens. Apple's sample writes the application name token into each spoken phrase, and Apple says the system uses a semantic similarity index so similar wordings match without listing every variant. The shortcuts are available as soon as the app is installed, with no registration step. [Permalink](https://aifitnessapi.com/engagement/app-intents-start-workout#faq-3) ### Can a shortcut start a workout Live Activity without opening my iPhone app? Yes, through LiveActivityIntent, which Apple's symbol metadata lists from iOS 17. Apple documents that an app generally has to be in the foreground to start a Live Activity, but that when the system performs a LiveActivityIntent it launches the app's process without opening the app, runs the intent, and starts the Live Activity from its perform method. Apple's design guidance for Live Activities also recommends offering an App Shortcut that starts your Live Activity, for example from the Action button on iPhone. [Permalink](https://aifitnessapi.com/engagement/app-intents-start-workout#faq-4) ### Is there an App Intents protocol for ending or cancelling a workout? Not among the workout types Apple lists. The Hardware interactions topic in Apple's App Intents documentation lists StartWorkoutIntent, PauseWorkoutIntent and ResumeWorkoutIntent under workout support and nothing for ending a session. Apple's HKWorkoutSession documentation says Siri support extends to the Lock Screen so people can start, pause, resume or cancel workouts hands-free, and that apps can integrate Siri intents to enable it, but it does not name the intent types involved. We could not verify that mapping from Apple's pages, so treat any specific claim about it with care. [Permalink](https://aifitnessapi.com/engagement/app-intents-start-workout#faq-5)