Appintents

App Intents Documentation

Search these docs to answer questions about App Intents APIs.

Return Format

Always include: 1. Summary - Answer the question concisely 2. File paths - List relevant files for full details, e.g.:

• appintents-appintent.md for AppIntent protocol
• appintents-appshortcut.md for creating shortcuts

Files

• appintents-overview.md - Framework overview and intent types
• appintents-appintent.md - AppIntent protocol and implementation
• appintents-appshortcut.md - App Shortcuts and phrases

Navigation: App Intents

Protocol

AppIntent

Available on: iOS 16.0+, iPadOS 16.0+, Mac Catalyst, macOS 13.0+, tvOS 16.0+, visionOS, watchOS 9.0+

An interface for providing an app-specific capability that people invoke from system experiences like Siri and the Shortcuts app.

protocol AppIntent : PersistentlyIdentifiable, _SupportsAppDependencies, Sendable

Overview

To expose your app’s functionality to system experiences like Siri or the Shortcuts app, and to support interactivity in widgets, you need to implement the AppIntent protocol. Use it to provide phrases that can launch the functionality, describe the needed data for the functionality you make available, and implement the method that performs the functionality.

The system instantiates an app intent you create parameter-less using the init()) initializer whenever a person invokes it through a system service like Siri, Shortcuts, and so on. If available, the system sets parameters based on user input or other available sources. With set parameters, the system attempts to resolve them in the order of their declaration in the AppIntent body. After it resolves all parameters, the system calls perform()) to perform the app intent with its configured parameters. Note that the system retains the app intent and its output only for the duration of the invocation.

Related sessions from WWDC22: Session 10032: Dive into App Intents.

Implement the AppIntent Protocol

Declare a custom intent type by defining a structure that conforms to the AppIntent protocol:

struct OrderSoupIntent: AppIntent {
   static var title = LocalizedStringResource("Order Soup")
   static var description = IntentDescription("Orders a soup from your favorite restaurant.")
}

Then, declare the AppIntent’s parameters. When you implement an AppIntent type, parameters must be declared with the @Parameter property wrapper. For more information about declaring parameters, see Adding parameters to an app intent.

struct OrderSoupIntent: AppIntent {
   @Parameter(title: "Soup")
   var soup: Soup

   @Parameter(title: "Quantity")
   var quantity: Int?
}

Next, implement the required perform())function: Validate your intent’s parameters, execute the intent, and return an IntentResult that represents the output of a completed intent; for example, a PerformResult.

struct OrderSoupIntent: AppIntent {
    @Parameter(title: "Soup")
    var soup: Soup

    @Parameter(title: "Quantity")
    var quantity: Int?

    static var parameterSummary: some ParameterSummary {
        Summary("Order \(\.$soup)") {
            \.$quantity
        }
    }

    func perform() async throws -> some IntentResult {
        guard let quantity = quantity, quantity < 10 else {
            throw $quantity.needsValue
        }
        soup.order(quantity: quantity)
        return .result()
    }
}

Inherits From

• PersistentlyIdentifiable
• Sendable
• SendableMetatype

Inherited By

• AssistantIntent
• AssistantSchemaIntent
• AudioPlaybackIntent
• AudioRecordingIntent
• AudioStartingIntent
• CameraCaptureIntent
• ControlConfigurationIntent
• CustomIntentMigratedAppIntent
• DeleteIntent
• DeprecatedAppIntent
• ForegroundContinuableIntent
• LiveActivityIntent
• LiveActivityStartingIntent
• OpenIntent
• PauseWorkoutIntent
• PlayVideoIntent
• PredictableIntent
• ProgressReportingIntent
• PushToTalkTransmissionIntent
• ResumeWorkoutIntent
• SetFocusFilterIntent
• SetValueIntent
• ShowInAppSearchResultsIntent
• SnippetIntent
• StartDiveIntent
• StartWorkoutIntent
• SystemIntent
• TargetContentProvidingIntent
• UISceneAppIntent
• URLRepresentableIntent
• UndoableIntent
• WidgetConfigurationIntent

Conforming Types

• EmptySnippetIntent
• OpenURLIntent

Creating an app intent

• init()) Creates an app intent.

Specifying the authentication policy

• authenticationPolicy A property that defines the authentication policy that indicates whether this app intent requires the device to be unlocked or otherwise authenticated.
• IntentAuthenticationPolicy An enumeration that describes the authentication policy to use when running an app intent.

Configuring the metadata

• title A short, localized, human-readable string that describes the app intent using a verb and a noun in title case.
• description A description of the app intent that the system shows to people.
• openAppWhenRun A boolean property that tells the system to consider the app intent even if its app is not in the foreground.
• isDiscoverable A boolean value that determines whether system features such as Shortcuts and Spotlight can discover this app intent.

