App Intents Integration

Overview

Comprehensive guide to App Intents framework for exposing app functionality to Siri, Apple Intelligence, Shortcuts, Spotlight, and other system experiences. Replaces older SiriKit custom intents with modern Swift-first API.

Core principle App Intents make your app's actions discoverable across Apple's ecosystem. Well-designed intents feel natural in Siri conversations, Shortcuts automation, and Spotlight search.

When to Use This Skill

• Exposing app functionality to Siri and Apple Intelligence
• Making app actions available in Shortcuts app
• Enabling Spotlight search for app content
• Integrating with Focus filters, widgets, Live Activities
• Adding Action button support (Apple Watch Ultra)
• Debugging intent resolution or parameter validation failures
• Testing intents with Shortcuts app
• Implementing entity queries for app content

Related Skills

• app-shortcuts-ref — App Shortcuts for instant Siri/Spotlight availability without user setup
• core-spotlight-ref — Core Spotlight and NSUserActivity integration for content indexing
• app-discoverability — Strategic guide for making apps surface system-wide across all APIs

System Experiences Supported

App Intents integrate with:

• Siri — Voice commands and Apple Intelligence
• Shortcuts — Automation workflows
• App Shortcuts — Pre-configured actions available instantly (see app-shortcuts-ref)
• Spotlight — Search discovery
• Focus Filters — Contextual filtering
• Action Button — Quick actions (Apple Watch Ultra)
• Control Center — Custom controls
• WidgetKit — Interactive widgets
• Live Activities — Dynamic Island updates
• Visual Intelligence — Image-based interactions

Visual Intelligence Integration

IntentValueQuery

Allow users to circle objects in the Visual Intelligence camera and see matching results from your app:

@UnionValue
enum VisualSearchResult {
    case landmark(LandmarkEntity)
    case collection(CollectionEntity)
}

struct LandmarkIntentValueQuery: IntentValueQuery {
    func values(for input: SemanticContentDescriptor) async throws -> [VisualSearchResult] {
        // Match visual input to app entities
    }
}

// Each entity type needs an OpenIntent
struct OpenLandmarkIntent: OpenIntent { /* ... */ }
struct OpenCollectionIntent: OpenIntent { /* ... */ }

Onscreen Entities

Associate app entities with visible content so users can ask Siri or ChatGPT about what's on screen:

struct LandmarkDetailView: View {
    let landmark: LandmarkEntity

    var body: some View {
        Group { /* View content */ }
        .userActivity("com.landmarks.ViewingLandmark") { activity in
            activity.title = "Viewing \(landmark.name)"
            activity.appEntityIdentifier = EntityIdentifier(for: landmark)
        }
    }
}

Core Concepts

The Three Building Blocks

1. AppIntent — Executable actions with parameters

struct OrderSoupIntent: AppIntent {
    static var title: LocalizedStringResource = "Order Soup"
    static var description: IntentDescription = "Orders soup from the restaurant"

    @Parameter(title: "Soup")
    var soup: SoupEntity

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

    func perform() async throws -> some IntentResult {
        guard let quantity = quantity, quantity < 10 else {
            throw $quantity.needsValue("Please specify how many soups")
        }

        try await OrderService.shared.order(soup: soup, quantity: quantity)
        return .result()
    }
}

2. AppEntity — Objects users interact with

struct SoupEntity: AppEntity {
    var id: String
    var name: String
    var price: Decimal

    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Soup"

    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(name)", subtitle: "$\(price)")
    }

    static var defaultQuery = SoupQuery()
}

3. AppEnum — Enumeration types for parameters

enum SoupSize: String, AppEnum {
    case small
    case medium
    case large

    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Size"
    static var caseDisplayRepresentations: [SoupSize: DisplayRepresentation] = [
        .small: "Small (8 oz)",
        .medium: "Medium (12 oz)",
        .large: "Large (16 oz)"
    ]
}

AppIntent: Defining Actions

Essential Properties

struct SendMessageIntent: AppIntent {
    // REQUIRED: Short verb-noun phrase
    static var title: LocalizedStringResource = "Send Message"

    // REQUIRED: Purpose explanation
    static var description: IntentDescription = "Sends a message to a contact"

    // OPTIONAL: Discovery in Shortcuts/Spotlight
    static var isDiscoverable: Bool = true

    // OPTIONAL: Launch app when run
    static var openAppWhenRun: Bool = false

    // OPTIONAL: Authentication requirement
    static var authenticationPolicy: IntentAuthenticationPolicy = .requiresAuthentication
}

Parameter Declaration

struct BookAppointmentIntent: AppIntent {
    // Required parameter (non-optional)
    @Parameter(title: "Service")
    var service: ServiceEntity

    // Optional parameter
    @Parameter(title: "Preferred Date")
    var preferredDate: Date?

    // Parameter with requestValueDialog for disambiguation
    @Parameter(title: "Location",
               requestValueDialog: "Which location would you like to visit?")
    var location: LocationEntity

    // Parameter with default value
    @Parameter(title: "Duration")
    var duration: Int = 60
}

Parameter Summary (Siri Phrasing)