Shortcuts and Suggestions
When you support shortcuts, people have a variety of ways to discover and interact with the custom and system intents your app provides. For example:
- Siri can suggest a shortcut for an action people have performed at least once by offering it in search results, on the lock screen, and in the Shortcuts app.
- Your app can supply a shortcut for an action that people haven't done yet, but might want to do in the future, so that the Shortcuts app can suggest it or it can appear on the Siri watch face.
- People can use the Shortcuts app to view all their shortcuts and even combine actions from different apps into multistep shortcuts.
- People can also use the Shortcuts app to automate a shortcut by defining the conditions that should run it, like time of day or current location.
- When you provide an Add to Siri button for your custom intent, people can create a shortcut they can run with their voice (for guidance, see Help People Add Shortcuts).
The Shortcuts app is also available on Apple Watch running watchOS 7 and later. For developer guidance, see SiriKit > Shortcuts.
Make Shortcuts Widely Available
Providing information about the actions your app supports helps the system offer them to people in various ways. For example, you donate an action when people actually perform it so that the system can offer it later as a shortcut in search results, throughout the Shortcuts app, or as a Siri Suggestion on the lock screen. You can also tell the system about shortcuts for actions people haven't taken yet or make a shortcut available on the Siri watch face (for guidance, see Suggest Shortcuts People Might Want to Add to Siri and Display Shortcuts on the Siri Watch Face).
Make a donation every time people perform the action. When you donate a shortcut each time people perform the associated action, you help the system more accurately predict the best time and place to offer the shortcut.
Only donate actions that people actually perform. For example, a coffee-ordering app should donate the Order coffee shortcut every time people order coffee, but it shouldn't make this donation when people do something else, like browse the menu.
Remove donations for actions that require corresponding data. If information required by a donated action no longer exists, your app should delete the donation so the shortcut isn’t suggested anymore. For example, if people delete a contact in a messaging app, the app should delete donations for messaging that contact. For developer guidance, see Deleting Donated Shortcuts. When people create a shortcut themselves, only they can delete it.
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 uses current traffic conditions to recommend when people should leave. Be sure to donate reservation information only when people create, view, or edit that reservation. Donating reservations at other times — such as while people are searching or viewing a list of all their reservations — can be a surprise, because the system presents a banner notification when it detects new events in your app.
For developer guidance, see Donating Shortcuts.
Suggest Shortcuts People Might Want to Add to Siri
If your app supports an action that people haven't performed yet, but might find useful, you can provide a suggested shortcut to the system so that people can discover it. For example, if people use a coffee-ordering app to order their daily coffee, but not to order a holiday special, the app might still want to give them a way to do this with an Order holiday coffee shortcut.
Suggested shortcuts appear in both the Gallery and the shortcut editor in the Shortcuts app. Also, your app can display an Add to Siri button that people can use to enable a suggested shortcut while they're in your app. For developer guidance, see Suggesting Shortcuts to Users.
Display Shortcuts on the Siri Watch Face
To have a shortcut appear on the Siri watch face, you define a relevant shortcut by including information like the time of day at which your shortcut is relevant and how the shortcut should be displayed on the Siri watch face. The information you supply lets the Siri watch face intelligently display your shortcut to people when they're in the appropriate context.
Create Shortcut Titles and Subtitles
Shortcut titles and subtitles appear when the system suggests them, or when people add shortcuts to Siri or edit them. In Siri Suggestions on iPhone and Apple Watch, a shortcut can also display an image.
Be concise, but descriptive. An effective title conveys what happens when the shortcut runs. A subtitle can provide additional detail that supplements — but doesn't duplicate — the title.
Start titles with a verb and use sentence-style capitalization without punctuation. Think of a shortcut title as a brief instruction.
|Order my favorite coffee|
|Show today’s forecast|
Lead with important information. 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.
Localize titles and subtitles. Providing content in multiple languages ensures an equally great experience for people everywhere.
Consider providing a custom image for a more engaging suggestion. For example, the shortcut for Order my favorite coffee could show a cup of the customer’s favorite coffee. Create an image that measures:
- 60pt × 60pt (180px × 180px @ 3x) to display in an iOS app
- 34pt × 34pt (68px × 68px @2x) to display on the Siri watch face on the 44mm Apple Watch (watchOS scales down the image for smaller watches)
Help People Add Shortcuts
People can add shortcuts from within your app or in the Shortcuts app.
Offer an Add to Siri button to let people add a shortcut for a common action. In the Add to Siri sheet that appears when people tap the button, they can type or record a custom voice command (or accept the app's suggested phrase) and add the shortcut. After the shortcut is added, the button’s text automatically changes to Added to Siri and it displays the invocation phrase. These changes show people that they successfully added the shortcut, and, crucially, remind them what to say when asking Siri to run it. For guidance on using the Add to Siri button, see Add to Siri Button Styles.
If you create a custom button to add a shortcut, provide an experience that mirrors the system-provided one. Display the phrase Add to Siri in your custom button. Don’t display alternative phrases like 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 Display Multiple Shortcuts in One Place for guidance on offering several shortcuts in one screen.)
After people use your custom button to add a shortcut, it's important to display their trigger phrase to help them remember it. If you created a custom Add to Siri button, you can mirror the system-provided experience and update the button to display Added to Siri followed by the phrase.
Let people edit and remove the shortcuts they added. When people tap the trigger phrase displayed in your app after adding a shortcut, show the shortcut editing view again so they can update the phrase or delete the shortcut.
Update the shortcuts your app displays. People can add, remove, and update your app’s shortcuts in the Shortcuts app. However, the Shortcuts app 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.
Provide Default Phrases for Shortcuts
Your app provides default phrases for shortcuts during setup. People can personalize these phrases when adding your shortcuts to Siri.
Keep phrases short and memorable. Bear in mind that people must speak your phrase verbatim, so long or confusing phrases may result in mistakes and frustration. Two- and three-word phrases tend to work best. More words can 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. It's also important to avoid implying that people can vary a shortcut's invocation phrase to get a different result. For example, people might interpret a phrase like Order a large clam chowder to mean that your shortcut will give them what they want if they substitute "small" for "large" and "lobster bisque" for "clam chowder."
Don’t commandeer core Siri commands. For example, your app should never suggest a phrase like Call 911 or include the text Hey Siri.
Make Shortcuts Customizable
When you define a parameter for each detail your app needs to perform an intent, people can customize the shortcut by editing these details in the Shortcuts app or your Add to Siri sheet.
To show people which details they can edit and how their edits affect the action, you provide a parameter summary. A parameter summary succinctly describes the action by using the parameters in a sentence that begins with a verb. For example, a customizable order coffee shortcut could display a parameter summary like "Order quantity coffee" where quantity and coffee are the parameters that people can edit. Here's an example of how the order coffee shortcut might look after people supply values for the quantity and coffee parameters.
Provide a parameter summary for each custom intent you support. At minimum, your parameter summary should include all parameters your intent requires, and any parameters that receive values from other apps or actions. The summary doesn't have to include optional parameters or parameters that people aren't likely to edit; if you omit parameters like these from the summary, people can still access them in the Show More section.
Craft a short parameter summary that's clearly related to your intent's title. When the intent title and the parameter summary are similar, it's easy for people to recognize the action regardless of where they view it. Aim to use the same words in the summary and the title — in particular, it's helpful to begin both phrases with the same verb. For example, if your intent title is “Search encyclopedia”, a good parameter summary could be “Search encyclopedia for search term”.
Aim for a parameter summary that reads like a sentence. Use sentence-style capitalization, but don't include ending punctuation. When possible, avoid punctuation entirely. Punctuation within a summary — especially colons, semicolons, and parentheses — can make the summary hard to read and understand.
Provide multiple parameter summaries when necessary. If your action includes a parameter that has a parent-child relationship with other parameters, you can provide multiple variants of the summary based on the current value of the parent parameter. For example, if your order coffee shortcut lets people specify whether they want to pick up their order or have it delivered, your parameter summary should reflect the current choice. In this scenario, you should create one parameter summary that helps people pick a store location and another summary that helps them pick a delivery address. Be sure to use a consistent grammatical structure and parameter order in all variants of the summary that you create.
Provide output parameters for information that people can use in a multistep shortcut. For example, an order coffee action might provide output that includes the estimated delivery time and the cost of the order. With this information, people could create a multistep shortcut that messages a friend about the delivery time and logs the transaction in their favorite budgeting app.
Consider defining an input parameter. When you define an input parameter for an action, the action can automatically receive output from a preceding action in a multistep shortcut. For example, if you support an action that applies a filter to an image, you might designate the image parameter as the input parameter so that it automatically accepts images from other actions. You configure an input parameter in your intent definition file (shown in "Define User-Configurable Shortcuts" in Adding User Interactivity with Siri Shortcuts and the Shortcuts App).
Help people distinguish among different variations of the same action. For example, an app that offers a send message action might use a contact photo to help people visually distinguish the various messages they send. To do this, choose the parameter that's most identifiable to people and designate it as the key parameter (shown in "Define User-Configurable Shortcuts" in Adding User Interactivity with Siri Shortcuts and the Shortcuts App). Be sure to provide an image for the key parameter every time you donate the action (for developer guidance, see INImage).
Avoid providing multiple actions that perform the same basic task. For example, instead of providing an action that adds text to a note and a different action that adds an image, consider providing a single action that lets people add both types of content. Providing a few high-level actions can make it easier for people to understand what the actions do when they're combined in a multistep shortcut.
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.
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.
Display Multiple Shortcuts in One Place
If your app contains more than a few 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 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 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.