Voice command element and attribute reference for Windows Phone 8

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

Voice command reference

The following table describes the elements and attributes of the voice command definition file.

Element	Description
VoiceCommands	Required root element of the voice command manifest. The value of its xmlns attribute must be https://schemas.microsoft.com/voicecommands/1.0 (no uppercase characters). Contains one or more CommandSet elements, each of which represents the voice commands for a single language.
CommandSet	Required child element of the VoiceCommands element. A container for all the voice commands that an app will accept in the single language specified by the required xml:lang attribute. The value of the xml:lang attribute must be unique in the VoiceCommand document. The Name attribute is optional and can be any arbitrary string; however, the Name attribute is required in order to reference and update a CommandSet element's PhraseList programmatically. The CommandSet element contains the following child elements: CommandPrefix (0 or 1), Example (1 only), Command (1 to 100), and PhraseList elements (zero or more). These child elements must occur in the order listed.
CommandPrefix	Optional child element of the VoiceCommands element. If present, must be the first child element of the CommandSet element. Specifies a user-friendly name for an app that a user can speak when giving a voice command. This is useful for apps with names that are long or are difficult to pronounce.
Command	Required child element of the CommandSet element. Takes the Name attribute. Defines an app action that users can initiate by speaking and what users can say to initiate the action. Each Command element is associated with a specific page in your app. Contains the following required child elements: Example (1 only), ListenFor (up to 10), Feedback (1 only), and Navigate (1 only). These child elements must occur in the order listed.
Example	Required child element of the Command element, optional child of the CommandSet element. Gives an ideal example of what a user can say for a command. As a child of the CommandSet element, the example text displays in the following screens: Below the app's name on the apps page of the What can I say screen. The page lists all apps that have enhanced voice commands. On the open page of the What can I say screen, there will be two additional examples of app name + example text, linking to the apps page. On some error screens. On Listening screens. On the Did you know? help screen that lists the commands for the app.
ListenFor	Required child element of the Command element. Contains a word or phrase that your app will recognize for this command. This may include or be a reference to a PhraseList element's Label attribute, which appears in the ListenFor element enclosed in curly braces, for example: {myList}. A Command element can contain up to ten ListenFor elements, and the content of any one can be recognized to activate the command. Use brackets around a word or words that are optional. That is, the word or words can be spoken, but are not necessary for a match. You can set up wildcard functionality by including an asterisk character inside a pair of curly braces, such as <ListenFor>Find {*}</ListenFor>. In this example, the voice command will match as long as the user speaks "Find", followed by any other word or phrase. If the voice command for a wildcard-enabled ListenFor element is matched, the reco key will contain the string "…".
Feedback	Required child element of the Command element. Specifies the text that will be displayed and read back to the user when the command is recognized. If the Feedback element includes a reference to a PhraseList element, then every ListenFor element in the containing Command element must also reference the same PhraseList.
Navigate	Required child element of the Command element. You can specify an optional Target attribute that specifies the page that should load when the app launches. If you specify the Target attribute, you can also add your own query parameters. If you do not specify the Target attribute, the app launches into its main page. The following XML code shows an example of how to set the Navigate element with a Target attribute and custom query parameter: <Navigate Target="Page2.xaml?myParam=someValue"/>
PhraseList	Optional child of the CommandSet element. Requires the Label attribute, the value of which is enclosed by curly braces inside ListenFor or Feedback elements, and is used to reference the PhraseList. Optionally specifies the Disambiguate attribute (default true), which controls whether content from this PhraseList element will result in user disambiguation and emit its recognition into the query string parameters for referencing voice commands. Contains up to 2,000 Item elements, each of which specifies a word or phrase that can be recognized to initiate the command that references the PhraseList. The 2,000 Item element limit is a combined total across all PhraseList elements in a CommandSet.
Item	Optional child of the PhraseList element. One of multiple words or phrases that can be recognized to initiate a command. A CommandSet can contain no more than 2,000 Item elements across all of its child PhraseList elements.

You can use the following special characters to define commands.

Important Note:
It’s not possible to nest the special characters listed below. For example, statements like [[start] new game] and [{myPhraseList}] are not possible.

Special character	Description
{}	Contains the value of the Label attribute for the PhraseList to reference, for example {myPhraseList}. Used within a ListenFor or Feedback element. A PhraseList reference in a Feedback element must match a corresponding reference in a ListenFor element in the same command.
[]	Designates that the enclosed word or phrase is optional. The enclosed word or phrase may be spoken but is not required to be recognized to initiate the command. For example, if the contents of a ListenFor element are "[start] [begin] new game", the user can speak "start new game" or "new game" or "begin new game" (or even "start begin new game") to initiate the command. Each bracketed element is independently optional, but they must be spoken in the correct order to be recognized. So, in the “new game” example, “start begin new game” would work, but "begin start new game” would not work because of the order in which they were declared.