Andrew Graham

Demystifying Siri, Part 2: Creating a Custom Intent

In Part 1 of our series on exploring Siri’s capabilities we discussed the possibility of creating a custom intent to make some of our app’s functionality accessible via Siri. At the end of this part we should be able to access our shortcut through the Shortcuts app, and by speaking a custom phrase in Siri.

Disclaimer: At the time of writing Xcode 11.6 is current as is iOS 13. Things may change in future versions!

Creating a new custom intent

I have an Xcode project called NumberRace. In order to create a custom intent we need to add a SiriKit Intent Definition File to this project. From the Xcode menu, select File > New > File… and, from the dialog box that appears, select “iOS” from the top and, in the “Resource” area, select SiriKit Intent Definition File. (In the diagram below, it’s on the right hand side in the middle row.)

The File chooser in Xcode.
Choosing the SiriKit Intent Definition File

This file can hold one or more intents so you can save the file in your preferred location as Intents.intentdefinition. There are no intents defined at the moment so let’s remedy that by clicking on the + sign at the bottom left.

A blank intent definition file
A blank intent definition file

Choose New Intent from the context menu.

The New Intent menu
Choosing a New Intent

We can now begin defining our custom intent. We’ll call it SolveGame - changing the name in the left hand pane has nicely updated the title in the right hand pane.

We now need a category. Remember that Siri only supports certain verbs in specific categories, for example Order, or Show, and choosing a category here influences how Siri talks about your intent. We’ll use a generic verb for now. **Run** will do. We’ll add a description here too.

Finally we don’t need user confirmation. If we were making a payment through an intent, a confirmation step is needed to make sure that the amount and payee are correct and there are no nasty financial slip-ups. In our case, there’s no harm done if any of the information is incorrect, so we can leave this box unchecked.

The Custom Intent section
Custom Intent properties

New in Xcode 12

New configuration options for Widgets, Shortcuts and Suggestions in Xcode 12
New options in Xcode 12

UPDATE: since writing this guide, it appears that a few more checkboxes have been added to this section of the Intents interface in Xcode 12. Make sure you also have the Configurable in Shortcuts and Suggestions boxes checked before proceeding!


We now need some parameters. To enable the solver to do its job, we’ll need:

Our target number is easy to define. Click on the + sign and type target. Is type is an Integer and it is user-facing. We can supply default, minimum and maximum values, and a phrase to request the parameter when we eventually hook our intent up to Siri’s voice assistant.

The Parameters section of our custom intent

But what about our initial numbers? We could use six integers to represent the six initial numbers, but we need to be a bit more restrictive than that as the user should only be able to select the numbers 1-10, 25, 50, 75 or 100. I’m going to opt for an enum so that the user can choose only those valid values. This may be a bit cumbersome but we’ll try it and see how it works.

Creating an enum

Click on the + sign at the bottom left of the pane, and select New Enum. Give it a name of InitialNumber. Next, create all the cases - one per possible value. I may live to regret this, but anyway that’s how I’ve done it, as pictured in the screenshot below.

Creating an enum

For each possible number we have a case .value<x> with an index matching our number. You’ll notice that I’ve also added a pronunciation hint. I’m not sure this is needed as I hope Siri can pronounce numbers!

Let’s move back to our Solve Game intent and add our initial number parameters. We’ll make each initial number parameter user-facing, so that the user can supply the value in Shortcuts.

We’ve updated the Siri Dialog too, ready for when we have our interactive voice interface.

Our parameters fully completed with initial numbers and targets
Our completed parameters

Configuring Shortcuts

The next section determines how our custom intent appears in the Shortcuts app. We’re going to make the intent user-configurable, which means that the user can choose to run the shortcut with some, all or none of our parameters pre-filled in.

For example, a user could create a shortcut to always solve a numbers game with a target of 342. The shortcut would prompt the user for the initial number values before handing control over to NumberRace.

Or the user could populate all the values in the shortcut. In that case, when the shortcut is run, the solver is opened with the same values each time. Not that there’s much point to that, but still - it’s possible.

We’ll add a summary - type in the following:

Solve a numbers game with a target of target using number1, number2, number3, number4, number5 and number6

Ensure that when you type the words in bold that you select the parameter from the box that appears. Bingo - we have an intent that can be used in the Shortcuts app!

The Shortcuts App section of our custom intent
Specifying our shortcut

Incidentally, Apple’s Human Interface Guidelines suggest avoiding punctuation as we have done here. So eventually we may have to come up with another suitably pithy sentence. That’s for another day though.

We should now have enough information to test our intent. Let’s build our project, open Shortcuts and see if it works.

Open the Shortcuts app and click on the Create Shortcut button.

The New Shortcut screen in the Shortcuts app
Creating a shortcut in Shortcuts

Click on Add action and select our app. Success! Our Solve Game intent is listed.

The NumberRace app in the Shortcuts app
Choosing an intent

Select that action and we can configure it how we wish.

The NumberRace solve game intent awaiting some parameters
Configuring our intent

Let’s choose a target number and ask the user every time for the target numbers…

Our configured Solve Game intent in the Shortcuts app
Our completed shortcut. Note the speech bubble next to some of the parameters - Shortcuts will ask for those values each time the shortcut is run

Clicking on the Play button will take us through our shortcut and, sure enough, we get asked for some initial numbers…

The Initial Numbers dialog box in the Shortcuts app
Choosing a number

The NumberRace app opens… and gets stuck on the main menu.

The NumberRace menu screen

Progress! Sort of!

We’ve created a shortcut and it gathers the correct values. But our app doesn’t know what to do next. It’s time to write some code. We’ll do this next, in Part 3.