Any app can offer shortcuts for immediately performing useful actions, or for opening the app to specific screens so the user can quickly initiate tasks.
For developer guidance, see SiriKit > Shortcuts.
Types of Shortcuts
SiriKit supports several types of shortcuts.
A donated shortcut is an app-specific action the user performs regularly and may want to perform again. For instance, a user might use a soup app to order clam chowder every Friday at noon. The soup app could recognize this action as a predicable user activity, and donate an Order my favorite soup shortcut to the system. Using signals like location, time of day, and type of motion (such as walking, running, or driving), the system can intelligently predict just the right time and place for the shortcut. The system can then offer the shortcut to the user through an iOS lock screen notification, search results, media playback controls on the lock screen (for media playback shortcuts), or the Siri face on Apple Watch.
For developer guidance, see Donating Shortcuts.
A suggested shortcut is an app-specific action the user hasn’t performed yet, but still might find useful. For example, if the user of a soup app has never ordered the soup of the day, the app might still want to give the user a way to do this with an Order soup of the day shortcut. In this case, the app provides a suggested shortcut for inclusion in Settings > Siri & Search, and the Shortcuts iOS app. The user can visit these locations to add the shortcut to Siri. An app can also expose an Add to Siri button for enabling a suggested shortcut directly in the app.
For developer guidance, see Suggesting Shortcuts to Users.
A relevant shortcut is an app-specific action the user hasn't performed, that includes relevancy information like location and time of day. These shortcuts are presented intelligently at appropriate times and places on the Siri face on Apple Watch.
For developer guidance, see Defining Relevant Shortcuts for Your App.
Consider offering shortcuts for common, useful activities. Actions people do or might do often—not once—make good shortcuts. In general, shortcuts should be for tasks that aren't overly complex.
Design long-lived shortcuts. Avoid offering shortcuts that are date-specific or associated with temporary data. For example, a travel app probably shouldn’t have shortcuts for showing specific itineraries. A better shortcut might be one that shows the user’s upcoming trips.
Make sure shortcuts aren’t context-specific. People can run shortcuts in different ways, at different times, and using different devices. A shortcut should run successfully and be a great experience regardless of how, when, and where it's initiated. For example, a workout app shouldn't donate an End workout shortcut because it would be a bad experience if the shortcut is suggested when the user isn't working out.
Don’t request user permission to use Siri before offering Siri Shortcuts in your app. If your app supports only Siri Shortcuts, you don’t need to get permission to use Siri before letting users create and use shortcuts. Asking for permission creates user friction and could discourage people from using your app's shortcuts.
Use system intents when available. If a built-in SiriKit intent represents your shortcut’s purpose, adopt that intent instead of defining your own custom intent. For example, if you’d like to offer a shortcut for sending a message, adopt INSendMessageIntent. If you’d like to offer a shortcut for playing media, adopt INPlayMediaIntent.
Support background operation. The best shortcuts run quickly and don’t pull people out of their current context. Strive to support shortcuts that can run in the background without bringing your app to the front.
Categorize custom intents. A category informs the system about the general function of a shortcut—like create, order, share, or search. This affects the text, icon, and spoken dialog presented to the user when a shortcut is offered by the system or used with Siri.
Make donations for common user actions. A donation should occur every time the user performs an action (not just the first time) to help the system more accurately predict the best time and place to offer a shortcut.
Donate shortcuts only for actions the user actually performs. Never donate a shortcut for something the user didn't do. If a user never orders soup, for example, a soup app should not donate a soup-ordering shortcut.
Remove donations with corresponding data. If information required by a donated shortcut no longer exists, your app should delete the donation so the shortcut isn’t suggested anymore. For example, if a user deletes a contact in a messaging app, any donations for messaging that contact should also be deleted. For developer guidance, see Deleting Donated Shortcuts. A user must manually remove shortcuts they’ve added to Siri.
Shortcut Titles and Subtitles
Shortcut titles and subtitles appear when shortcuts are suggested by the system, added to Siri, or edited by the user.
Be concise, but descriptive. A title should clearly convey what happens when the shortcut runs. A subtitle can provide additional detail that supplements—but doesn't duplicate—the title.
Use sentence-style capitalization without punctuation for titles, and start with a verb. Think of a shortcut title as an instruction.
|Order my favorite soup|
|Get today’s forecast|
Place important information first. Long titles and subtitles may be truncated in certain contexts depending on the device’s screen size.
Exclude your app name. The system already identifies the app associated with a shortcut.
Use quotation marks only when referencing specific phrases used by shortcuts. For example:
|Send “I’m coming home late tonight” to Christine|
|Send I’m coming home late tonight to Christine|
|Play The Science Podcast|
|Play “The Science Podcast”|
|Order clam chowder|
|Order “clam chowder”|
Localize titles and subtitles. Providing content in multiple languages ensures an equally great experience for people everywhere.
Shortcuts presented to the user include an image that gives additional visual context. By default, this image is your app icon.
Use custom imagery for a more engaging user experience. The shortcut for Order my favorite soup, for example, might show a bowl of the user’s favorite soup.
Provide relevant shortcut images at the right size. An image that appears on the Siri face on the 44mm Apple Watch should measure 68px × 68px (34pt × 34pt @2x). The system scales down the image for smaller watches.
Adding and Editing Shortcuts
People can add, edit, and delete shortcuts in Settings, but you can also expose these features inside your iOS app.
Offer an Add to Siri button to let people add a shortcut for a common action. When the user taps the button, the standard shortcut view appears and allows them to record a custom voice command and add the shortcut. After the shortcut is added, the button’s text automatically changes to Added to Siri and the recorded invocation phrase is included. These changes show people that they successfully added a shortcut, and, crucially, remind them what to say when asking Siri to run it. If you let people create shortcuts for several actions in your app, see Offering Multiple Siri Shortcuts for guidance on displaying several shortcuts in one screen.
Accommodate the variable width of the Add to Siri button. The width of the button varies in different locales and when updated to display the user's invocation phrase.
Maintain clear space around the Add to Siri button. At minimum, leave padding of 1/10 the button's height on all sides of the button.
If you create a custom button to add a shortcut, provide an experience that mirrors the system-provided one. Your custom button should display the phrase Add to Siri. Don’t display phrases such as add voice command, create voice shortcut, or make voice prompt, and don’t display the Siri icon in your custom button. Also, don’t use the Siri icon as a button, or display it anywhere else in your interface. (See Offering Multiple Siri Shortcuts for guidance on offering many shortcuts in one screen.)
After people use your custom button to add a shortcut, it's important to display the recorded invocation phrase to help them remember it. If you created a custom Add to Siri button, you can follow the system-provided experience and update the button to display Added to Siri and the phrase.
Let people edit and remove added shortcuts. When the user taps the invocation phrase displayed in your app after adding a shortcut, show the standard shortcut view again so the user can rerecord the phrase or delete the shortcut.
Keep any shortcuts displayed in your app up to date. People can add, remove, and update your app’s shortcuts in Settings > Siri & Search. However, Settings doesn't notify your app when these changes occur. It's your app’s responsibility to keep its interface up to date with the latest shortcut changes.
For developer guidance, see Shortcut Management.
Add to Siri Button Styles
The Add to Siri button is available in several visual styles.
Offering Multiple Siri Shortcuts
If your app contains more than a few Siri Shortcuts, consider creating a dedicated area of the app to display them. A dedicated screen makes it easy for people to see all of your app’s shortcuts at a glance and to add the shortcuts they want to use.
Use an unambiguous title for your list of shortcuts. For example, using "Siri Shortcuts" for the navigation bar title clearly communicates the purpose of the screen.
Consider creating a custom Add button for use in a list of shortcuts. The system-provided Add to Siri button can add too much visual weight when it's used several times in one view. If the screen makes it clear that all the items in the list are Siri Shortcuts, you can display a simpler button that uses "Add" or "+" for each shortcut in the list.
Provide feedback when a shortcut has been added. Show people that they've successfully added a shortcut by replacing the Add button with an Edit button and displaying the phrase they recorded. Alternatively, you can remove the Add button and let people tap the phrase they recorded to open an editing view.
Suggesting Phrases for Siri Shortcuts
People record custom phrases when adding suggested shortcuts to Siri, but your app can provide phrases that appear as suggestions.
Keep suggested phrases short and memorable. Bear in mind that people must speak phrases verbatim to initiate shortcuts. Long or confusing phrases may result in mistakes and frustration. Ideally, phrases should contain two or three words. More words will be harder for people to remember, and phrases that are too long will get truncated. A playful phrase, like Soup time, is easier to remember than a serious phrase, like Order my favorite soup.
Keep suggested phrases generic. Suggested phrases shouldn’t imply natural language understanding. For example, a specific phrase like Order a large clam chowder might lead someone to think they can use a variation like Order a small lobster bisque. A more generic phrase, like Soup time, helps avoid such a misunderstanding and remains intuitive.
Don’t commandeer core Siri commands. For example, your app should never suggest a phrase like Call 911 or include the text Hey Siri.
Referring to Siri and Siri Shortcuts
Don’t refer to Siri using pronouns such as “she,” “him,” or “her.” Ideally, just use the word Siri. For example, After you add a shortcut to Siri, you can run the shortcut anytime by asking Siri.
When referring to Siri Shortcuts, always typeset both words with a capital S and make sure that Shortcuts is plural. For example, Siri Shortcuts provide a quick way to get things done in your app with just a tap or by asking Siri.
When referring to individual shortcuts (that is, not the feature or the Shortcuts app), use lower case. For example, Run a shortcut by asking Siri or tapping a suggestion on the lock screen.
Use the right terminology when describing how people can use Siri Shortcuts in your app. Users run shortcuts by asking Siri, so your wording should be very similar to phrases like Run a shortcut by asking Siri or Run the shortcut by asking Siri with your personalized phrase (localized as appropriate). To encourage users to create or use Siri Shortcuts, avoid using phrases like add voice shortcuts, make a voice command, create a voice prompt, or any other variation. Instead, you can use one of the following phrases (localized as appropriate):
- Add to Siri
- Add a shortcut to Siri to run with your voice
- Add a shortcut to Siri to run anytime by asking Siri
Use translations of your app name and the word Shortcuts—but not Siri—when referring to them in a localized context. For example, use the translated version of Shortcuts when referring to specific shortcuts in Settings > Siri & Search > My Shortcuts.