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 the Shortcuts iOS app. 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.
Best Practices for Designing Shortcuts
Offer shortcuts that accelerate common, useful activities. Take advantage of the familiarity people have with your app and create shortcuts for actions that people are already doing often—don't create a shortcut for an action that people are likely to do only once.
In general, create shortcuts for tasks that aren't overly complex. People benefit the most from shortcuts that reduce the number of steps required to complete a task. Don't spoil this benefit by requiring people to engage in a lengthy conversation with your app. You can also reduce the likelihood of user errors by limiting shortcuts to clearly defined tasks.
Design long-lived shortcuts. Avoid offering shortcuts that are date-specific or associated with temporary data. For example, a travel app probably shouldn’t offer a shortcut for each specific itinerary. A better shortcut would let people choose from all of their upcoming trips using follow-up questions.
Provide shortcuts that aren’t limited by context. People can run shortcuts in different ways, at different times, and using different devices. A shortcut runs successfully and is 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. Doing so also ensures that people can complete the shortcut's task in hands-free and eyes-free scenarios.
Pick a custom intent category that closely matches your shortcut's task. 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.
If your app handles reservations, consider donating them to the system. These items—such as ticketed events or reservations for restaurants, flights, movies, and other travel itineraries—automatically appear as suggestions in Calendar or Maps. For example, donated reservations can appear on the lock screen with a suggestion to check in with your app, or as a reminder that tells people when to leave, based on current traffic conditions. Be sure to donate reservation information only while people are actively viewing details for a specific reservation. Donating reservations at other times—such as while people are searching or viewing a list of all their reservations—can surprise people, because the system presents a banner notification when it detects new events in your app.
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.
Creating 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.
Suggesting Phrases for Siri Shortcuts
Your app provides default phrases for Siri Shortcuts during setup. People can set up personalized phrases when adding suggested shortcuts to Siri.
Keep suggested phrases short and memorable. Bear in mind that people must speak your phrases, so 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.
Make sure the phrases you suggest are accurate and specific. Phrases like Reorder coffee or Order my usual coffee clearly describe what the shortcut does, which makes it easier for people to remember the phrase later. Also make sure that your suggested phrases are specific to each shortcut's scope: For example, Watch baseball is clearer and more memorable than Watch sports. However, suggested phrases shouldn’t imply natural language understanding. For example, a phrase like Order a large clam chowder might lead someone to think they can use a variation like Order a small lobster bisque.
Don’t commandeer core Siri commands. For example, your app should never suggest a phrase like Call 911 or include the text Hey Siri.
Including Shortcut Images
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 action-specific images and define key parameters to make it easy for people to find your shortcuts when they search in the Shortcuts app.
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.
Offering Follow-Up Questions
Shortcuts can offer follow-up questions that let people do more with a single shortcut by refining its results on the fly. For example, if you offer an Order my usual coffee shortcut, you can help people get exactly what they want by asking them questions like What size?, Which location?, or Which of your usual orders? For developer guidance, see Improving User Interaction with Siri and Siri Shortcuts.
Design shortcuts that require as few follow-up questions as possible. Often, a shortcut can fulfill a request without asking any follow-up questions. Although follow-up questions make shortcuts more flexible, you want don't want to force people into a long interaction. In most cases, it's best to offer just one or two follow-up questions.
Make sure each follow-up question is meaningful. Ideally, each follow-up question helps people make an important choice. If options you present—or, worse, the questions themselves—are too granular or too similar, the conversation can become repetitive, and people may feel like using your shortcut is too much work.
Support chaining of follow-up questions when it makes sense. For example, an app that helps people order food might offer options for pickup or delivery, but ask for a specific location only after people choose the delivery option.
Predefine useful defaults. People can change the parameters of follow-up questions when they add shortcuts to Siri. You can make it easier for people to do this by setting default values that are based on the user's current context. Say you offer a Reorder soup shortcut with a follow-up question that asks people to specify the order. When people add this shortcut to Siri from the order's detail view, you could preconfigure the shortcut to include that specific order.
Consider providing dynamic options. For example, if your shortcut relies on location, you can help ensure accurate, up-to-date results by offering the options that are currently closest to the user. You can also provide dynamic options when people first add a shortcut to Siri.
Help people understand errors and failures. For example, if you ask a follow-up question that lets people choose a flavor, you need to provide a useful response if the person's choice is sold out. The system provides default errors for cases like reaching a maximum or minimum value, but you should tailor errors so that they're specific to your shortcut's task. For example, if chicken noodle soup has sold out, respond with an error like Sorry, we're out of chicken noodle soup. and not Sorry, we can't complete your order.
Ensure that your shortcut works well in every scenario. Make it easy for people to run your shortcut, regardless of how they initiate it. For example, you should be prepared for people to run your shortcut using their voice on devices with and without a screen, from suggestions on the lock screen or the Siri face on Apple Watch, from search, and within a multistep shortcut. For guidance on accommodating voice-only scenarios, see Responses.
Letting People Add and Edit Shortcuts
People can add, edit, and delete shortcuts in the Shortcuts app, 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, you could use follow-up questions to consolidate the actions or display several shortcuts in one screen. For guidance, see Offering Follow-Up Questions and Offering Multiple Siri Shortcuts.
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. In addition, you can customize the corner radius of the buttons to match your app's interface.
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. Alternatively, consider offering follow-up questions to support a couple of additional options for a single shortcut.
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.