--- title: Adding User Interactivity with Siri Shortcuts and the Shortcuts App framework: sirikit role: article role_heading: Article path: sirikit/adding-user-interactivity-with-siri-shortcuts-and-the-shortcuts-app --- # Adding User Interactivity with Siri Shortcuts and the Shortcuts App Add custom intents and parameters to help users interact more quickly and effectively with Siri and the Shortcuts app. ## Overview Overview You can offer your app’s unique capabilities throughout the system by designing custom intents. You may also want to create a custom intent that provides the same functionality as a system intent, to offer users more flexibility for incorporating that functionality into a multi-step shortcut. Define custom intents and their parameters in an intents definition file. Xcode uses this file to generate an INIntent subclass and related data types for each of your intents. When the user invokes your shortcut with their voice, Siri starts a dialog to collect the additional information needed to complete the shortcut. In the Shortcuts app, the user can make changes to what the shortcut will do when it’s invoked. To get an app that integrates custom intents and parameters, see Soup Chef: Accelerating App Interactions with Shortcuts and download the Soup Chef sample app. Add an Intent Definition File to Your App Target Choose File > New > File to add a new SiriKit Intent Definition File to your Xcode project. Make sure that you select your app target. Define Your Intents Create the new intent and define what the intent does. Select the created Intents.intentdefiniton file. In the Xcode Menu Bar, choose Editor > New Intent. Name your intent using a VerbNoun convention, like SetAlarm, CheckOrderStatus, and so on. Make sure the category you select matches your intent’s purpose because the chosen category defines the default Siri dialog, as you will see in a later section. In the title field, add a human-readable title for the intent. In the Description field, add a short sentence that describes what the intent does. The figure below shows a custom intent named OrderSoup with the category, title, and description set. note: Xcode automatically creates the following response codes for a custom intent: unspecified, ready, continueInApp, inProgress, success, failure, and failureRequiringAppLaunch. Define the Intent Parameters Before you can use the intent, you need to define the intent’s parameters such as soup, quantity, and so on. Create a new parameter by clicking the plus button in the Parameters field and selecting either a system parameter type or a custom type in the Type field. System types are predefined by the system, and custom types allow you to create your own types. Parameter names must start with a lowercase character while custom type names must start with an uppercase character. By default, Xcode selects the User-facing checkbox. This controls whether the parameter is configurable in the Shortcuts app and resolvable at runtime in both Siri and the Shortcuts app. Add Parameter Metadata and Siri Dialog Data Siri can prompt users to complete shortcuts that require additional input based on the parameter metadata you provide. Set the Input fields for each parameter that you want the user to have control over, such as allowing them to order different quantities of soup through a shortcut. You can also customize the Siri dialog for each parameter resolution result. Enter the phrase you want Siri to say to the app user in the Prompt field. Establish Relationships Between Parameters Use relationships between parameters to determine whether certain parameters should be prompted by voice in Siri based on their association with their parent parameter. To set the parent parameter: Expand the Relationship section. Select the desired parameter from the Parent Parameter drop-down. Select when to show the parameter from the Show If Parent drop-down. If the parent has to have an exact value, select the value from the Value drop-down. The following example shows the storeLocation parameter has a child relationship to the orderType parent parameter. The orderType parameter is an enum with two values, pickup and delivery. When the user tells Siri they will pick up their order, the storeLocation value is automatically used. Define User-Configurable Shortcuts User-configurable shortcuts are shortcuts that the user can configure in the Shortcuts app, and use interactively in Siri. To enable a shortcut for user configuration: Select the Intent is user-configurable checkbox. Fill in the Summary field. The following example shows a Shortcut that supports the soup, orderType, and deliveryLocation parameters. The summary contains the soup and orderType parameters with the deliveryLocation in the More Options section. Set Intent Responses and Outputs An intent response represents the result of the intent’s action, such as ordering soup. Response templates allow Siri to respond with an appropriate dialog when a success or failure occurs. Add properties to allow passing of data into Siri dialogs or into the shortcut output. The output allows the user to use the result of your shortcut with other actions in the Shortcuts editor. The voice-only dialog is spoken instead of the printed dialog in circumstances where the user isn’t looking at a screen, such as on HomePod, CarPlay, and AirPods. The following example shows the response for a successful order. It provides the total amount, the user’s order, and the estimated wait time. ## See Also ### Articles - [Defining Relevant Shortcuts for the Siri Watch Face](sirikit/defining-relevant-shortcuts-for-the-siri-watch-face.md) - [Deleting Donated Shortcuts](sirikit/deleting-donated-shortcuts.md) - [Dispatching intents to handlers](sirikit/dispatching-intents-to-handlers.md) - [Improving Siri Media Interactions and App Selection](sirikit/improving-siri-media-interactions-and-app-selection.md) - [Improving interactions between Siri and your messaging app](sirikit/improving-interactions-between-siri-and-your-messaging-app.md) - [Registering Custom Vocabulary with SiriKit](sirikit/registering-custom-vocabulary-with-sirikit.md) - [Confirming the Details of an Intent](sirikit/confirming-the-details-of-an-intent.md) - [Handling an Intent](sirikit/handling-an-intent.md) - [Resolving the Parameters of an Intent](sirikit/resolving-the-parameters-of-an-intent.md) - [Generating a List of Ride Options](sirikit/generating-a-list-of-ride-options.md) - [Handling the Ride-Booking Intents](sirikit/handling-the-ride-booking-intents.md) - [Donating Reservations](sirikit/donating-reservations.md) - [Specifying Synonyms for Your App Name](sirikit/specifying-synonyms-for-your-app-name.md) - [Intent Phrases](sirikit/intent-phrases.md) - [Localizing Your Vocabulary for Chinese Dialects](sirikit/localizing-your-vocabulary-for-chinese-dialects.md)