Performing the action

• perform()) Performs the intent after resolving the provided parameters.
• systemContext Context information that’s available while the system performs the app intent’s action.
• PerformResult

Requesting confirmation

• requestConfirmation()) Requests user confirmation before performing the app intent.
• requestConfirmation(conditions:actionName:dialog:)) Requests user confirmation before performing the app intent.
• requestConfirmation(conditions:actionName:dialog:showDialogAsPrompt:content:)) Request user confirmation before performing the app intent.
• requestConfirmation(result:confirmationActionName:showPrompt:)) Requests user confirmation before performing the app intent.
• requestConfirmation(output:confirmationActionName:showPrompt:))

Donating the intent to the system

• donate()-1e60c) Donates the intent to the transcript.
• donate()-jp6k) Donates the intent to the transcript.
• donate(result:)-36cia) Donates the intent and optional result to the transcript.
• donate(result:)-9b25i) Donates the intent and optional result to the transcript.
• callAsFunction(donate:)-3qvbt)
• callAsFunction(donate:)-7v1om)

Summarizing the parameters

• SummaryContent The type of parameter summary representing this intent.
• parameterSummary Defines the summary of this intent in relation to how its parameters are populated.
• parameterSummary
• ParameterSummaryBuilder A result builder that allows you to declaratively describe a parameter summary.
• AppIntent.Parameter
• AppIntent.Case
• AppIntent.DefaultCase
• AppIntent.Summary
• AppIntent.Switch
• AppIntent.When

URL representation

• IntentURLRepresentation The URL representation of an app intent.

Instance Methods

• continueInForeground(_:alwaysConfirm:)) A method you call to ask a person to continue an action in the foreground.
• needsToContinueInForegroundError(_:alwaysConfirm:)) A method you call to ask a person to continue an intent’s action in the foreground after it encounters an error.
• requestChoice(between:dialog:)) Pauses the app intent to request a person to choose from several options.
• requestChoice(between:dialog:content:)) Pauses the app intent to request a person to choose from several options.
• requestChoice(between:dialog:view:)) Pauses the app intent to request a person to choose from several options.
• requestConfirmation(conditions:actionName:dialog:showDialogAsPrompt:snippetIntent:)-3vewj)
• requestConfirmation(conditions:actionName:dialog:showDialogAsPrompt:snippetIntent:)-jxb8) Requests user confirmation before performing the app intent.

Type Aliases

• AppIntent.Option A convenience type alias that represents a choice option within the scope of an app intent.

Type Properties

• supportedModes Defines the supported modes that describe the behavior of your app intent.

General actions

• IntentDescription The human-readable description and metadata for an app intent.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.

Navigation: App Intents

Structure

AppShortcut

Available on: iOS 16.0+, iPadOS 16.0+, Mac Catalyst, macOS 13.0+, tvOS 16.0+, visionOS, watchOS 9.0+

A type that defines a preconfigured shortcut for a specific app intent.

struct AppShortcut

Overview

Related sessions from WWDC22: Session 10170: Implement App Shortcuts with App Intents, and session 10169: Design App Shortcuts.

Note: Apple may extract anonymized App Shortcuts data such as localized phrases, display representation values, and the title and description of related intents. Machine learning models use this data when training to help improve the App Shortcuts experience.

Creating an app shortcut

• init(intent:phrases:shortTitle:systemImageName:)-8yntq) Initializes an App Shortcut with phrases that run the app intent, a title, and an image.
• init(intent:phrases:shortTitle:systemImageName:parameterPresentation:)) Initializes an App Shortcut with phrases that run the app intent, a title, an image, and specified parameters.
• init(intent:phrases:shortTitle:systemImageName:)-2hk1x) Initializes an App Shortcut with phrases that run the app intent, a title, and an image.

App Shortcut definition

• AppShortcutsContent
• AppShortcutPhrase A spoken phrase that causes the system to run the corresponding App Shortcut.
• AppShortcutPhraseToken Dynamic values you can include in the spoken phrases that run your shortcut.
• NegativeAppShortcutPhrase An object that represents a negative phrase.
• NegativeAppShortcutPhrases This is a set of negative phrases, which will all be added to the app-level negative training set. All the training data specified here, will be used to completely bypass your app
• NSAppIconActionTintColorName The tint color to apply to text and symbols in the App Shortcuts platter.
• NSAppIconComplementingColorNames The names of the colors to use for the background of the App Shortcuts platter.
• AppShortcutsBuilder A result builder that allows you to declaratively describe the App Shortcuts that your app provides.
• ShortcutTileColor Describes the colors a shortcut tile in the Shortcuts app.

---

Extracted from Apple DocC JSON by apple-skills tooling. This is unofficial content. All documentation belongs to Apple Inc.