-1. Under **Tenant creation**, select **Yes**.

-1. Review your **Tenant Creation** setting. If the settings is set to **No**, then contact your administrator to assign the tenant creator role to you. The setting is greyed out if you're not an administrator in the tenant.

-The custom neural (custom document) model uses deep learning models and base model trained on a large collection of documents. This model is then fine-tuned or adapted to your data when you train the model with a labeled dataset. Custom neural models support structured, semi-structured, and unstructured documents to extract fields. When you're choosing between the two model types, start with a neural model to determine if it meets your functional needs. See [neural models](concept-custom-neural.md) to learn more about custom document models.

-description: Learn about deploying your language projects to multiple regions.

-> * [Custom NER](../../custom-named-entity-recognition/overview.md)

-Custom Language service features enable you to deploy your project to more than one region, making it much easier to access your project globally while managing only one instance of your project in one place.

-Before you deploy a project, you can assign **deployment resources** in other regions. Each deployment resource is a different Language resource from the one you use to author your project. You deploy to those resources and then target your prediction requests to that resource in their respective regions and your queries are served directly from that region.

-When creating a deployment, you can select which of your assigned deployment resources and their corresponding regions you would like to deploy to. The model you deploy is then replicated to each region and accessible with its own endpoint dependent on the deployment resource's custom subdomain.

-Suppose you want to make sure your project, which is used as part of a customer support chatbot, is accessible by customers across the US and India. You would author a project with the name **ContosoSupport** using a _West US 2_ Language resource named **MyWestUS2**. Before deployment, you would assign two deployment resources to your project - **MyEastUS** and **MyCentralIndia** in _East US_ and _Central India_, respectively.

-When deploying your project, You would select all three regions for deployment: the original _West US 2_ region and the assigned ones through _East US_ and _Central India_.

-You would now have three different endpoint URLs to access your project in all three regions:

-* West US 2: `https://mywestus2.cognitiveservices.azure.com/language/:analyze-conversations`

-* East US: `https://myeastus.cognitiveservices.azure.com/language/:analyze-conversations`

-* Central India: `https://mycentralindia.cognitiveservices.azure.com/language/:analyze-conversations`

-The same request body to each of those different URLs serves the exact same response directly from that region.

-Assigning deployment resources requires Microsoft Entra authentication. Microsoft Entra ID is used to confirm you have access to the resources you are interested in assigning to your project for multi-region deployment. In the Language Studio, you can automatically [enable Microsoft Entra authentication](https://aka.ms/rbac-language) by assigning yourself the _Cognitive Services Language Owner_ role to your original resource. To programmatically use Microsoft Entra authentication, learn more from the [Azure AI services documentation](../../../authentication.md?source=docs&tabs=powershell&tryIt=true#authenticate-with-azure-active-directory).

-Your project name and resource are used as its main identifiers. Therefore, a Language resource can only have a specific project name in each resource. Any other projects with the same name will not be deployable to that resource.

-For example, if a project **ContosoSupport** was created by resource **MyWestUS2** in _West US 2_ and deployed to resource **MyEastUS** in _East US_, the resource **MyEastUS** cannot create a different project called **ContosoSupport** and deploy a project to that region. Similarly, your collaborators cannot then create a project **ContosoSupport** with resource **MyCentralIndia** in _Central India_ and deploy it to either **MyWestUS2** or **MyEastUS**.

-You can only swap deployments that are available in the exact same regions, otherwise swapping will fail.

-If you remove an assigned resource from your project, all of the project deployments to that resource will then be deleted.

-> You **cannot** assign deployment resources to orchestration workflow projects with custom question answering or LUIS connections. You subsequently cannot add custom question answering or LUIS connections to projects that have assigned resources.

-> For multi-region deployment to work as expected, the connected CLU projects **must also be deployed** to the same regional resources you've deployed the orchestration workflow project to. Otherwise the orchestration workflow project will attempt to route a request to a deployment in its region that doesn't exist.

-## Next steps

-description: Learn when to choose conversational language understanding or orchestration workflow

-When you create large applications, you should consider whether your use-case would be best served by a single conversational app (flat architecture), or multiple apps that are orchestrated.

-## Orchestration overview

-Orchestration workflow is a feature that allows you to connect different projects from [LUIS](../../../LUIS/what-is-luis.md) [conversational language understanding](../overview.md), and [custom question answering](../../question-answering/overview.md) in one project. You can then use this project for predictions using one endpoint. The orchestration project makes a prediction on which child project should be called, automatically routes the request, and returns with its response.

-The key point is that orchestration involves two steps:

-1. Predicting which child project to call. <!--The model that performs this classification can be trained either with a standard or an advanced recipe. (Please see footnotes on instructions for training with advanced recipe).-->

-2. Routing the utterance to the destination child app, and returning the child app's response.

-### Advantages

- * If your overall schema has a substantial number of domains, the orchestration approach can help decompose your application into several child apps (each serving a specific domain). For example, an automotive conversational app might have a *navigation domain*, a *media domain*, and so on.

- * Developing each domain app in parallel is easier. People and teams with specific domain expertise can work on individual apps collaboratively and in parallel.

- * Since each domain app is smaller, the development cycle becomes faster. Smaller sized domain apps take much less time to train than a single large app.

- * Since there are separate child apps serving each domain, it's easy to set separate thresholds for different child apps.

-* AI quality improvements where appropriate:

- * Some applications require that certain entities are domain restricted. Orchestration makes this easy to achieve. Once the orchestration project has predicted which child app should be called, the other child apps won't be called.

- For example, if your app contains a `Person.Name` prebuilt entity, consider the utterance *"How do I use a jack?"*, in the context of a vehicle question. In this context, *jack* is an automotive tool, and shouldnΓÇÖt be recognized as a person's name. Using orchestration, this utterance can be redirected to a child app created to answer such questions, which doesnΓÇÖt have a `Person.Name` entity.

-### Disadvantages

- * If you need a particular prebuilt entity being returned in all utterances irrespective of the domain, for example `Quantity.Number` or `Geography.Location`, there is no way of adding an entity to the Orchestration app (it is an intent-only model). You would need to add it to all individual child apps.

- * Orchestration apps take two model inferences. One for predicting which child app to call, another for the prediction in the child app. Inference times will typically be slower than single apps with a flat architecture.

- * Training an orchestration app does not allow you to granularly split data between the testing and training sets. For example, you cannot train a 90-10 split for child app A, and then an 80-20 split for child app B. This may be a minor point, but worth keeping in mind.

-Flat architecture is the other method of developing conversational apps. Instead of using an orchestration app to send utterances to one of multiple child apps, you develop a singular (or flat) app to handle utterances.

-### Advantages

- * For small sized apps or domains, the orchestrator approach can be overly complex.

- * Since all intents and entities are at the same app level, it might be easier to make changes to all of them together.

- * If you want certain prebuilt or list entities to be returned for all utterances, you only need to add it alongside other entities in a single app. If you use orchestration, as mentioned above, you would need to add it to every child app.

-### Disadvantages

- * For large apps (say > 50 intents or entities) it can become difficult to keep track of evolving schemas and datasets. This is particularly evident in cases where the app has to serve several domains. For example an automotive conversational app might have a *navigation domain*, a *media domain*, and so on.

- * In a flat architecture, there is no way to restrict entities to be returned only in certain cases. You can accomplish this using orchestration by assigning those specific entities to particular child apps.

-## Next steps

-If you're uploading your data into CLU it has to follow a specific format, use this article to learn more about accepted data formats.

-If you're [importing a project](../how-to/create-project.md#import-project) into CLU the file uploaded has to be in the following format.

-|`{API-VERSION}` | The [version](../../concepts/model-lifecycle.md#api-versions) of the API you are calling. | `2023-04-01` |

-|`confidenceThreshold`|`{CONFIDENCE-THRESHOLD}`|This is the threshold score below which the intent will be predicted as [none intent](none-intent.md). Values are from `0` to `1`|`0.7`|

-| `projectName` | `{PROJECT-NAME}` | The name of your project. This value is case-sensitive. | `EmailApp` |

-| `multilingual` | `true`| A boolean value that enables you to have utterances in multiple languages in your dataset and when your model is deployed you can query the model in any supported language (not necessarily included in your training documents. See [Language support](../language-support.md#multi-lingual-option) for more information about supported language codes. | `true`|

-|`sublists`|`[]`|Array containing sublists. Each sublist is a key and its associated values.|`[]`|

-|`synonyms`|`[]`|Array containing all the synonyms|synonym|

-| `language` | `{LANGUAGE-CODE}` | A string specifying the language code for the utterances, synonyms, and regular expressions used in your project. If your project is a multilingual project, choose the [language code](../language-support.md) of the majority of the utterances. |`en-us`|

-| `intents` | `[]` | Array containing all the intents you have in the project. These are the intents that will be classified from your utterances.| `[]` |

-| `entities` | `[]` | Array containing all the entities in your project. These are the entities that will be extracted from your utterances. Every entity can have additional optional components defined with them: list, prebuilt, or regex. | `[]` |

-| `dataset` | `{DATASET}` | The test set to which this utterance will go to when split before training. Learn more about data splitting [here](../how-to/train-model.md#data-splitting) . Possible values for this field are `Train` and `Test`. |`Train`|

-| `values`| `{VALUES-FOR-LIST}` | A list of comma separated strings that will be matched exactly for extraction and map to the list key. | `"msft", "microsoft", "MS"` |

-| `prebuilts`| `{PREBUILT-COMPONENTS}` | The prebuilt components that can extract common types. You can find the list of prebuilts you can add [here](../prebuilt-component-reference.md). | `Quantity.Number` |

-| `requiredComponents` | `{REQUIRED-COMPONENTS}` | A setting that specifies a requirement that a specific component be present to return the entity. You can learn more [here](./entity-components.md#required-components). The possible values are `learned`, `regex`, `list`, or `prebuilts` |`"learned", "prebuilt"`|

-CLU offers the option to upload your utterance directly to the project rather than typing them in one by one. You can find this option in the [data labeling](../how-to/tag-utterances.md) page for your project.

-|`text`|`{Utterance-Text}`|Your utterance text|Testing|

-| `language` | `{LANGUAGE-CODE}` | A string specifying the language code for the utterances used in your project. If your project is a multilingual project, choose the language code of the majority of the utterances. See [Language support](../language-support.md) for more information about supported language codes. |`en-us`|

-| `dataset` | `{DATASET}` | The test set to which this utterance will go to when split before training. Learn more about data splitting [here](../how-to/train-model.md#data-splitting) . Possible values for this field are `Train` and `Test`. |`Train`|

-|`intent`|`{intent}`|The assigned intent| intent1|

-|`entity`|`{entity}`|Entity to be extracted| entity1|

-## Next steps

-* You can import your labeled data into your project directly. See [import project](../how-to/create-project.md#import-project) for more information.

-* See the [how-to article](../how-to/tag-utterances.md) more information about labeling your data. When you're done labeling your data, you can [train your model](../how-to/train-model.md).

-description: Learn about evaluation metrics in Conversational Language Understanding

-Your [dataset is split](../how-to/train-model.md#data-splitting) into two parts: a set for training, and a set for testing. The training set is used to train the model, while the testing set is used as a test for model after training to calculate the model performance and evaluation. The testing set isn't introduced to the model through the training process, to make sure that the model is tested on new data.

-Model evaluation is triggered automatically after training is completed successfully. The evaluation process starts by using the trained model to predict user defined intents and entities for utterances in the test set, and compares them with the provided tags (which establishes a baseline of truth). The results are returned so you can review the modelΓÇÖs performance. For evaluation, conversational language understanding uses the following metrics:

-* **Precision**: Measures how precise/accurate your model is. It's the ratio between the correctly identified positives (true positives) and all identified positives. The precision metric reveals how many of the predicted classes are correctly labeled.

-* **Recall**: Measures the model's ability to predict actual positive classes. It's the ratio between the predicted true positives and what was actually tagged. The recall metric reveals how many of the predicted classes are correct.

-* **F1 score**: The F1 score is a function of Precision and Recall. It's needed when you seek a balance between Precision and Recall.

-Precision, recall, and F1 score are calculated for:

-* Each entity separately (entity-level evaluation)

-* Each intent separately (intent-level evaluation)

-The definitions of precision, recall, and evaluation are the same for entity-level, intent-level and model-level evaluations. However, the counts for *True Positives*, *False Positives*, and *False Negatives* can differ. For example, consider the following text.

-* Make a response with thank you very much.

-* reply with saying yes.

-* email to cynthia that dinner last week was splendid.

-* send email to mike

-These are the intents used: *Reply*,*sendEmail*,*readEmail*. These are the entities: *contactName*, *message*.

-|Make a response with thank you very much|Reply|Reply|`thank you very much` as `message` |`thank you very much` as `message` |

-|reply with saying yes| sendEmail|Reply|--|`yes` as `message`|

-|email to cynthia that dinner last week was splendid|Reply|sendEmail|`dinner last week was splendid` as `message`| `cynthia` as `contactName`, `dinner last week was splendid` as `message`|

-|send email to mike|sendEmail|sendEmail|`mike` as `message`|`mike` as `contactName`|

-### Intent level evaluation for *Reply* intent

-| True Positive | 1 | Utterance 1 was correctly predicted as *Reply*. |

-| False Positive | 1 |Utterance 4 was mistakenly predicted as *Reply*. |

-| False Negative | 1 | Utterance 2 was mistakenly predicted as *sendEmail*. |

-**F1 Score** = `2 * Precision * Recall / (Precision + Recall) = (2 * 0.5 * 0.5) / (0.5 + 0.5) = 0.5 `

-### Intent level evaluation for *sendEmail* intent

-| True Positive | 1 | Utterance 5 was correctly predicted as *sendEmail* |

-| False Positive | 1 |Utterance 2 was mistakenly predicted as *sendEmail*. |

-| False Negative | 1 | Utterance 4 was mistakenly predicted as *Reply*. |

-**F1 Score** = `2 * Precision * Recall / (Precision + Recall) = (2 * 0.5 * 0.5) / (0.5 + 0.5) = 0.5 `

-### Intent level evaluation for *readEmail* intent

-| True Positive | 1 | Utterance 3 was correctly predicted as *readEmail*. |

-| False Positive | 0 |--|

-| False Negative | 0 |--|

-**F1 Score** = `2 * Precision * Recall / (Precision + Recall) = (2 * 1 * 1) / (1 + 1) = 1`

-### Entity level evaluation for *contactName* entity

-| True Positive | 1 | `cynthia` was correctly predicted as `contactName` in utterance 4|

-| False Positive | 0 |--|

-| False Negative | 1 | `mike` was mistakenly predicted as `message` in utterance 5 |

-**F1 Score** = `2 * Precision * Recall / (Precision + Recall) = (2 * 1 * 0.5) / (1 + 0.5) = 0.67`

-### Entity level evaluation for *message* entity

-| True Positive | 2 |`thank you very much` was correctly predicted as `message` in utterance 1 and `dinner last week was splendid` was correctly predicted as `message` in utterance 4 |

-| False Positive | 1 |`mike` was mistakenly predicted as `message` in utterance 5 |

-| False Negative | 1 | ` yes` was not predicted as `message` in utterance 2 |

-| True Positive | 6 | Sum of TP for all intents and entities |

-| False Positive | 3| Sum of FP for all intents and entities |

-| False Negative | 4 | Sum of FN for all intents and entities |

-**F1 Score** = `2 * Precision * Recall / (Precision + Recall) = (2 * 0.67 * 0.60) / (0.67 + 0.60) = 0.63`

-A Confusion matrix is an N x N matrix used for model performance evaluation, where N is the number of entities or intents.

-The matrix compares the expected labels with the ones predicted by the model.

-This gives a holistic view of how well the model is performing and what kinds of errors it is making.

-You can use the Confusion matrix to identify intents or entities that are too close to each other and often get mistaken (ambiguity). In this case consider merging these intents or entities together. If that isn't possible, consider adding more tagged examples of both intents or entities to help the model differentiate between them.

-The highlighted diagonal in the image below is the correctly predicted entities, where the predicted tag is the same as the actual tag.

-* The values in the diagonal are the *True Positive* values of each intent or entity.

-* The sum of the values in the intent or entities rows (excluding the diagonal) is the *false positive* of the model.

-* The sum of the values in the intent or entities columns (excluding the diagonal) is the *false Negative* of the model.

-Similarly,

-* The *true positive* of the model is the sum of *true Positives* for all intents or entities.

-* The *false positive* of the model is the sum of *false positives* for all intents or entities.

-* The *false Negative* of the model is the sum of *false negatives* for all intents or entities.

-After you trained your model, you will see some guidance and recommendations on how to improve the model. It's recommended to have a model covering every point in the guidance section.

-* Training set has enough data: When an intent or entity has fewer than 15 labeled instances in the training data, it can lead to lower accuracy due to the model not being adequately trained on that intent. In this case, consider adding more labeled data in the training set. You should only consider adding more labeled data to your entity if your entity has a learned component. If your entity is defined only by list, prebuilt, and regex components, then this recommendation is not applicable.

-* All intents or entities are present in test set: When the testing data lacks labeled instances for an intent or entity, the model evaluation is less comprehensive due to untested scenarios. Consider having test data for every intent and entity in your model to ensure everything is being tested.

-* Unclear distinction between intents or entities: When data is similar for different intents or entities, it can lead to lower accuracy because they may be frequently misclassified as each other. Review the following intents and entities and consider merging them if theyΓÇÖre similar. Otherwise, add more examples to better distinguish them from each other. You can check the *confusion matrix* tab for more guidance. If you are seeing two entities constantly being predicted for the same spans because they share the same list, prebuilt, or regex components, then make sure to add a **learned** component for each entity and make it **required**. Learn more about [entity components](./entity-components.md).

-## Next steps

-[Train a model in Language Studio](../how-to/train-model.md)

-description: Learn about the default None intent in conversational language understanding

-Every project in conversational language understanding includes a default **None** intent. The None intent is a required intent and can't be deleted or renamed. The intent is meant to categorize any utterances that do not belong to any of your other custom intents.

-An utterance can be predicted as the None intent if the top scoring intent's score is **lower** than the None score threshold. It can also be predicted if the utterance is similar to examples added to the None intent.

-For any query and utterance, the highest scoring intent ends up **lower** than the threshold score, the top intent will be automatically replaced with the None intent. The scores of all the other intents remain unchanged.

-The score should be set according to your own observations of prediction scores, as they may vary by project. A higher threshold score forces the utterances to be more similar to the examples you have in your training data.

-When you export a project's JSON file, the None score threshold is defined in the _**"settings"**_ parameter of the JSON as the _**"confidenceThreshold"**_, which accepts a decimal value between 0.0 and 1.0.

-> During model evaluation of your test set, the None score threshold is not applied.

-## Adding examples to the None intent

-The None intent is also treated like any other intent in your project. If there are utterances that you want predicted as None, consider adding similar examples to them in your training data. For example, if you would like to categorize utterances that are not important to your project as None, such as greetings, yes and no answers, responses to questions such as providing a number, then add those utterances to your intent.

-You should also consider adding false positive examples to the None intent. For example, in a flight booking project it is likely that the utterance "I want to buy a book" could be confused with a Book Flight intent. Adding "I want to buy a book" or "I love reading books" as None training utterances helps alter the predictions of those types of utterances towards the None intent instead of Book Flight.

-## Next steps

-[Conversational language understanding overview](../overview.md)

-description: Custom Commands encryption of data at rest.

-# Custom Commands encryption of data at rest

-Custom Commands automatically encrypts your data when it's persisted to the cloud. The Custom Commands service encryption protects your data and to help you to meet your organizational security and compliance commitments.

-> [!NOTE]

-> Custom Commands service doesn't automatically enable encryption for the LUIS resources associated with your application. If needed, you must enable encryption for your LUIS resource from [here](../luis/encrypt-data-at-rest.md).

-## About Azure AI services encryption

-Data is encrypted and decrypted using [FIPS 140-2](https://en.wikipedia.org/wiki/FIPS_140-2) compliant [256-bit AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) encryption. Encryption and decryption are transparent, meaning encryption and access are managed for you. Your data is secure by default and you don't need to modify your code or applications to take advantage of encryption.

-## About encryption key management

-When you use Custom Commands, speech service stores following data in the cloud:

-* Configuration JSON behind the Custom Commands application

-* LUIS authoring and prediction key

-By default, your subscription uses Microsoft-managed encryption keys. However, you can also manage your subscription with your own encryption keys. Customer-managed keys (CMK), also known as bring your own key (BYOK), offer greater flexibility to create, rotate, disable, and revoke access controls. You can also audit the encryption keys used to protect your data.

-> [!IMPORTANT]

-> Customer-managed keys are only available resources created after 27 June, 2020. To use CMK with the Speech service, you will need to create a new Speech resource. Once the resource is created, you can use Azure Key Vault to set up your managed identity.

-To request the ability to use customer-managed keys, fill out and submit Customer-Managed Key Request Form. It takes approximately 3-5 business days to hear back on the status of your request. Depending on demand, you might be placed in a queue and approved as space becomes available. Once approved for using CMK with the Speech service, you need to create a new Speech resource from the Azure portal.

- > [!NOTE]

- > **Customer-managed keys (CMK) are supported only for custom commands.**

- >

- > **Custom speech and custom voice still support only Bring Your Own Storage (BYOS).** [Learn more](speech-encryption-of-data-at-rest.md)

- >

- > If you're using the given speech resource for accessing these service, compliance needs must be met by explicitly configuring BYOS.

-## Customer-managed keys with Azure Key Vault

-You must use Azure Key Vault to store customer-managed keys. You can either create your own keys and store them in a key vault, or you can use the Azure Key Vault APIs to generate keys. The Speech resource and the key vault must be in the same region and in the same Microsoft Entra tenant, but they can be in different subscriptions. For more information about Azure Key Vault, see [What is Azure Key Vault?](../../key-vault/general/overview.md).

-When a new Speech resource is created and used to provision Custom Commands applications, data is always encrypted using Microsoft-managed keys. It's not possible to enable customer-managed keys at the time that the resource is created. Customer-managed keys are stored in Azure Key Vault, and the key vault must be provisioned with access policies that grant key permissions to the managed identity that is associated with the Azure AI services resource. The managed identity is available only after the resource is created using the Pricing Tier required for CMK.

-Enabling customer managed keys also enables a system assigned [managed identity](../../active-directory/managed-identities-azure-resources/overview.md), a feature of Microsoft Entra ID. Once the system assigned managed identity is enabled, this resource is registered with Microsoft Entra ID. After being registered, the managed identity is given access to the Key Vault selected during customer managed key setup.

-> [!IMPORTANT]

-> If you disable system assigned managed identities, access to the key vault will be removed and any data encrypted with the customer keys will no longer be accessible. Any features depended on this data will stop working.

-> [!IMPORTANT]

-> Managed identities do not currently support cross-directory scenarios. When you configure customer-managed keys in the Azure portal, a managed identity is automatically assigned under the covers. If you subsequently move the subscription, resource group, or resource from one Microsoft Entra directory to another, the managed identity associated with the resource is not transferred to the new tenant, so customer-managed keys may no longer work. For more information, see **Transferring a subscription between Microsoft Entra directories** in [FAQs and known issues with managed identities for Azure resources](../../active-directory/managed-identities-azure-resources/known-issues.md#transferring-a-subscription-between-azure-ad-directories).

-## Configure Azure Key Vault

-Using customer-managed keys requires that two properties be set in the key vault, **Soft Delete** and **Do Not Purge**. These properties aren't enabled by default, but can be enabled using either PowerShell or Azure CLI on a new or existing key vault.

-> [!IMPORTANT]

-> If you do not have the **Soft Delete** and **Do Not Purge** properties enabled and you delete your key, you won't be able to recover the data in your Azure AI services resource.

-To learn how to enable these properties on an existing key vault, see the sections titled **Enabling soft-delete** and **Enabling Purge Protection** in one of the following articles:

-Only RSA keys of size 2048 are supported with Azure Storage encryption. For more information about keys, see **Key Vault keys** in [About Azure Key Vault keys, secrets and certificates](../../key-vault/general/about-keys-secrets-certificates.md).

-## Enable customer-managed keys for your Speech resource

-To enable customer-managed keys in the Azure portal, follow these steps:

-1. Navigate to your Speech resource.

-1. On the **Settings** page for your Speech resource, select **Encryption**. Select the **Customer Managed Keys** option, as shown in the following figure.

- 

-## Specify a key

-After you enable customer-managed keys, you'll have the opportunity to specify a key to associate with the Azure AI services resource.

-### Specify a key as a URI

-To specify a key as a URI, follow these steps:

-1. To locate the key URI in the Azure portal, navigate to your key vault, and select the **Keys** setting. Select the desired key, then select the key to view its versions. Select a key version to view the settings for that version.

-1. Copy the value of the **Key Identifier** field, which provides the URI.

- 

-1. In the **Encryption** settings for your Speech service, choose the **Enter key URI** option.

-1. Paste the URI that you copied into the **Key URI** field.

-1. Specify the subscription that contains the key vault.

-1. Save your changes.

-### Specify a key from a key vault

-To specify a key from a key vault, first make sure that you have a key vault that contains a key. To specify a key from a key vault, follow these steps:

-1. Choose the **Select from Key Vault** option.

-1. Select the key vault containing the key you want to use.

-1. Select the key from the key vault.

- 

-1. Save your changes.

-## Update the key version

-When you create a new version of a key, update the Speech resource to use the new version. Follow these steps:

-1. Navigate to your Speech resource and display the **Encryption** settings.

-1. Enter the URI for the new key version. Alternately, you can select the key vault and the key again to update the version.

-1. Save your changes.

-## Use a different key

-To change the key used for encryption, follow these steps:

-1. Navigate to your Speech resource and display the **Encryption** settings.

-1. Enter the URI for the new key. Alternately, you can select the key vault and choose a new key.

-1. Save your changes.

-## Rotate customer-managed keys

-You can rotate a customer-managed key in Azure Key Vault according to your compliance policies. When the key is rotated, you must update the Speech resource to use the new key URI. To learn how to update the resource to use a new version of the key in the Azure portal, see [Update the key version](#update-the-key-version).

-Rotating the key doesn't trigger re-encryption of data in the resource. There's no further action required from the user.

-## Revoke access to customer-managed keys

-To revoke access to customer-managed keys, use PowerShell or Azure CLI. For more information, see [Azure Key Vault PowerShell](/powershell/module/az.keyvault//) or [Azure Key Vault CLI](/cli/azure/keyvault). Revoking access effectively blocks access to all data in the Azure AI services resource, as the encryption key is inaccessible by Azure AI services.

-## Disable customer-managed keys

-When you disable customer-managed keys, your Speech resource is then encrypted with Microsoft-managed keys. To disable customer-managed keys, follow these steps:

-1. Navigate to your Speech resource and display the **Encryption** settings.

-1. Deselect the checkbox next to the **Use your own key** setting.

-## Next steps

-* [Speech Customer-Managed Key Request Form](https://aka.ms/cogsvc-cmk)

-* [Learn more about Azure Key Vault](../../key-vault/general/overview.md)

-* [What are managed identities](../../active-directory/managed-identities-azure-resources/overview.md)

-description: In this article, you learn about concepts and definitions for Custom Commands applications.

-# Custom Commands concepts and definitions

-This article serves as a reference for concepts and definitions for Custom Commands applications.

-## Commands configuration

-Commands are the basic building blocks of a Custom Commands application. A command is a set of configurations required to complete a specific task defined by a user.

-### Example sentences

-Example utterances are the set examples the user can say to trigger a particular command. You need to provide only a sample of utterances and not an exhaustive list.

-### Parameters

-Parameters are information required by the commands to complete a task. In complex scenarios, parameters can also be used to define conditions that trigger custom actions.

-### Completion rules

-Completion rules are a series of rules to be executed after the command is ready to be fulfilled, for example, when all the conditions of the rules are satisfied.

-### Interaction rules

-Interaction rules are extra rules to handle more specific or complex situations. You can add more validations or configure advanced features such as confirmations or a one-step correction. You can also build your own custom interaction rules.

-## Parameters configuration

-Parameters are information required by commands to complete a task. In complex scenarios, parameters can also be used to define conditions that trigger custom actions.

-### Name

-A parameter is identified by the name property. You should always give a descriptive name to a parameter. A parameter can be referred across different sections, for example, when you construct conditions, speech responses, or other actions.

-### Required

-This check box indicates whether a value for this parameter is required for command fulfillment or completion. You must configure responses to prompt the user to provide a value if a parameter is marked as required.

-If you configured a **required parameter** to have a **Default value**, the system still prompts for the parameter's value.

-### Type

-Custom Commands supports the following parameter types:

-* Age

-* Currency

-* DateTime

-* Dimension

-* Email

-* Geography

-* Number

-* Ordinal

-* Percentage

-* PersonName

-* PhoneNumber

-* String

-* Temperature

-* Url

-Every locale supports the "String" parameter type, but availability of all other types differs by locale. Custom Commands uses LUIS's prebuilt entity resolution, so the availability of a parameter type in a locale depends on LUIS's prebuilt entity support in that locale. You can find [more details on LUIS's prebuilt entity support per locale](../luis/luis-reference-prebuilt-entities.md). Custom LUIS entities (such as machine learned entities) are currently not supported.

-Some parameter types like Number, String and DateTime support default value configuration, which you can configure from the portal.

-### Configuration

-Configuration is a parameter property defined only for the type String. The following values are supported:

-* **None**.

-* **Accept full input**: When enabled, a parameter accepts any input utterance. This option is useful when the user needs a parameter with the full utterance. An example is postal addresses.

-* **Accept predefined input values from an external catalog**: This value is used to configure a parameter that can assume a wide variety of values. An example is a sales catalog. In this case, the catalog is hosted on an external web endpoint and can be configured independently.

-* **Accept predefined input values from internal catalog**: This value is used to configure a parameter that can assume a few values. In this case, values must be configured in the Speech Studio.

-### Validation

-Validations are constructs applicable to certain parameter types that let you configure constraints on a parameter's value. Currently, Custom Commands supports validations on the following parameter types:

-* DateTime

-* Number

-## Rules configuration

-A rule in Custom Commands is defined by a set of *conditions* that, when met, execute a set of *actions*. Rules also let you configure *post-execution state* and *expectations* for the next turn.

-### Types

-Custom Commands supports the following rule categories:

-* **Completion rules**: These rules must be executed upon command fulfillment. All the rules configured in this section for which the conditions are true will be executed.

-* **Interaction rules**: These rules can be used to configure extra custom validations, confirmations, and a one-step correction, or to accomplish any other custom dialog logic. Interaction rules are evaluated at each turn in the processing and can be used to trigger completion rules.

-The different actions configured as part of a rule are executed in the order in which they appear in the authoring portal.

-### Conditions

-Conditions are the requirements that must be met for a rule to execute. Rules conditions can be of the following types:

-* **Parameter value equals**: The configured parameter's value equals a specific value.

-* **No parameter value**: The configured parameters shouldn't have any value.

-* **Required parameters**: The configured parameter has a value.

-* **All required parameters**: All the parameters that were marked as required have a value.

-* **Updated parameters**: One or more parameter values were updated as a result of processing the current input (utterance or activity).

-* **Confirmation was successful**: The input utterance or activity was a successful confirmation (yes).

-* **Confirmation was denied**: The input utterance or activity wasn't a successful confirmation (no).

-* **Previous command needs to be updated**: This condition is used in instances when you want to catch a negated confirmation along with an update. Behind the scenes, this condition is configured for when the dialog engine detects a negative confirmation where the intent is the same as the previous turn, and the user has responded with an update.

-### Actions

-* **Send speech response**: Send a speech response back to the client.

-* **Update parameter value**: Update the value of a command parameter to a specified value.

-* **Clear parameter value**: Clear the command parameter value.

-* **Call web endpoint**: Make a call to a web endpoint.

-* **Send activity to client**: Send a custom activity to the client.

-### Expectations

-Expectations are used to configure hints for the processing of the next user input. The following types are supported:

-* **Expecting confirmation from user**: This expectation specifies that the application is expecting a confirmation (yes/no) for the next user input.

-* **Expecting parameter(s) input from user**: This expectation specifies one or more command parameters that the application is expecting from the user input.

-### Post-execution state

-The post-execution state is the dialog state after processing the current input (utterance or activity). It's of the following types:

-* **Keep current state**: Keep current state only.

-* **Complete the command**: Complete the command and no more rules of the command are processed.

-* **Execute completion rules**: Execute all the valid completion rules.

-* **Wait for user's input**: Wait for the next user input.

-## Next steps

-> [!div class="nextstepaction"]

-> [See samples on GitHub](https://aka.ms/speech/cc-samples)

-Direct Line Speech offers the highest levels of customization and sophistication for voice assistants. It's designed for conversational scenarios that are open-ended, natural, or hybrids of the two with task completion or command-and-control use. This high degree of flexibility comes with a greater complexity. Consider [Custom Commands](custom-commands.md) for scenarios that are scoped to well-defined tasks using natural language input.

-description: In this article, you learn how to debug errors when authoring Custom Commands application.

-# Debug errors when authoring a Custom Commands application

-This article describes how to debug when you see errors while building Custom Commands application.

-## Errors when creating an application

-Custom Commands also creates an application in [LUIS](https://www.luis.ai/) when creating a Custom Commands application.

-[LUIS limits 500 applications per authoring resource](../luis/luis-limits.md). Creation of LUIS application could fail if you're using an authoring resource that already has 500 applications.

-Make sure the selected LUIS authoring resource has fewer than 500 applications. If not, you can create new LUIS authoring resource, switch to another one, or try to clean up your LUIS applications.

-## Errors when deleting an application

-### Can't delete LUIS application

-When you delete a Custom Commands application, Custom Commands might also try to delete the LUIS application associated with the Custom Commands application.

-If the deletion of LUIS application failed, go to your [LUIS](https://www.luis.ai/) account to delete them manually.

-### TooManyRequests

-When you try to delete large number of applications all at once, it's likely you would see 'TooManyRequests' errors. These errors mean your deletion requests get throttled by Azure.

-Refresh your page and try to delete fewer applications.

-## Errors when modifying an application

-### Can't delete a parameter or a Web Endpoint

-You aren't allowed to delete a parameter when it's being used.

-Remove any reference of the parameter in any speech responses, sample sentences, conditions, actions, and try again.

-### Can't delete a Web Endpoint

-You aren't allowed to delete a Web Endpoint when it's being used.

-Remove any **Call Web Endpoint** action that uses this Web Endpoint before removing a Web Endpoint.

-## Errors when training an application

-### Built-In intents

-LUIS has built-in Yes/No intents. Having sample sentences with only "yes", "no" would fail the training.

-| Keyword | Variations |

-| - | |

-| Yes | Sure, OK |

-| No | Nope, Not |

-### Common sample sentences

-Custom Commands doesn't allow common sample sentences shared among different commands. The training of an application could fail if some sample sentences in one command are already defined in another command.

-Make sure you don't have common sample sentences shared among different commands.

-For best practice of balancing your sample sentences across different commands, refer [LUIS best practice](../luis/faq.md).

-### Empty sample sentences

-You need to have at least one sample sentence for each Command.

-### Undefined parameter in sample sentences

-One or more parameters are used in the sample sentences but not defined.

-### Training takes too long

-LUIS training is meant to learn quickly with fewer examples. Don't add too many example sentences.

-If you have many example sentences that are similar, define a parameter, abstract them into a pattern and add it to Example Sentences.

-For example, you can define a parameter {vehicle} for the example sentences below, and only add "Book a {vehicle}" to Example Sentences.

-| Example sentences | Pattern |

-| - | - |

-| Book a car | Book a {vehicle} |

-| Book a flight | Book a {vehicle} |

-| Book a taxi | Book a {vehicle} |

-For best practice of LUIS training, refer [LUIS best practice](../luis/faq.md).

-## Can't update LUIS key

-### Reassign to E0 authoring resource

-LUIS doesn't support reassigning LUIS application to E0 authoring resource.

-If you need to change your authoring resource from F0 to E0, or change to a different E0 resource, recreate the application.

-For quickly export an existing application and import it into a new application, refer to [Continuous Deployment with Azure DevOps](./how-to-custom-commands-deploy-cicd.md).

-### Save button is disabled

-If you never assign a LUIS prediction resource to your application, the Save button would be disabled when you try to change your authoring resource without adding a prediction resource.

-## Next steps

-> [!div class="nextstepaction"]

-> [See samples on GitHub](https://aka.ms/speech/cc-samples)

-description: In this article, you learn how to debug runtime errors in a Custom Commands application.

-# Troubleshoot a Custom Commands application at runtime

-This article describes how to debug when you see errors while running Custom Commands application.

-## Connection failed

-If your run Custom Commands application from [client application (with Speech SDK)](./how-to-custom-commands-setup-speech-sdk.md) or [Windows Voice Assistant Client](./how-to-custom-commands-developer-flow-test.md), you might experience connection errors as listed below:

-| Error code | Details |

-| - | -- |

-| [401](#error-401) | AuthenticationFailure: WebSocket Upgrade failed with an authentication error |

-| [1002](#error-1002) | The server returned status code '404' when status code '101' was expected. |

-### Error 401

-

- Make sure your speech resource key is correct.

-### Error 1002

-

- Publish your application in the portal.

- Make sure your custom command application ID is correct.

- custom command application outside your speech resource

- Make sure the custom command application is created under your speech resource.

-For more information on troubleshooting the connection issues, reference [Windows Voice Assistant Client Troubleshooting](https://github.com/Azure-Samples/Cognitive-Services-Voice-Assistant/tree/master/clients/csharp-wpf#troubleshooting)

-## Dialog is canceled

-When your Custom Commands application is running, the dialog would be canceled when some errors occur.

-The CancelledDialog event consists of cancellation code and description, as listed below:

-| Cancellation Code | Cancellation Description |

-| - | | -- |

-| [MaxTurnThresholdReached](#no-progress-was-made-after-the-max-number-of-turns-allowed) | No progress was made after the max number of turns allowed |

-| [RecognizerQuotaExceeded](#recognizer-usage-quota-exceeded) | Recognizer usage quota exceeded |

-| [RecognizerConnectionFailed](#connection-to-the-recognizer-failed) | Connection to the recognizer failed |

-| [RecognizerUnauthorized](#this-application-cant-be-accessed-with-the-current-subscription) | This application can't be accessed with the current subscription |

-| [RecognizerInputExceededAllowedLength](#input-exceeds-the-maximum-supported-length) | Input exceeds the maximum supported length for the recognizer |

-| [RecognizerNotFound](#recognizer-not-found) | Recognizer not found |

-| [RecognizerInvalidQuery](#invalid-query-for-the-recognizer) | Invalid query for the recognizer |

-| [RecognizerError](#recognizer-return-an-error) | Recognizer returns an error |

-### No progress was made after the max number of turns allowed

-The dialog is canceled when a required slot isn't successfully updated after certain number of turns. The build-in max number is 3.

-### Recognizer usage quota exceeded

-Language Understanding (LUIS) has limits on resource usage. Usually "Recognizer usage quota exceeded error" is caused by:

- Add a prediction resource to your Custom Commands application:

- 1. go to **Settings**, LUIS resource

- 1. Choose a prediction resource from **Prediction resource**, or select **Create new resource**

- If you are on a F0 prediction resource, it has limit of 10 thousand/month, 5 queries/second.

-For more details on LUIS resource limits, refer [Language Understanding resource usage and limit](../luis/luis-limits.md#resource-usage-and-limits)

-### Connection to the recognizer failed

-Usually it means transient connection failure to Language Understanding (LUIS) recognizer. Try it again and the issue should be resolved.

-### This application can't be accessed with the current subscription

-Your subscription isn't authorized to access the LUIS application.

-### Input exceeds the maximum supported length

-Your input exceeded 500 characters. We only allow at most 500 characters for input utterance.

-### Invalid query for the recognizer

-Your input exceeded 500 characters. We only allow at most 500 characters for input utterance.

-### Recognizer return an error

-The LUIS recognizer returned an error when trying to recognize your input.

-### Recognizer not found

-Can't find the recognizer type specified in your custom commands dialog model. Currently, we only support [Language Understanding (LUIS) Recognizer](https://www.luis.ai/).

-## Other common errors

-### Unexpected response

-Unexpected responses result from many different reasons.

-A few checks to start with:

- As we currently don't support Yes/No Intents except when using with confirmation feature. All the Yes/No Intents defined in example sentences wouldn't be detected.

- The LUIS recognition accuracy might get affected when two commands share similar intents and examples sentences. You can try to make commands functionality and example sentences as distinct as possible.

- For best practice of improving recognition accuracy, refer [LUIS best practice](../luis/faq.md).

-

- Check the reasons of cancellation in the section above.

-### Error while rendering the template

-An undefined parameter is used in the speech response.

-### Object reference not set to an instance of an object

-You have an empty parameter in the JSON payload defined in **Send Activity to Client** action.

-## Next steps

-> [!div class="nextstepaction"]

-> [See samples on GitHub](https://aka.ms/speech/cc-samples)

-description: In this article, you learn how to set up continuous deployment for your Custom Commands applications. You create the scripts to support the continuous deployment workflows.

-# Continuous Deployment with Azure DevOps

-In this article, you learn how to set up continuous deployment for your Custom Commands applications. The scripts to support the CI/CD workflow are provided to you.

-## Prerequisite

-> [!div class = "checklist"]

-> * A Custom Commands application for development (DEV)

-> * A Custom Commands application for production (PROD)

-> * Sign up for [Azure Pipelines](/azure/devops/pipelines/get-started/pipelines-sign-up)

-## Export/Import/Publish

-The scripts are hosted at [Voice Assistant - Custom Commands](https://github.com/Azure-Samples/Cognitive-Services-Voice-Assistant/tree/master/custom-commands). Clone the scripts in the bash directory to your repository. Make sure you maintain the same path.

-### Set up a pipeline

-1. Go to **Azure DevOps - Pipelines** and select "New Pipeline"

-1. In **Connect** section, select the location of your repository where these scripts are located

-1. In **Select** section, select your repository

-1. In **Configure** section, select "Starter pipeline"

-1. Next you get an editor with a YAML file, replace the "steps" section with this script.

- ```yaml

- steps:

- - task: Bash@3

- displayName: 'Export source app'

- inputs:

- targetType: filePath

- filePath: ./bash/export.sh

- arguments: '-r westus2 -s $(SubscriptionKey) -c $(Culture) -a $(SourceAppId) -f ExportedDialogModel.json'

- workingDirectory: bash

- failOnStderr: true

-

- - task: Bash@3

- displayName: 'Import to target app'

- inputs:

- targetType: filePath

- filePath: ./bash/import.sh

- arguments: '-r westus2 -s $(SubscriptionKey) -c $(Culture) -a $(TargetAppId) -f ExportedDialogModel.json'

- workingDirectory: bash

- failOnStderr: true

-

- - task: Bash@3

- displayName: 'Train and Publish target app'

- inputs:

- targetType: filePath

- filePath: './bash/train-and-publish.sh'

- arguments: '-r westus2 -s $(SubscriptionKey) -c $(Culture) -a $(TargetAppId)'

- workingDirectory: bash

- failOnStderr: true

- ```

-

-1. These scripts assume that you're using the region `westus2`, if that's not the case update the arguments of the tasks accordingly

- > [!div class="mx-imgBorder"]

- > 

-1. In the "Save and run" button, open the dropdown and select "Save"

-### Hook up the pipeline with your application

-1. Navigate to the main page of the pipeline.

-1. In the top-right corner dropdown, select **Edit pipeline**. It gets you to a YAML editor.

-1. In the top-right corner next to "Run" button, select **Variables**. Select **New variable**.

-1. Add these variables:

-

- | Variable | Description |

- | - | | -- |

- | SourceAppId | ID of the DEV application |

- | TargetAppId | ID of the PROD application |

- | SubscriptionKey | The key used for both applications |

- | Culture | Culture of the applications (en-us) |

- > [!div class="mx-imgBorder"]

- > 

-1. Select "Run" and then select the "Job" running.

- You should see a list of tasks running that contains: "Export source app", "Import to target app" & "Train and Publish target app"

-## Deploy from source code

-In case you want to keep the definition of your application in a repository, we provide the scripts for deployments from source code. Since the scripts are in bash, If you're using Windows you need to install the [Linux subsystem](/windows/wsl/install-win10).

-The scripts are hosted at [Voice Assistant - Custom Commands](https://github.com/Azure-Samples/Cognitive-Services-Voice-Assistant/tree/master/custom-commands). Clone the scripts in the bash directory to your repository. Make sure you maintain the same path.

-### Prepare your repository

-1. Create a directory for your application, in our example create one called "apps".

-1. Update the arguments of the bash script below, and run. It imports the dialog model of your application to the file myapp.json

- ```BASH

- bash/export.sh -r <region> -s <subscriptionkey> -c en-us -a <appid> -f apps/myapp.json

- ```

- | Arguments | Description |

- | - | | -- |

- | region | Your Speech resource region. For example: `westus2` |

- | subscriptionkey | Your Speech resource key. |

- | appid | the Custom Commands' application ID you want to export. |

-1. Push these changes to your repository.

-### Set up a pipeline

-1. Go to **Azure DevOps - Pipelines** and select "New Pipeline"

-1. In **Connect** section, select the location of your repository where these scripts are located

-1. In **Select** section, select your repository

-1. In **Configure** section, select "Starter pipeline"

-1. Next you get an editor with a YAML file, replace the "steps" section with this script.

- ```yaml

- steps:

- - task: Bash@3

- displayName: 'Import app'

- inputs:

- targetType: filePath

- filePath: ./bash/import.sh

- arguments: '-r westus2 -s $(SubscriptionKey) -c $(Culture) -a $(TargetAppId) -f ../apps/myapp.json'

- workingDirectory: bash

- failOnStderr: true

-

- - task: Bash@3

- displayName: 'Train and Publish app'

- inputs:

- targetType: filePath

- filePath: './bash/train-and-publish.sh'

- arguments: '-r westus2 -s $(SubscriptionKey) -c $(Culture) -a $(TargetAppId)'

- workingDirectory: bash

- failOnStderr: true

- ```

- > [!NOTE]

- > these scripts assume that you are using the region westus2, if that's not the case update the arguments of the tasks accordingly

-1. In the "Save and run" button, open the dropdown and select "Save"

-### Hook up the pipeline with your target applications

-1. Navigate to the main page of the pipeline.

-1. In the top-right corner dropdown, select **Edit pipeline**. It gets you to a YAML editor.

-1. In the top-right corner next to "Run" button, select **Variables**. Select **New variable**.

-1. Add these variables:

- | Variable | Description |

- | - | | -- |

- | TargetAppId | ID of the PROD application |

- | SubscriptionKey | The key used for both applications |

- | Culture | Culture of the applications (en-us) |

-1. Select "Run" and then select the "Job" running.

- You should see a list of tasks running that contains: "Import app" & "Train and Publish app"

-## Next steps

-> [!div class="nextstepaction"]

-> [See samples on GitHub](https://aka.ms/speech/cc-samples)

-description: In this article, you learn different approaches to testing a custom commands application.

-# Test your Custom Commands Application

-In this article, you learn different approaches to testing a custom commands application.

-## Test in the portal

-Test in the portal is the simplest and quickest way to check if your custom command application work as expected. After the app is successfully trained, select `Test` button to start testing.

-> [!div class="mx-imgBorder"]

-> 

-## Test with Windows Voice Assistant Client

-The Windows Voice Assistant Client is a Windows Presentation Foundation (WPF) application in C# that makes it easy to test interactions with your bot before creating a custom client application.

-The tool can accept a custom command application ID. It allows you to test your task completion or command-and-control scenario hosted on the Custom Commands service.

-To set up the client, checkout [Windows Voice Assistant Client](https://github.com/Azure-Samples/Cognitive-Services-Voice-Assistant/tree/master/clients/csharp-wpf).

-> [!div class="mx-imgBorder"]

-> 

-## Test programatically with the Voice Assistant Test Tool

-The Voice Assistant Test Tool is a configurable .NET Core C# console application for end-to-end functional regression tests for your Microsoft Voice Assistant.

-The tool can run manually as a console command or automated as part of an Azure DevOps CI/CD pipeline to prevent regressions in your bot.

-To learn how to set up the tool, see [Voice Assistant Test Tool](https://github.com/Azure-Samples/Cognitive-Services-Voice-Assistant/tree/main/clients/csharp-dotnet-core/voice-assistant-test).

-## Test with Speech SDK-enabled client applications

-The Speech software development kit (SDK) exposes many of the Speech service capabilities, which allows you to develop speech-enabled applications. It's available in many programming languages on most platforms.

-To set up a Universal Windows Platform (UWP) client application with Speech SDK, and integrate it with your custom command application:

-For other programming languages and platforms:

-## Next steps

-> [!div class="nextstepaction"]

-> [See samples on GitHub](https://aka.ms/speech/cc-samples)

-description: In this article, you learn how to send activity from a Custom Commands application to a client application running the Speech SDK.

-# Send Custom Commands activity to client application

-In this article, you learn how to send activity from a Custom Commands application to a client application running the Speech SDK.

-You complete the following tasks:

-## Prerequisites

-> [!div class = "checklist"]

-> * [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) or higher. This guide uses Visual Studio 2019

-> * An Azure AI Speech resource key and region: Create a Speech resource on the [Azure portal](https://portal.azure.com). For more information, see [Create a multi-service resource](../multi-service-resource.md?pivots=azportal).

-> * A previously [created Custom Commands app](quickstart-custom-commands-application.md)

-> * A Speech SDK enabled client app:

-[How-to: Integrate with a client application using Speech SDK](./how-to-custom-commands-setup-speech-sdk.md)

-## Setup Send activity to client

-1. Open the Custom Commands application you previously created

-1. Select **TurnOnOff** command, select **ConfirmationResponse** under completion rule, then select **Add an action**

-1. Under **New Action-Type**, select **Send activity to client**

-1. Copy the JSON below to **Activity content**

- ```json

- {

- "type": "event",

- "name": "UpdateDeviceState",

- "value": {

- "state": "{OnOff}",

- "device": "{SubjectDevice}"

- }

- }

- ```

-1. Select **Save** to create a new rule with a Send Activity action, **Train** and **Publish** the change

- > [!div class="mx-imgBorder"]

- > 

-## Integrate with client application

-In [How-to: Setup client application with Speech SDK (Preview)](./how-to-custom-commands-setup-speech-sdk.md), you created a UWP client application with Speech SDK that handled commands such as `turn on the tv`, `turn off the fan`. With some visuals added, you can see the result of those commands.

-To Add labeled boxes with text indicating **on** or **off**, add the following XML block of StackPanel to `MainPage.xaml`.

-```xml

-<StackPanel Orientation="Vertical" H......>

-......

-</StackPanel>

-<StackPanel Orientation="Horizontal" HorizontalAlignment="Center" Margin="20">

- <Grid x:Name="Grid_TV" Margin="50, 0" Width="100" Height="100" Background="LightBlue">

- <StackPanel>

- <TextBlock Text="TV" Margin="0, 10" TextAlignment="Center"/>

- <TextBlock x:Name="State_TV" Text="off" TextAlignment="Center"/>

- </StackPanel>

- </Grid>

- <Grid x:Name="Grid_Fan" Margin="50, 0" Width="100" Height="100" Background="LightBlue">

- <StackPanel>

- <TextBlock Text="Fan" Margin="0, 10" TextAlignment="Center"/>

- <TextBlock x:Name="State_Fan" Text="off" TextAlignment="Center"/>

- </StackPanel>

- </Grid>

-</StackPanel>

-<MediaElement ....../>

-```

-### Add reference libraries

-Since you've created a JSON payload, you need to add a reference to the [JSON.NET](https://www.newtonsoft.com/json) library to handle deserialization.

-1. Right-client your solution.

-1. Choose **Manage NuGet Packages for Solution**, Select **Browse**

-1. If you already installed **Newtonsoft.json**, make sure its version is at least 12.0.3. If not, go to **Manage NuGet Packages for Solution - Updates**, search for **Newtonsoft.json** to update it. This guide is using version 12.0.3.

- > [!div class="mx-imgBorder"]

- > 

-1. Also, make sure NuGet package **Microsoft.NETCore.UniversalWindowsPlatform** is at least 6.2.10. This guide is using version 6.2.10.

-In `MainPage.xaml.cs', add

-```C#

-using Newtonsoft.Json;

-using Windows.ApplicationModel.Core;

-using Windows.UI.Core;

-```

-### Handle the received payload

-In `InitializeDialogServiceConnector`, replace the `ActivityReceived` event handler with following code. The modified `ActivityReceived` event handler extracts the payload from the activity and change the visual state of the tv or fan respectively.

-```C#

-connector.ActivityReceived += async (sender, activityReceivedEventArgs) =>

-{

- NotifyUser($"Activity received, hasAudio={activityReceivedEventArgs.HasAudio} activity={activityReceivedEventArgs.Activity}");

- dynamic activity = JsonConvert.DeserializeObject(activityReceivedEventArgs.Activity);

- var name = activity?.name != null ? activity.name.ToString() : string.Empty;

- if (name.Equals("UpdateDeviceState"))

- {

- Debug.WriteLine("Here");

- var state = activity?.value?.state != null ? activity.value.state.ToString() : string.Empty;

- var device = activity?.value?.device != null ? activity.value.device.ToString() : string.Empty;

- if (state.Equals("on") || state.Equals("off"))

- {

- switch (device)

- {

- case "tv":

- await CoreApplication.MainView.CoreWindow.Dispatcher.RunAsync(

- CoreDispatcherPriority.Normal, () => { State_TV.Text = state; });

- break;

- case "fan":

- await CoreApplication.MainView.CoreWindow.Dispatcher.RunAsync(

- CoreDispatcherPriority.Normal, () => { State_Fan.Text = state; });

- break;

- default:

- NotifyUser($"Received request to set unsupported device {device} to {state}");

- break;

- }

- }

- else {

- NotifyUser($"Received request to set unsupported state {state}");

- }

- }

- if (activityReceivedEventArgs.HasAudio)

- {

- SynchronouslyPlayActivityAudio(activityReceivedEventArgs.Audio);

- }

-};

-```

-## Try it out

-1. Start the application

-1. Select Enable microphone

-1. Select the Talk button

-1. Say `turn on the tv`

-1. The visual state of the tv should change to "on"

- > [!div class="mx-imgBorder"]

- > 

-## Next steps

-> [!div class="nextstepaction"]

-> [How to: set up web endpoints](./how-to-custom-commands-setup-web-endpoints.md)

-description: how to make requests to a published Custom Commands application from the Speech SDK running in a UWP application.

-# Integrate with a client application using Speech SDK

-In this article, you learn how to make requests to a published Custom Commands application from the Speech SDK running in an UWP application. In order to establish a connection to the Custom Commands application, you need:

-## Prerequisites

-A Custom Commands application is required to complete this article. Try a quickstart to create a custom commands application:

-> [!div class = "checklist"]

-> * [Create a Custom Commands application](quickstart-custom-commands-application.md)

-You also need:

-> [!div class = "checklist"]

-> * [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) or higher. This guide is based on Visual Studio 2019.

-> * An Azure AI Speech resource key and region: Create a Speech resource on the [Azure portal](https://portal.azure.com). For more information, see [Create a multi-service resource](../multi-service-resource.md?pivots=azportal).

-> * [Enable your device for development](/windows/uwp/get-started/enable-your-device-for-development)

-## Step 1: Publish Custom Commands application

-1. Open your previously created Custom Commands application.

-1. Go to **Settings**, select **LUIS resource**.

-1. If **Prediction resource** isn't assigned, select a query prediction key or create a new one.

- Query prediction key is always required before publishing an application. For more information about LUIS resources, reference [Create LUIS Resource](../luis/luis-how-to-azure-subscription.md)

-1. Go back to editing Commands, Select **Publish**.

- > [!div class="mx-imgBorder"]

- > 

-1. Copy the App ID from the "publish" notification for later use.

-1. Copy the Speech Resource Key for later use.

-## Step 2: Create a Visual Studio project

-Create a Visual Studio project for UWP development and [install the Speech SDK](./quickstarts/setup-platform.md?pivots=programming-language-csharp&tabs=uwp).

-## Step 3: Add sample code

-In this step, we add the XAML code that defines the user interface of the application, and add the C# code-behind implementation.

-### XAML code

-Create the application's user interface by adding the XAML code.

-1. In **Solution Explorer**, open `MainPage.xaml`

-1. In the designer's XAML view, replace the entire contents with the following code snippet:

- ```xml

- <Page

- x:Class="helloworld.MainPage"

- xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

- xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

- xmlns:local="using:helloworld"

- xmlns:d="http://schemas.microsoft.com/expression/blend/2008"

- xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"

- mc:Ignorable="d"

- Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">

- <Grid>

- <StackPanel Orientation="Vertical" HorizontalAlignment="Center"

- Margin="20,50,0,0" VerticalAlignment="Center" Width="800">

- <Button x:Name="EnableMicrophoneButton" Content="Enable Microphone"

- Margin="0,10,10,0" Click="EnableMicrophone_ButtonClicked"

- Height="35"/>

- <Button x:Name="ListenButton" Content="Talk"

- Margin="0,10,10,0" Click="ListenButton_ButtonClicked"

- Height="35"/>

- <StackPanel x:Name="StatusPanel" Orientation="Vertical"

- RelativePanel.AlignBottomWithPanel="True"

- RelativePanel.AlignRightWithPanel="True"

- RelativePanel.AlignLeftWithPanel="True">

- <TextBlock x:Name="StatusLabel" Margin="0,10,10,0"

- TextWrapping="Wrap" Text="Status:" FontSize="20"/>

- <Border x:Name="StatusBorder" Margin="0,0,0,0">

- <ScrollViewer VerticalScrollMode="Auto"

- VerticalScrollBarVisibility="Auto" MaxHeight="200">

- <!-- Use LiveSetting to enable screen readers to announce

- the status update. -->

- <TextBlock

- x:Name="StatusBlock" FontWeight="Bold"

- AutomationProperties.LiveSetting="Assertive"

- MaxWidth="{Binding ElementName=Splitter, Path=ActualWidth}"

- Margin="10,10,10,20" TextWrapping="Wrap" />

- </ScrollViewer>

- </Border>

- </StackPanel>

- </StackPanel>

- <MediaElement x:Name="mediaElement"/>

- </Grid>

- </Page>

- ```

-The Design view is updated to show the application's user interface.

-### C# code-behind source

-Add the code-behind source so that the application works as expected. The code-behind source includes:

-Add the code-behind source as follows:

-1. In **Solution Explorer**, open the code-behind source file `MainPage.xaml.cs` (grouped under `MainPage.xaml`)

-1. Replace the file's contents with the following code:

- ```csharp

- using Microsoft.CognitiveServices.Speech;

- using Microsoft.CognitiveServices.Speech.Audio;

- using Microsoft.CognitiveServices.Speech.Dialog;

- using System;

- using System.IO;

- using System.Text;

- using Windows.UI.Xaml;

- using Windows.UI.Xaml.Controls;

- using Windows.UI.Xaml.Media;

- namespace helloworld

- {

- public sealed partial class MainPage : Page

- {

- private DialogServiceConnector connector;

- private enum NotifyType

- {

- StatusMessage,

- ErrorMessage

- };

- public MainPage()

- {

- this.InitializeComponent();

- }

- private async void EnableMicrophone_ButtonClicked(

- object sender, RoutedEventArgs e)

- {

- bool isMicAvailable = true;

- try

- {

- var mediaCapture = new Windows.Media.Capture.MediaCapture();

- var settings =

- new Windows.Media.Capture.MediaCaptureInitializationSettings();

- settings.StreamingCaptureMode =

- Windows.Media.Capture.StreamingCaptureMode.Audio;

- await mediaCapture.InitializeAsync(settings);

- }

- catch (Exception)

- {

- isMicAvailable = false;

- }

- if (!isMicAvailable)

- {

- await Windows.System.Launcher.LaunchUriAsync(

- new Uri("ms-settings:privacy-microphone"));

- }

- else

- {

- NotifyUser("Microphone was enabled", NotifyType.StatusMessage);

- }

- }

- private void NotifyUser(

- string strMessage, NotifyType type = NotifyType.StatusMessage)

- {

- // If called from the UI thread, then update immediately.

- // Otherwise, schedule a task on the UI thread to perform the update.

- if (Dispatcher.HasThreadAccess)

- {

- UpdateStatus(strMessage, type);

- }

- else

- {

- var task = Dispatcher.RunAsync(

- Windows.UI.Core.CoreDispatcherPriority.Normal,

- () => UpdateStatus(strMessage, type));

- }

- }

- private void UpdateStatus(string strMessage, NotifyType type)

- {

- switch (type)

- {

- case NotifyType.StatusMessage:

- StatusBorder.Background = new SolidColorBrush(

- Windows.UI.Colors.Green);

- break;

- case NotifyType.ErrorMessage:

- StatusBorder.Background = new SolidColorBrush(

- Windows.UI.Colors.Red);

- break;

- }

- StatusBlock.Text += string.IsNullOrEmpty(StatusBlock.Text)

- ? strMessage : "\n" + strMessage;

- if (!string.IsNullOrEmpty(StatusBlock.Text))

- {

- StatusBorder.Visibility = Visibility.Visible;

- StatusPanel.Visibility = Visibility.Visible;

- }

- else

- {

- StatusBorder.Visibility = Visibility.Collapsed;

- StatusPanel.Visibility = Visibility.Collapsed;

- }

- // Raise an event if necessary to enable a screen reader

- // to announce the status update.

- var peer = Windows.UI.Xaml.Automation.Peers.FrameworkElementAutomationPeer.FromElement(StatusBlock);

- if (peer != null)

- {

- peer.RaiseAutomationEvent(

- Windows.UI.Xaml.Automation.Peers.AutomationEvents.LiveRegionChanged);

- }

- }

- // Waits for and accumulates all audio associated with a given

- // PullAudioOutputStream and then plays it to the MediaElement. Long spoken

- // audio will create extra latency and a streaming playback solution

- // (that plays audio while it continues to be received) should be used --

- // see the samples for examples of this.

- private void SynchronouslyPlayActivityAudio(

- PullAudioOutputStream activityAudio)

- {

- var playbackStreamWithHeader = new MemoryStream();

- playbackStreamWithHeader.Write(Encoding.ASCII.GetBytes("RIFF"), 0, 4); // ChunkID

- playbackStreamWithHeader.Write(BitConverter.GetBytes(UInt32.MaxValue), 0, 4); // ChunkSize: max

- playbackStreamWithHeader.Write(Encoding.ASCII.GetBytes("WAVE"), 0, 4); // Format

- playbackStreamWithHeader.Write(Encoding.ASCII.GetBytes("fmt "), 0, 4); // Subchunk1ID

- playbackStreamWithHeader.Write(BitConverter.GetBytes(16), 0, 4); // Subchunk1Size: PCM

- playbackStreamWithHeader.Write(BitConverter.GetBytes(1), 0, 2); // AudioFormat: PCM

- playbackStreamWithHeader.Write(BitConverter.GetBytes(1), 0, 2); // NumChannels: mono

- playbackStreamWithHeader.Write(BitConverter.GetBytes(16000), 0, 4); // SampleRate: 16kHz

- playbackStreamWithHeader.Write(BitConverter.GetBytes(32000), 0, 4); // ByteRate

- playbackStreamWithHeader.Write(BitConverter.GetBytes(2), 0, 2); // BlockAlign

- playbackStreamWithHeader.Write(BitConverter.GetBytes(16), 0, 2); // BitsPerSample: 16-bit

- playbackStreamWithHeader.Write(Encoding.ASCII.GetBytes("data"), 0, 4); // Subchunk2ID

- playbackStreamWithHeader.Write(BitConverter.GetBytes(UInt32.MaxValue), 0, 4); // Subchunk2Size

- byte[] pullBuffer = new byte[2056];

- uint lastRead = 0;

- do

- {

- lastRead = activityAudio.Read(pullBuffer);

- playbackStreamWithHeader.Write(pullBuffer, 0, (int)lastRead);

- }

- while (lastRead == pullBuffer.Length);

- var task = Dispatcher.RunAsync(

- Windows.UI.Core.CoreDispatcherPriority.Normal, () =>

- {

- mediaElement.SetSource(

- playbackStreamWithHeader.AsRandomAccessStream(), "audio/wav");

- mediaElement.Play();

- });

- }

- private void InitializeDialogServiceConnector()

- {

- // New code will go here

- }

- private async void ListenButton_ButtonClicked(

- object sender, RoutedEventArgs e)

- {

- // New code will go here

- }

- }

- }

- ```

- > [!NOTE]

- > If you see error: "The type 'Object' is defined in an assembly that is not referenced"

- > 1. Right-client your solution.

- > 1. Choose **Manage NuGet Packages for Solution**, Select **Updates**

- > 1. If you see **Microsoft.NETCore.UniversalWindowsPlatform** in the update list, Update **Microsoft.NETCore.UniversalWindowsPlatform** to newest version

-1. Add the following code to the method body of `InitializeDialogServiceConnector`

- ```csharp

- // This code creates the `DialogServiceConnector` with your resource information.

- // create a DialogServiceConfig by providing a Custom Commands application id and Speech resource key

- // The RecoLanguage property is optional (default en-US); note that only en-US is supported in Preview

- const string speechCommandsApplicationId = "YourApplicationId"; // Your application id

- const string speechSubscriptionKey = "YourSpeechSubscriptionKey"; // Your Speech resource key

- const string region = "YourServiceRegion"; // The Speech resource region.

- var speechCommandsConfig = CustomCommandsConfig.FromSubscription(speechCommandsApplicationId, speechSubscriptionKey, region);

- speechCommandsConfig.SetProperty(PropertyId.SpeechServiceConnection_RecoLanguage, "en-us");

- connector = new DialogServiceConnector(speechCommandsConfig);

- ```

-1. Replace the strings `YourApplicationId`, `YourSpeechSubscriptionKey`, and `YourServiceRegion` with your own values for your app, speech key, and [region](regions.md)

-1. Append the following code snippet to the end of the method body of `InitializeDialogServiceConnector`

- ```csharp

- //

- // This code sets up handlers for events relied on by `DialogServiceConnector` to communicate its activities,

- // speech recognition results, and other information.

- //

- // ActivityReceived is the main way your client will receive messages, audio, and events

- connector.ActivityReceived += (sender, activityReceivedEventArgs) =>

- {

- NotifyUser(

- $"Activity received, hasAudio={activityReceivedEventArgs.HasAudio} activity={activityReceivedEventArgs.Activity}");

- if (activityReceivedEventArgs.HasAudio)

- {

- SynchronouslyPlayActivityAudio(activityReceivedEventArgs.Audio);

- }

- };

- // Canceled will be signaled when a turn is aborted or experiences an error condition

- connector.Canceled += (sender, canceledEventArgs) =>

- {

- NotifyUser($"Canceled, reason={canceledEventArgs.Reason}");

- if (canceledEventArgs.Reason == CancellationReason.Error)

- {

- NotifyUser(

- $"Error: code={canceledEventArgs.ErrorCode}, details={canceledEventArgs.ErrorDetails}");

- }

- };

- // Recognizing (not 'Recognized') will provide the intermediate recognized text

- // while an audio stream is being processed

- connector.Recognizing += (sender, recognitionEventArgs) =>

- {

- NotifyUser($"Recognizing! in-progress text={recognitionEventArgs.Result.Text}");

- };

- // Recognized (not 'Recognizing') will provide the final recognized text

- // once audio capture is completed

- connector.Recognized += (sender, recognitionEventArgs) =>

- {

- NotifyUser($"Final speech to text result: '{recognitionEventArgs.Result.Text}'");

- };

- // SessionStarted will notify when audio begins flowing to the service for a turn

- connector.SessionStarted += (sender, sessionEventArgs) =>

- {

- NotifyUser($"Now Listening! Session started, id={sessionEventArgs.SessionId}");

- };

- // SessionStopped will notify when a turn is complete and

- // it's safe to begin listening again

- connector.SessionStopped += (sender, sessionEventArgs) =>

- {

- NotifyUser($"Listening complete. Session ended, id={sessionEventArgs.SessionId}");

- };

- ```

-1. Add the following code snippet to the body of the `ListenButton_ButtonClicked` method in the `MainPage` class

- ```csharp

- // This code sets up `DialogServiceConnector` to listen, since you already established the configuration and

- // registered the event handlers.

- if (connector == null)

- {

- InitializeDialogServiceConnector();

- // Optional step to speed up first interaction: if not called,

- // connection happens automatically on first use

- var connectTask = connector.ConnectAsync();

- }

- try

- {

- // Start sending audio

- await connector.ListenOnceAsync();

- }

- catch (Exception ex)

- {

- NotifyUser($"Exception: {ex.ToString()}", NotifyType.ErrorMessage);

- }

- ```

-1. From the menu bar, choose **File** > **Save All** to save your changes

-## Try it out

-1. From the menu bar, choose **Build** > **Build Solution** to build the application. The code should compile without errors.

-1. Choose **Debug** > **Start Debugging** (or press **F5**) to start the application. The **helloworld** window appears.

- 

-1. Select **Enable Microphone**. If the access permission request pops up, select **Yes**.

- 

-1. Select **Talk**, and speak an English phrase or sentence into your device's microphone. Your speech is transmitted to the Direct Line Speech channel and transcribed to text, which appears in the window.

-## Next steps

-> [!div class="nextstepaction"]

-> [How-to: send activity to client application (Preview)](./how-to-custom-commands-send-activity-to-client.md)

-description: set up web endpoints for Custom Commands

-# Set up web endpoints

-In this article, you learn how to set up web endpoints in a Custom Commands application that allow you to make HTTP requests from a client application. You complete the following tasks:

-## Prerequisites

-> [!div class = "checklist"]

-> * [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/)

-> * An Azure AI Speech resource key and region: Create a Speech resource on the [Azure portal](https://portal.azure.com). For more information, see [Create a multi-service resource](../multi-service-resource.md?pivots=azportal).

-> * A Custom Commands app (see [Create a voice assistant using Custom Commands](quickstart-custom-commands-application.md))

-> * A Speech SDK enabled client app (see [Integrate with a client application using Speech SDK](how-to-custom-commands-setup-speech-sdk.md))

-## Deploy an external web endpoint using Azure Function app

-For this tutorial, you need an HTTP endpoint that maintains states for all the devices you set up in the **TurnOnOff** command of your Custom Commands application.

-If you already have a web endpoint you want to call, skip to the [next section](#set-up-web-endpoints-in-custom-commands).

-Alternatively, the next section provides details about a default hosted web endpoint you can use if you want to skip this section.

-### Input format of Azure function

-Next, you deploy an endpoint using [Azure Functions](../../azure-functions/index.yml).

-The following is the format of a Custom Commands event that is passed to your Azure function. Use this information when you're writing your Azure Function app.

-```json

-{

- "conversationId": "string",

- "currentCommand": {

- "name": "string",

- "parameters": {

- "SomeParameterName": "string",

- "SomeOtherParameterName": "string"

- }

- },

- "currentGlobalParameters": {

- "SomeGlobalParameterName": "string",

- "SomeOtherGlobalParameterName": "string"

- }

-}

-```

-

-The following table describes the key attributes of this input:

-

-| Attribute | Explanation |

-| - | |

-| **conversationId** | The unique identifier of the conversation. Note this ID can be generated by the client app. |

-| **currentCommand** | The command that's currently active in the conversation. |

-| **name** | The name of the command. The `parameters` attribute is a map with the current values of the parameters. |

-| **currentGlobalParameters** | A map like `parameters`, but used for global parameters. |

-For the **DeviceState** Azure Function, an example Custom Commands event looks like following. This acts as an **input** to the function app.

-

-```json

-{

- "conversationId": "someConversationId",

- "currentCommand": {

- "name": "TurnOnOff",

- "parameters": {

- "item": "tv",

- "value": "on"

- }

- }

-}

-```

-### Azure Function output for a Custom Command app

-If output from your Azure Function is consumed by a Custom Commands app, it should appear in the following format. See [Update a command from a web endpoint](./how-to-custom-commands-update-command-from-web-endpoint.md) for details.

-```json

-{

- "updatedCommand": {

- "name": "SomeCommandName",

- "updatedParameters": {

- "SomeParameterName": "SomeParameterValue"

- },

- "cancel": false

- },

- "updatedGlobalParameters": {

- "SomeGlobalParameterName": "SomeGlobalParameterValue"

- }

-}

-```

-### Azure Function output for a client application

-If output from your Azure Function is consumed by a client application, the output can take whatever form the client application requires.

-For our **DeviceState** endpoint, output of your Azure function is consumed by a client application instead of the Custom Commands application. Example output of the Azure function should look like the following:

-

-```json

-{

- "TV": "on",

- "Fan": "off"

-}

-```

-This output should be written to an external storage, so that you can maintain the state of devices. The external storage state is used in the [Integrate with client application](#integrate-with-client-application) section below.

-### Deploy Azure function

-We provide a sample you can configure and deploy as an Azure Functions app. To create a storage account for our sample, follow these steps.

-

-1. Create table storage to save device state. In the Azure portal, create a new resource of type **Storage account** by name **devicestate**.

-1. Copy the **Connection string** value from **devicestate -> Access keys**. You need to add this string secret to the downloaded sample Function App code.

-1. Download sample [Function App code](https://github.com/Azure-Samples/Cognitive-Services-Voice-Assistant/tree/main/custom-commands/quick-start).

-1. Open the downloaded solution in Visual Studio 2019. In **Connections.json**, replace **STORAGE_ACCOUNT_SECRET_CONNECTION_STRING** with the secret from Step 2.

-1. Download the **DeviceStateAzureFunction** code.

-To deploy the sample app to Azure Functions, follow these steps.

-1. [Deploy](../../azure-functions/index.yml) the Azure Functions app.

-1. Wait for deployment to succeed and go the deployed resource on the Azure portal.

-1. Select **Functions** in the left pane, and then select **DeviceState**.

-1. In the new window, select **Code + Test** and then select **Get function URL**.

-

-## Set up web endpoints in Custom Commands

-Let's hook up the Azure function with the existing Custom Commands application.

-In this section, you use an existing default **DeviceState** endpoint. If you created your own web endpoint using Azure Function or otherwise, use that instead of the default `https://webendpointexample.azurewebsites.net/api/DeviceState`.

-1. Open the Custom Commands application you previously created.

-1. Go to **Web endpoints**, select **New web endpoint**.

- > [!div class="mx-imgBorder"]

- > 

- | Setting | Suggested value | Description |

- | - | | -- |

- | Name | UpdateDeviceState | Name for the web endpoint. |

- | URL | ```https://webendpointexample.azurewebsites.net/api/DeviceState``` | The URL of the endpoint you wish your custom command app to talk to. |

- | Method | POST | The allowed interactions (such as GET, POST) with your endpoint.|

- | Headers | Key: app, Value: take the first eight digits of your applicationId | The header parameters to include in the request header.|

- > [!NOTE]

- > - The example web endpoint created using [Azure Functions](../../azure-functions/index.yml), which hooks up with the database that saves the device state of the tv and fan.

- > - The suggested header is only needed for the example endpoint.

- > - To make sure the value of the header is unique in our example endpoint, take the first 8 digits of your **applicationId**.

- > - In real world, the web endpoint can be the endpoint to the [IOT hub](../../iot-hub/about-iot-hub.md) that manages your devices.

-1. Select **Save**.

-## Call web endpoints

-1. Go to **TurnOnOff** command, select **ConfirmationResponse** under completion rule, then select **Add an action**.

-1. Under **New Action-Type**, select **Call web endpoint**

-1. In **Edit Action - Endpoints**, select **UpdateDeviceState**, which is the web endpoint we created.

-1. In **Configuration**, put the following values:

- > [!div class="mx-imgBorder"]

- > 

- | Setting | Suggested value | Description |

- | - | | -- |

- | Endpoints | UpdateDeviceState | The web endpoint you wish to call in this action. |

- | Query parameters | item={SubjectDevice}&&value={OnOff} | The query parameters to append to the web endpoint URL. |

- | Body content | N/A | The body content of the request. |

- > [!NOTE]

- > - The suggested query parameters are only needed for the example endpoint

-1. In **On Success - Action to execute**, select **Send speech response**.

- In **Simple editor**, enter `{SubjectDevice} is {OnOff}`.

- > [!div class="mx-imgBorder"]

- > 

- | Setting | Suggested value | Description |

- | - | | -- |

- | Action to execute | Send speech response | Action to execute if the request to web endpoint succeeds |

- > [!NOTE]

- > - You can also directly access the fields in the http response by using `{YourWebEndpointName.FieldName}`. For example: `{UpdateDeviceState.TV}`

-1. In **On Failure - Action to execute**, select **Send speech response**

- In **Simple editor**, enter `Sorry, {WebEndpointErrorMessage}`.

- > [!div class="mx-imgBorder"]

- > 

- | Setting | Suggested value | Description |

- | - | | -- |

- | Action to execute | Send speech response | Action to execute if the request to web endpoint fails |

- > [!NOTE]

- > - `{WebEndpointErrorMessage}` is optional. You are free to remove it if you don't want to expose any error message.

- > - Within our example endpoint, we send back http response with detailed error messages for common errors such as missing header parameters.

-### Try it out in test portal

- > [!div class="mx-imgBorder"]

- > 

- > [!div class="mx-imgBorder"]

- > 

-## Integrate with client application

-In [Send Custom Commands activity to client application](./how-to-custom-commands-send-activity-to-client.md), you added a **Send activity to client** action. The activity is sent to the client application whether or not **Call web endpoint** action is successful or not.

-However, typically you only want to send activity to the client application when the call to the web endpoint is successful. In this example, this is when the device's state is successfully updated.

-1. Delete the **Send activity to client** action you previously added.

-1. Edit call web endpoint:

- 1. In **Configuration**, make sure **Query Parameters** is `item={SubjectDevice}&&value={OnOff}`

- 1. In **On Success**, change **Action to execute** to **Send activity to client**

- 1. Copy the JSON below to the **Activity Content**

- ```json

- {

- "type": "event",

- "name": "UpdateDeviceState",

- "value": {

- "state": "{OnOff}",

- "device": "{SubjectDevice}"

- }

- }

- ```

-Now you only send activity to the client when the request to the web endpoint is successful.

-### Create visuals for syncing device state

-Add the following XML to `MainPage.xaml` above the **EnableMicrophoneButton** block.

-```xml

-<Button x:Name="SyncDeviceStateButton" Content="Sync Device State"

- Margin="0,10,10,0" Click="SyncDeviceState_ButtonClicked"

- Height="35"/>

-<Button x:Name="EnableMicrophoneButton" ......

- .........../>

-```

-### Sync device state

-In `MainPage.xaml.cs`, add the reference `using Windows.Web.Http;`. Add the following code to the `MainPage` class. This method sends a GET request to the example endpoint, and extract the current device state for your app. Make sure to change `<your_app_name>` to what you used in the **header** in Custom Command web endpoint.

-```C#

-private async void SyncDeviceState_ButtonClicked(object sender, RoutedEventArgs e)

-{

- //Create an HTTP client object

- var httpClient = new HttpClient();

- //Add a user-agent header to the GET request.

- var your_app_name = "<your-app-name>";

- Uri endpoint = new Uri("https://webendpointexample.azurewebsites.net/api/DeviceState");

- var requestMessage = new HttpRequestMessage(HttpMethod.Get, endpoint);

- requestMessage.Headers.Add("app", $"{your_app_name}");

- try

- {

- //Send the GET request

- var httpResponse = await httpClient.SendRequestAsync(requestMessage);

- httpResponse.EnsureSuccessStatusCode();

- var httpResponseBody = await httpResponse.Content.ReadAsStringAsync();

- dynamic deviceState = JsonConvert.DeserializeObject(httpResponseBody);

- var TVState = deviceState.TV.ToString();

- var FanState = deviceState.Fan.ToString();

- await CoreApplication.MainView.CoreWindow.Dispatcher.RunAsync(

- CoreDispatcherPriority.Normal,

- () =>

- {

- State_TV.Text = TVState;

- State_Fan.Text = FanState;

- });

- }

- catch (Exception ex)

- {

- NotifyUser(

- $"Unable to sync device status: {ex.Message}");

- }

-}

-```

-## Try it out

-1. Start the application.

-1. Select Sync Device State.\

-If you tested out the app with `turn on tv` in previous section, you would see the TV shows as **on**.

- > [!div class="mx-imgBorder"]

- > 

-1. Select **Enable microphone**.

-1. Select the **Talk** button.

-1. Say `turn on the fan`. The visual state of the fan should change to **on**.

- > [!div class="mx-imgBorder"]

- > 

-## Next steps

-> [!div class="nextstepaction"]

-> [Update a command from a client app](./how-to-custom-commands-update-command-from-client.md)

-description: Learn how to update a command from a client application.

-# Update a command from a client app

-In this article, you learn how to update an ongoing command from a client application.

-## Prerequisites

-> [!div class = "checklist"]

-> * A previously [created Custom Commands app](quickstart-custom-commands-application.md)

-## Update the state of a command

-If your client application requires you to update the state of an ongoing command without voice input, you can send an event to update the command.

-To illustrate this scenario, send the following event activity to update the state of an ongoing command (`TurnOnOff`):

-```json

-{

- "type": "event",

- "name": "RemoteUpdate",

- "value": {

- "updatedCommand": {

- "name": "TurnOnOff",

- "updatedParameters": {

- "OnOff": "on"

- },

- "cancel": false

- },

- "updatedGlobalParameters": {},

- "processTurn": true

- }

-}

-```

-Let's review the key attributes of this activity:

-| Attribute | Explanation |

-| - | |

-| **type** | The activity is of type `"event"`. |

-| **name** | The name of the event needs to be `"RemoteUpdate"`. |

-| **value** | The attribute `"value"` contains the attributes required to update the current command. |

-| **updatedCommand** | The attribute `"updatedCommand"` contains the name of the command. Within that attribute, `"updatedParameters"` is a map with the names of the parameters and their updated values. |

-| **cancel** | If the ongoing command needs to be canceled, set the attribute `"cancel"` to `true`. |

-| **updatedGlobalParameters** | The attribute `"updatedGlobalParameters"` is a map just like `"updatedParameters"`, but it's used for global parameters. |

-| **processTurn** | If the turn needs to be processed after the activity is sent, set the attribute `"processTurn"` to `true`. |

-You can test this scenario in the Custom Commands portal:

-1. Open the Custom Commands application that you previously created.

-1. Select **Train** and then **Test**.

-1. Send `turn`.

-1. Open the side panel and select **Activity editor**.

-1. Type and send the `RemoteCommand` event specified in the previous section.

- > [!div class="mx-imgBorder"]

- > 

-Note how the value for the parameter `"OnOff"` was set to `"on"` through an activity from the client instead of speech or text.

-## Update the catalog of the parameter for a command

-When you configure the list of valid options for a parameter, the values for the parameter are defined globally for the application.

-In our example, the `SubjectDevice` parameter has a fixed list of supported values regardless of the conversation.

-If you want to add new entries to the parameter's catalog per conversation, you can send the following activity:

-```json

-{

- "type": "event",

- "name": "RemoteUpdate",

- "value": {

- "catalogUpdate": {

- "commandParameterCatalogs": {

- "TurnOnOff": [

- {

- "name": "SubjectDevice",

- "values": {

- "stereo": [

- "cd player"

- ]

- }

- }

- ]

- }

- },

- "processTurn": false

- }

-}

-```

-With this activity, you added an entry for `"stereo"` to the catalog of the parameter `"SubjectDevice"` in the command `"TurnOnOff"`.

-> [!div class="mx-imgBorder"]

-> :::image type="content" source="./media/custom-commands/update-catalog-with-remote-activity.png" alt-text="Screenshot that shows a catalog update.":::

-Note a couple of things:

-## Add more context from the client application

-You can set more context from the client application per conversation that can later be used in your Custom Commands application.

-For example, think about the scenario where you want to send the ID and name of the device connected to the Custom Commands application.

-To test this scenario, let's create a new command in the current application:

-1. Create a new command called `GetDeviceInfo`.

-1. Add an example sentence of `get device info`.

-1. In the completion rule **Done**, add a **Send speech response** action that contains the attributes of `clientContext`.

- 

-1. Save, train, and test your application.

-1. In the testing window, send an activity to update the client context.

- ```json

- {

- "type": "event",

- "name": "RemoteUpdate",

- "value": {

- "clientContext": {

- "deviceId": "12345",

- "deviceName": "My device"

- },

- "processTurn": false

- }

- }

- ```

-1. Send the text `get device info`.

- 

-Note a few things:

-## Next steps

-> [!div class="nextstepaction"]

-> [Update a command from a web endpoint](./how-to-custom-commands-update-command-from-web-endpoint.md)

-description: Learn how to update the state of a command by using a call to a web endpoint.

-# Update a command from a web endpoint

-If your client application requires an update to the state of an ongoing command without voice input, you can use a call to a web endpoint to update the command.

-In this article, you learn how to update an ongoing command from a web endpoint.

-## Prerequisites

-> [!div class = "checklist"]

-> * A previously [created Custom Commands app](quickstart-custom-commands-application.md)

-## Create an Azure function

-For this example, you need an HTTP-triggered [Azure function](../../azure-functions/index.yml) that supports the following input (or a subset of this input):

-```JSON

-{

- "conversationId": "SomeConversationId",

- "currentCommand": {

- "name": "SomeCommandName",

- "parameters": {

- "SomeParameterName": "SomeParameterValue",

- "SomeOtherParameterName": "SomeOtherParameterValue"

- }

- },

- "currentGlobalParameters": {

- "SomeGlobalParameterName": "SomeGlobalParameterValue",

- "SomeOtherGlobalParameterName": "SomeOtherGlobalParameterValue"

- }

-}

-```

-Let's review the key attributes of this input:

-| Attribute | Explanation |

-| - | |

-| **conversationId** | The unique identifier of the conversation. This ID can be generated from the client app. |

-| **currentCommand** | The command that's currently active in the conversation. |

-| **name** | The name of the command. The `parameters` attribute is a map with the current values of the parameters. |

-| **currentGlobalParameters** | A map like `parameters`, but used for global parameters. |

-The output of the Azure function needs to support the following format:

-```JSON

-{

- "updatedCommand": {

- "name": "SomeCommandName",

- "updatedParameters": {

- "SomeParameterName": "SomeParameterValue"

- },

- "cancel": false

- },

- "updatedGlobalParameters": {

- "SomeGlobalParameterName": "SomeGlobalParameterValue"

- }

-}

-```

-You might recognize this format because it's the same one that you used when [updating a command from the client](./how-to-custom-commands-update-command-from-client.md).

-Now, create an Azure function based on Node.js. Copy/paste this code:

-```nodejs

-module.exports = async function (context, req) {

- context.log(req.body);

- context.res = {

- body: {

- updatedCommand: {

- name: "IncrementCounter",

- updatedParameters: {

- Counter: req.body.currentCommand.parameters.Counter + 1

- }

- }

- }

- };

-}

-```

-When you call this Azure function from Custom Commands, you send the current values of the conversation. You return the parameters that you want to update or if you want to cancel the current command.

-## Update the existing Custom Commands app

-Let's hook up the Azure function with the existing Custom Commands app:

-1. Add a new command named `IncrementCounter`.

-1. Add just one example sentence with the value `increment`.

-1. Add a new parameter called `Counter` (same name as specified in the Azure function) of type `Number` with a default value of `0`.

-1. Add a new web endpoint called `IncrementEndpoint` with the URL of your Azure function, with **Remote updates** set to **Enabled**.

- > [!div class="mx-imgBorder"]

- > :::image type="content" source="./media/custom-commands/set-web-endpoint-with-remote-updates.png" alt-text="Screenshot that shows setting a web endpoint with remote updates.":::

-1. Create a new interaction rule called **IncrementRule** and add a **Call web endpoint** action.

- > [!div class="mx-imgBorder"]

- > :::image type="content" source="./media/custom-commands/increment-rule-web-endpoint.png" alt-text="Screenshot that shows the creation of an interaction rule.":::

-1. In the action configuration, select `IncrementEndpoint`. Configure **On success** to **Send speech response** with the value of `Counter`, and configure **On failure** with an error message.

- > [!div class="mx-imgBorder"]

- > :::image type="content" source="./media/custom-commands/set-increment-counter-call-endpoint.png" alt-text="Screenshot that shows setting an increment counter for calling a web endpoint.":::

-1. Set the post-execution state of the rule to **Wait for user's input**.

-## Test it

-1. Save and train your app.

-1. Select **Test**.

-1. Send `increment` a few times (which is the example sentence for the `IncrementCounter` command).

- > [!div class="mx-imgBorder"]

- > :::image type="content" source="./media/custom-commands/increment-counter-example-no-mic.png" alt-text="Screenshot that shows an increment counter example.":::

-Notice how the Azure function increments the value of the `Counter` parameter on each turn.

-## Next steps

-> [!div class="nextstepaction"]

-> [Enable a CI/CD process for your Custom Commands application](./how-to-custom-commands-deploy-cicd.md)

-description: Learn how to develop and customize Custom Commands applications. These voice-command apps are best suited for task completion or command-and-control scenarios.

-# Develop Custom Commands applications

-In this how-to article, you learn how to develop and configure Custom Commands applications. The Custom Commands feature helps you build rich voice-command apps that are optimized for voice-first interaction experiences. The feature is best suited to task completion or command-and-control scenarios. It's well suited for Internet of Things (IoT) devices and for ambient and headless devices.

-In this article, you create an application that can turn a TV on and off, set the temperature, and set an alarm. After you create these basic commands, you'll learn about the following options for customizing commands:

-* Adding parameters to commands

-* Adding configurations to command parameters

-* Building interaction rules

-* Creating language-generation templates for speech responses

-* Using custom voice tools

-## Create an application by using simple commands

-Start by creating an empty Custom Commands application. For details, refer to the [quickstart](quickstart-custom-commands-application.md). In this application, instead of importing a project, you create a blank project.

-1. In the **Name** box, enter the project name *Smart-Room-Lite* (or another name of your choice).

-1. In the **Language** list, select **English (United States)**.

-1. Select or create a LUIS resource.

- > [!div class="mx-imgBorder"]

- > 

-### Update LUIS resources (optional)

-You can update the authoring resource that you selected in the **New project** window. You can also set a prediction resource.

-A prediction resource is used for recognition when your Custom Commands application is published. You don't need a prediction resource during the development and testing phases.

-### Add a TurnOn command

-In the empty Smart-Room-Lite Custom Commands application you created, add a command. The command processes an utterance, `Turn on the tv`. It responds with the message `Ok, turning the tv on`.

-1. Create a new command by selecting **New command** at the top of the left pane. The **New command** window opens.

-1. For the **Name** field, provide the value `TurnOn`.

-1. Select **Create**.

-The middle pane lists the properties of the command.

-The following table explains the command's configuration properties. For more information, see [Custom Commands concepts and definitions](./custom-commands-references.md).

-| Configuration | Description |

-| - | |

-| Example sentences | Example utterances the user can say to trigger this command. |

-| Parameters | Information required to complete the command. |

-| Completion rules | Actions to be taken to fulfill the command. Examples: responding to the user or communicating with a web service. |

-| Interaction rules | Other rules to handle more specific or complex situations. |

-> [!div class="mx-imgBorder"]

-> 

-#### Add example sentences

-In the **Example sentences** section, you provide an example of what the user can say.

-1. In the middle pane, select **Example sentences**.

-1. In the pane on the right, add examples:

- ```

- Turn on the tv

- ```

-1. At the top of the pane, select **Save**.

-You don't have parameters yet, so you can move to the **Completion rules** section.

-#### Add a completion rule

-Next, the command needs a completion rule. This rule tells the user that a fulfillment action is being taken.

-For more information about rules and completion rules, see [Custom Commands concepts and definitions](./custom-commands-references.md).

-1. Select the default completion rule **Done**. Then edit it as follows:

- | Setting | Suggested value | Description |

- | - | - | -- |

- | **Name** | `ConfirmationResponse` | A name describing the purpose of the rule |

- | **Conditions** | None | Conditions that determine when the rule can run |

- | **Actions** | **Send speech response** > **Simple editor** > `Ok, turning the tv on` | The action to take when the rule condition is true |

- > [!div class="mx-imgBorder"]

- > 

-1. Select **Save** to save the action.

-1. Back in the **Completion rules** section, select **Save** to save all changes.

- > [!NOTE]

- > You don't have to use the default completion rule that comes with the command. You can delete the default completion rule and add your own rule.

-### Add a SetTemperature command

-Now add one more command, `SetTemperature`. This command takes a single utterance, `Set the temperature to 40 degrees`, and respond with the message `Ok, setting temperature to 40 degrees`.

-To create the new command, follow the steps you used for the `TurnOn` command, but use the example sentence `Set the temperature to 40 degrees`.

-Then edit the existing **Done** completion rules as follows:

-| Setting | Suggested value |

-| - | - |

-| **Name** | `ConfirmationResponse` |

-| **Conditions** | None |

-| **Actions** | **Send speech response** > **Simple editor** > **First variation** > `Ok, setting temperature to 40 degrees` |

-Select **Save** to save all changes to the command.

-### Add a SetAlarm command

-Create a new `SetAlarm` command. Use the example sentence `Set an alarm for 9 am tomorrow`. Then edit the existing **Done** completion rules as follows:

-| Setting | Suggested value |

-| - | - |

-| **Name** | `ConfirmationResponse` |

-| **Conditions** | None |

-| **Actions** | **Send speech response** > **Simple editor** > **First variation** > `Ok, setting an alarm for 9 am tomorrow` |

-Select **Save** to save all changes to the command.

-### Try it out

-Test the application's behavior by using the test pane:

-1. In the upper-right corner of the pane, select the **Train** icon.

-1. When the training finishes, select **Test**.

-Try out the following utterance examples by using voice or text:

-> [!div class="mx-imgBorder"]

-> 

-> [!TIP]

-> In the test pane, you can select **Turn details** for information about how this voice input or text input was processed.

-## Add parameters to commands

-In this section, you learn how to add parameters to your commands. Commands require parameters to complete a task. In complex scenarios, parameters can be used to define conditions that trigger custom actions.

-### Configure parameters for a TurnOn command

-Start by editing the existing `TurnOn` command to turn on and turn off multiple devices.

-1. Now that the command handles both on and off scenarios, rename the command as *TurnOnOff*.

- 1. In the pane on the left, select the **TurnOn** command. Then next to **New command** at the top of the pane, select the edit button.

- 1. In the **Rename command** window, change the name to *TurnOnOff*.

-1. Add a new parameter to the command. The parameter represents whether the user wants to turn the device on or off.

- 1. At top of the middle pane, select **Add**. From the drop-down menu, select **Parameter**.

- 1. In the pane on the right, in the **Parameters** section, in the **Name** box, add `OnOff`.

- 1. Select **Required**. In the **Add response for a required parameter** window, select **Simple editor**. In the **First variation** field, add *On or Off*.

- 1. Select **Update**.

- > [!div class="mx-imgBorder"]

- > 

- 1. Configure the parameter's properties by using the following table. For information about all of the configuration properties of a command, see [Custom Commands concepts and definitions](./custom-commands-references.md).

- | Configuration | Suggested value | Description |

- | | -| |

- | **Name** | `OnOff` | A descriptive name for the parameter |

- | **Required** | Selected | Check box indicating whether a value for this parameter is required before the command finishes. |

- | **Response for required parameter** |**Simple editor** > `On or Off?` | A prompt asking for the value of this parameter when it isn't known. |

- | **Type** | **String** | Parameter type, such as Number, String, Date Time, or Geography. |

- | **Configuration** | **Accept predefined input values from an internal catalog** | For strings, this setting limits inputs to a set of possible values. |

- | **Predefined input values** | `on`, `off` | Set of possible values and their aliases. |

- 1. To add predefined input values, select **Add a predefined input**. In **New Item** window, type *Name* as shown in the preceding table. In this case, you're not using aliases, so you can leave this field blank.

- > [!div class="mx-imgBorder"]

- > 

- 1. Select **Save** to save all configurations of the parameter.

-#### Add a SubjectDevice parameter

-1. To add a second parameter to represent the name of the devices that can be controlled by using this command, select **Add**. Use the following configuration.

- | Setting | Suggested value |

- | | |

- | **Name** | `SubjectDevice` |

- | **Required** | Selected |

- | **Response for required parameter** | **Simple editor** > `Which device do you want to control?` |

- | **Type** | **String** |

- | **Configuration** | **Accept predefined input values from an internal catalog** |

- | **Predefined input values** | `tv`, `fan` |

- | **Aliases** (`tv`) | `television`, `telly` |

-1. Select **Save**.

-#### Modify example sentences

-For commands that use parameters, it's helpful to add example sentences that cover all possible combinations. For example:

-* Complete parameter information: `turn {OnOff} the {SubjectDevice}`

-* Partial parameter information: `turn it {OnOff}`

-* No parameter information: `turn something`

-Example sentences that use varying degrees of information allow the Custom Commands application to resolve both one-shot resolutions and multiple-turn resolutions by using partial information.

-With that information in mind, edit the example sentences to use these suggested parameters:

-```

-turn {OnOff} the {SubjectDevice}

-{SubjectDevice} {OnOff}

-turn it {OnOff}

-turn something {OnOff}

-turn something

-```

-Select **Save**.

-> [!TIP]

-> In the example-sentences editor, use curly braces to refer to your parameters. For example, `turn {OnOff} the {SubjectDevice}`.

-> Use a tab for automatic completion backed by previously created parameters.

-#### Modify completion rules to include parameters

-Modify the existing completion rule `ConfirmationResponse`.

-1. In the **Conditions** section, select **Add a condition**.

-1. In the **New Condition** window, in the **Type** list, select **Required parameters**. In the list that follows, select both **OnOff** and **SubjectDevice**.

-1. Select **Create**.

-1. In the **Actions** section, edit the **Send speech response** action by hovering over it and selecting the edit button. This time, use the newly created `OnOff` and `SubjectDevice` parameters:

- ```

- Ok, turning the {SubjectDevice} {OnOff}

- ```

-1. Select **Save**.

-Try out the changes by selecting the **Train** icon at the top of the pane on the right.

-When the training finishes, select **Test**. A **Test your application** window appears. Try the following interactions:

-### Configure parameters for a SetTemperature command

-Modify the `SetTemperature` command to enable it to set the temperature as the user directs.

-Add a `TemperatureValue` parameter. Use the following configuration:

-| Configuration | Suggested value |

-| | -|

-| **Name** | `TemperatureValue` |

-| **Required** | Selected |

-| **Response for required parameter** | **Simple editor** > `What temperature would you like?`

-| **Type** | `Number` |

-Edit the example utterances to use the following values.

-```

-set the temperature to {TemperatureValue} degrees

-change the temperature to {TemperatureValue}

-set the temperature

-change the temperature

-```

-Edit the existing completion rules. Use the following configuration.

-| Configuration | Suggested value |

-| | -|

-| **Conditions** | **Required parameter** > **TemperatureValue** |

-| **Actions** | **Send speech response** > `Ok, setting temperature to {TemperatureValue} degrees` |

-### Configure parameters for a SetAlarm command

-Add a parameter called `DateTime`. Use the following configuration.

- | Setting | Suggested value |

- | | -|

- | **Name** | `DateTime` |

- | **Required** | Selected |

- | **Response for required parameter** | **Simple editor** > `For what time?` |

- | **Type** | **DateTime** |

- | **Date Defaults** | If the date is missing, use today. |

- | **Time Defaults** | If the time is missing, use the start of the day. |

-> [!NOTE]

-> This article mostly uses String, Number, and DateTime parameter types. For a list of all supported parameter types and their properties, see [Custom Commands concepts and definitions](./custom-commands-references.md).

-Edit the example utterances. Use the following values.

-```

-set an alarm for {DateTime}

-set alarm {DateTime}

-alarm for {DateTime}

-```

-Edit the existing completion rules. Use the following configuration.

- | Setting | Suggested value |

- | - | - |

- | **Actions** | **Send speech response** > `Ok, alarm set for {DateTime}` |

-Test the three commands together by using utterances related to different commands. (You can switch between the different commands.)

-## Add configurations to command parameters

-In this section, you learn more about advanced parameter configuration, including:

-### Configure a parameter as an external catalog entity

-The Custom Commands feature allows you to configure string-type parameters to refer to external catalogs hosted over a web endpoint. So you can update the external catalog independently without editing the Custom Commands application. This approach is useful in cases where the catalog entries are numerous.

-Reuse the `SubjectDevice` parameter from the `TurnOnOff` command. The current configuration for this parameter is **Accept predefined inputs from internal catalog**. This configuration refers to a static list of devices in the parameter configuration. Move out this content to an external data source that can be updated independently.

-To move the content, start by adding a new web endpoint. In the pane on the left, go to the **Web endpoints** section. Add a new web endpoint URL. Use the following configuration.

-| Setting | Suggested value |

-|-|-|

-| **Name** | `getDevices` |

-| **URL** | `<Your endpoint of getDevices.json>` |

-| **Method** | **GET** |

-Then, configure and host a web endpoint that returns a JSON file that lists the devices that can be controlled. The web endpoint should return a JSON file formatted like this example:

-```json

-{

- "fan" : [],

- "refrigerator" : [

- "fridge"

- ],

- "lights" : [

- "bulb",

- "bulbs",

- "light",

- "light bulb"

- ],

- "tv" : [

- "telly",

- "television"

- ]

-}

-```

-Next go the **SubjectDevice** parameter settings page. Set up the following properties.

-| Setting | Suggested value |

-| -| - |

-| **Configuration** | **Accept predefined inputs from external catalog** |

-| **Catalog endpoint** | `getDevices` |

-| **Method** | **GET** |

-Then select **Save**.

-> [!IMPORTANT]

-> You won't see an option to configure a parameter to accept inputs from an external catalog unless you have the web endpoint set in the **Web endpoint** section in the pane on the left.

-Try it out by selecting **Train**. After the training finishes, select **Test** and try a few interactions.

-* Input: *turn on*

-* Output: Which device do you want to control?

-* Input: *lights*

-* Output: Ok, turning the lights on

-> [!NOTE]

-> You can now control all the devices hosted on the web endpoint. But you still need to train the application to test the new changes and then republish the application.

-### Add validation to parameters

-*Validations* are constructs that apply to certain parameter types that allow you to configure constraints on the parameter's value. They prompt you for corrections if values don't fall within the constraints. For a list of parameter types that extend the validation construct, see [Custom Commands concepts and definitions](./custom-commands-references.md).

-Test out validations by using the `SetTemperature` command. Use the following steps to add a validation for the `Temperature` parameter.

-1. In the pane on the left, select the **SetTemperature** command.

-1. In the middle pane, select **Temperature**.

-1. In the pane on the right, select **Add a validation**.

-1. In the **New validation** window, configure validation as shown in the following table. Then select **Create**.

- | Parameter configuration | Suggested value | Description |

- | - | - | - |

- | **Min Value** | `60` | For Number parameters, the minimum value this parameter can assume |

- | **Max Value** | `80` | For Number parameters, the maximum value this parameter can assume |

- | **Failure response** | **Simple editor** > **First variation** > `Sorry, I can only set temperature between 60 and 80 degrees. What temperature do you want?` | A prompt to ask for a new value if the validation fails |

- > [!div class="mx-imgBorder"]

- > 

-Try it out by selecting the **Train** icon at the top of the pane on the right. After the training finishes, select **Test**. Try a few interactions:

-## Add interaction rules

-Interaction rules are extra rules that handle specific or complex situations. Although you're free to author your own interaction rules, in this example you use interaction rules for the following scenarios:

-* Confirming commands

-* Adding a one-step correction to commands

-For more information about interaction rules, see [Custom Commands concepts and definitions](./custom-commands-references.md).

-### Add confirmations to a command

-To add a confirmation, you use the `SetTemperature` command. To achieve confirmation, create interaction rules by using the following steps:

-1. In the pane on the left, select the **SetTemperature** command.

-1. In the middle pane, add interaction rules by selecting **Add**. Then select **Interaction rules** > **Confirm command**.

- This action adds three interaction rules. The rules ask the user to confirm the date and time of the alarm. They expect a confirmation (yes or no) for the next turn.

- 1. Modify the **Confirm command** interaction rule by using the following configuration:

- 1. Change the name to **Confirm temperature**.

- 1. The condition **All required parameters** is already set.

- 1. Add a new action: **Type** > **Send speech response** > **Are you sure you want to set the temperature as {TemperatureValue} degrees?**

- 1. In the **Expectations** section, leave the default value of **Expecting confirmation from user**.

- > [!div class="mx-imgBorder"]

- > 

- 1. Modify the **Confirmation succeeded** interaction rule to handle a successful confirmation (the user said yes).

- 1. Change the name to **Confirmation temperature succeeded**.

- 1. Leave the existing **Confirmation was successful** condition.

- 1. Add a new condition: **Type** > **Required parameters** > **TemperatureValue**.

- 1. Leave the default **Post-execution state** value as **Execute completion rules**.

- 1. Modify the **Confirmation denied** interaction rule to handle scenarios when confirmation is denied (the user said no).

- 1. Change the name to **Confirmation temperature denied**.

- 1. Leave the existing **Confirmation was denied** condition.

- 1. Add a new condition: **Type** > **Required parameters** > **TemperatureValue**.

- 1. Add a new action: **Type** > **Send speech response** > **No problem. What temperature then?**.

- 1. Change the default **Post-execution state** value to **Wait for user's input**.

-> [!IMPORTANT]

-> In this article, you use the built-in confirmation capability. You can also manually add interaction rules one by one.

-Try out the changes by selecting **Train**. When the training finishes, select **Test**.

-### Implement corrections in a command

-In this section, you configure a one-step correction. This correction is used after the fulfillment action has run. You'll also see an example of how a correction is enabled by default if the command isn't fulfilled yet. To add a correction when the command isn't finished, add the new parameter `AlarmTone`.

-In the left pane, select the **SetAlarm** command. Then and add the new parameter **AlarmTone**.

-Next, update the response for the **DateTime** parameter to **Ready to set alarm with tone as {AlarmTone}. For what time?**. Then modify the completion rule as follows:

-1. Select the existing completion rule **ConfirmationResponse**.

-1. In the pane on the right, hover over the existing action and select **Edit**.

-1. Update the speech response to `OK, alarm set for {DateTime}. The alarm tone is {AlarmTone}`.

-> [!IMPORTANT]

-> The alarm tone can change without any explicit configuration in an ongoing command. For example, it can change when the command hasn't finished yet. A correction is enabled *by default* for all of the command parameters, regardless of the turn number, if the command is yet to be fulfilled.

-#### Implement a correction when a command is finished

-The Custom Commands platform allows for one-step correction even when the command finishes. This feature isn't enabled by default. It must be explicitly configured.

-Use the following steps to configure a one-step correction:

-1. In the **SetAlarm** command, add an interaction rule of the type **Update previous command** to update the previously set alarm. Rename the interaction rule as **Update previous alarm**.

-1. Leave the default condition: **Previous command needs to be updated**.

-1. Add a new condition: **Type** > **Required Parameter** > **DateTime**.

-1. Add a new action: **Type** > **Send speech response** > **Simple editor** > **Updating previous alarm time to {DateTime}**.

-1. Leave the default **Post-execution state** value as **Command completed**.

-Try out the changes by selecting **Train**. Wait for the training to finish, and then select **Test**.

-> [!NOTE]

-> In a real application, in the **Actions** section of this correction rule, you'll also need to send back an activity to the client or call an HTTP endpoint to update the alarm time in your system. This action should be solely responsible for updating the alarm time. It shouldn't be responsible for any other attribute of the command. In this case, that attribute would be the alarm tone.

-## Add language-generation templates for speech responses

-Language-generation (LG) templates allow you to customize the responses sent to the client. They introduce variance into the responses. You can achieve language generation by using:

-* Language-generation templates.

-* Adaptive expressions.

-Custom Commands templates are based on the Bot Framework's [LG templates](/azure/bot-service/file-format/bot-builder-lg-file-format#templates). Because the Custom Commands feature creates a new LG template when required (for speech responses in parameters or actions), you don't have to specify the name of the LG template.

-So you don't need to define your template like this:

- ```

- # CompletionAction

- - Ok, turning {OnOff} the {SubjectDevice}

- - Done, turning {OnOff} the {SubjectDevice}

- - Proceeding to turn {OnOff} {SubjectDevice}

- ```

-Instead, you can define the body of the template without the name, like this:

-> [!div class="mx-imgBorder"]

-> 

-This change introduces variation into the speech responses that are sent to the client. For an utterance, the corresponding speech response is randomly picked out of the provided options.

-By taking advantage of LG templates, you can also define complex speech responses for commands by using adaptive expressions. For more information, see the [LG templates format](/azure/bot-service/file-format/bot-builder-lg-file-format#templates).

-By default, the Custom Commands feature supports all capabilities, with the following minor differences:

-* In the LG templates, entities are represented as `${entityName}`. The Custom Commands feature doesn't use entities. But you can use parameters as variables with either the `${parameterName}` representation or the `{parameterName}` representation.

-* The Custom Commands feature doesn't support template composition and expansion, because you never edit the *.lg* file directly. You edit only the responses of automatically created templates.

-* The Custom Commands feature doesn't support custom functions that LG injects. Predefined functions are supported.

-* The Custom Commands feature doesn't support options, such as `strict`, `replaceNull`, and `lineBreakStyle`.

-### Add template responses to a TurnOnOff command

-Modify the `TurnOnOff` command to add a new parameter. Use the following configuration.

-| Setting | Suggested value |

-| | |

-| **Name** | `SubjectContext` |

-| **Required** | Unselected |

-| **Type** | **String** |

-| **Default value** | `all` |

-| **Configuration** | **Accept predefined input values from internal catalog** |

-| **Predefined input values** | `room`, `bathroom`, `all`|

-#### Modify a completion rule

-Edit the **Actions** section of the existing completion rule **ConfirmationResponse**. In the **Edit action** window, switch to **Template Editor**. Then replace the text with the following example.

-```

- - Ok, turning all the lights {OnOff}

- - Ok, turning {OnOff} the {SubjectContext} {SubjectDevice}

- - Ok, turning the {SubjectDevice} {OnOff}

- - Done, turning {OnOff} the {SubjectDevice}

-```

-Train and test your application by using the following input and output. Notice the variation of responses. The variation is created by multiple alternatives of the template value and also by use of adaptive expressions.

-* Input: *turn on the tv*

-* Output: Ok, turning on the tv

-* Input: *turn on the tv*

-* Output: Done, turned on the tv

-* Input: *turn off the lights*

-* Output: Ok, turning all the lights off

-* Input: *turn off room lights*

-* Output: Ok, turning off the room lights

-## Use a custom voice

-Another way to customize Custom Commands responses is to select an output voice. Use the following steps to switch the default voice to a custom voice:

-1. In your Custom Commands application, in the pane on the left, select **Settings**.

-1. In the middle pane, select **Custom voice**.

-1. In the table, select a custom voice or public voice.

-1. Select **Save**.

-> [!div class="mx-imgBorder"]

-> 

-> [!NOTE]

-> For public voices, neural types are available only for specific regions. For more information, see [Speech service supported regions](./regions.md#speech-service).

->

-> You can create custom voices on the **Custom voice** project page. For more information, see [Get started with custom voice](./professional-voice-create-project.md).

-Now the application responds in the selected voice, instead of the default voice.

-## Next steps

-* Learn how to [integrate your Custom Commands application](how-to-custom-commands-setup-speech-sdk.md) with a client app by using the Speech SDK.

-* [Set up continuous deployment](how-to-custom-commands-deploy-cicd.md) for your Custom Commands application by using Azure DevOps.

- * [Tutorial: Create a custom commands application with simple voice commands](./how-to-develop-custom-commands-application.md)

-| End-to-end keyword recognition with speech to text | Best suited for products that use a customized on-device keyword model from custom keyword with keyword verification and speech to text. This scenario is the most common. | <ul><li>[Voice assistant sample code](https://github.com/Azure-Samples/Cognitive-Services-Voice-Assistant)</li><li>[Tutorial: Voice enable your assistant built using Azure AI Bot Service with the C# Speech SDK](./tutorial-voice-enable-your-bot-speech-sdk.md)</li><li>[Tutorial: Create a custom commands application with simple voice commands](./how-to-develop-custom-commands-application.md)</li></ul> |

-description: In this quickstart, you create and test a basic custom commands application in Speech Studio.

-# Quickstart: Create a voice assistant with custom commands

-In this quickstart, you create and test a basic custom commands application using Speech Studio. You can also access this application from a Windows client app.

-## Region Availability

-At this time, custom commands support speech resources created in regions that have [voice assistant capabilities](./regions.md#voice-assistants).

-## Prerequisites

-> [!div class="checklist"]

-> * <a href="https://portal.azure.com/#create/Microsoft.CognitiveServicesSpeechServices" target="_blank">Create a Speech resource in a region that supports custom commands.</a> Refer to the **Region Availability** section above for list of supported regions.

-> * Download the sample [Smart Room Lite](https://aka.ms/speech/cc-quickstart) json file.

-> * Download the latest version of [Windows Voice Assistant Client](https://aka.ms/speech/va-samples-wvac).

-## Go to the Speech Studio for custom commands

-1. In a web browser, go to [Speech Studio](https://aka.ms/speechstudio/customcommands).

-1. Enter your credentials to sign in to the portal.

- The default view is your list of Speech resources.

- > [!NOTE]

- > If you don't see the select resource page, you can navigate there by choosing "Resource" from the settings menu on the top bar.

-1. Select your Speech resource, and then select **Go to Studio**.

-1. Select **Custom commands**.

- The default view is a list of the custom commands applications you have under your selected resource.

-## Import an existing application as a new custom commands project

-1. Select **New project** to create a project.

-1. In the **Name** box, enter project name as `Smart-Room-Lite` (or something else of your choice).

-1. In the **Language** list, select **English (United States)**.

-1. Select **Browse files** and in the browse window, select the **SmartRoomLite.json** file.

- > [!div class="mx-imgBorder"]

- > 

-1. In the **LUIS authoring resource** list, select an authoring resource. If there are no valid authoring resources, create one by selecting **Create new LUIS authoring resource**.

-

- 1. In the **Resource Name** box, enter the name of the resource.

- 1. In the **Resource Group** list, select a resource group.

- 1. In the **Location** list, select a location.

- 1. In the **Pricing Tier** list, select a tier.

-

-

- > [!NOTE]

- > You can create resource groups by entering the desired resource group name into the "Resource Group" field. The resource group will be created when **Create** is selected.

-1. Next, select **Create** to create your project.

-1. After the project is created, select your project.

-You should now see overview of your new custom commands application.

-## Try out some voice commands

-1. Select **Train** at the top of the right pane.

-1. Once training is completed, select **Test** and try out the following utterances:

- - Turn on the tv

- - Set the temperature to 80 degrees

- - Turn it off

- - The tv

- - Set an alarm for 5 PM

-## Integrate custom commands application in an assistant

-Before you can access this application from outside Speech Studio, you need to publish the application. For publishing an application, you need to configure prediction LUIS resource.

-### Update prediction LUIS resource

-1. Select **Settings** in the left pane and select **LUIS resources** in the middle pane.

-1. Select a prediction resource, or create one by selecting **Create new resource**.

-1. Select **Save**.

-

- > [!div class="mx-imgBorder"]

- > 

-> [!NOTE]

-> Because the authoring resource supports only 1,000 prediction endpoint requests per month, you will mandatorily need to set a LUIS prediction resource before publishing your custom commands application.

-### Publish the application

-Select **Publish** on top of the right pane. Once publish completes, a new window appears. Note down the **Application ID** and **Speech resource key** value from it. You need these two values to be able to access the application from outside Speech Studio.

-Alternatively, you can also get these values by selecting **Settings** > **General** section.

-### Access application from client

-In the scope of this article, we're using the Windows Voice Assistant client you downloaded as part of the prerequisites. Unzip the folder.

-1. Launch **VoiceAssistantClient.exe**.

-1. Create a new publish profile and enter value for **Connection Profile**. In the **General Settings** section, enter values **Subscription Key** (this is same as the **Speech resource key** value you saved when publishing the application), **Subscription key region** and **custom commands app ID**.

- > [!div class="mx-imgBorder"]

- > 

-1. Select **Save and Apply Profile**.

-1. Now try out the following inputs via speech/text

- > [!div class="mx-imgBorder"]

- > 

-> [!TIP]

-> You can select entries in **Activity Log** to inspect the raw responses being sent from the custom commands service.

-## Next steps

-In this article, you used an existing application. Next, in the [how-to sections](./how-to-develop-custom-commands-application.md), you learn how to design, develop, debug, test and integrate a custom commands application from scratch.

-In the meantime, when you use Custom Command, you can manage your subscription with your own encryption keys. Customer-managed keys (CMK), also known as bring your own key (BYOK), offer greater flexibility to create, rotate, disable, and revoke access controls. You can also audit the encryption keys used to protect your data. For more information about Custom Command and CMK, see [Custom Commands encryption of data at rest](custom-commands-encryption-of-data-at-rest.md).

-* [Custom Commands](https://aka.ms/speechstudio/customcommands): Easily build rich, voice-command apps that are optimized for voice-first interaction experiences. Custom Commands provides a code-free authoring experience in Speech Studio, an automatic hosting model, and relatively lower complexity. The feature helps you focus on building the best solution for your voice-command scenarios. For more information, see the [Develop Custom Commands applications](how-to-develop-custom-commands-application.md) guide. Also see [Integrate with a client application by using the Speech SDK](how-to-custom-commands-setup-speech-sdk.md).

-As another example, you can [create a connection](../how-to/connections-add.md) to an Azure AI Search resource. The connection can then be used by prompt flow tools such as the Vector DB Lookup tool.

-Azure OpenAI service offers a diverse set of models with different capabilities and price points. When you deploy Azure OpenAI models in Azure AI Studio, you can consume the deployments, using prompt flow or another tool. Model availability varies by region. To learn more about the details of each model see [Azure OpenAI Service models](../../ai-services/openai/concepts/models.md).

-The following example uses output from an activity called `Get Twitter Connection` to populate a hashtable.

-@{'ApiKey'=$ActivityOutput['Get Twitter Connection'].ConsumerAPIKey;

- 'ApiSecret'=$ActivityOutput['Get Twitter Connection'].ConsumerAPISecret;

- 'AccessToken'=$ActivityOutput['Get Twitter Connection'].AccessToken;

- 'AccessTokenSecret'=$ActivityOutput['Get Twitter Connection'].AccessTokenSecret}

-Change Tracking and Inventory makes use of [Microsoft Defender for Cloud File Integrity Monitoring (FIM)](../../security-center/security-center-file-integrity-monitoring.md) to examine operating system and application files, and Windows Registry. While FIM monitors those entities, Change Tracking and Inventory natively tracks:

-docker run --name mssql-server -e 'ACCEPT_EULA=Y' -e "SA_PASSWORD=$pw" -e "MSSQL_PID=$edition" -p ${port}:1433 -d mcr.microsoft.com/mssql/server:$tag

-| [Azure Monitor managed service for Prometheus](../essentials/prometheus-metrics-overview.md) | [Prometheus](https://prometheus.io) is a cloud-native metrics solution from the Cloud Native Compute Foundation and the most common tool used for collecting and analyzing metric data from Kubernetes clusters. Azure Monitor managed service for Prometheus is a fully managed solution that's compatible with the Prometheus query language (PromQL) and Prometheus alerts and integrates with Azure Managed Grafana for visualization. This service supports your investment in open source tools without the complexity of managing your own Prometheus environment. |

-| [Azure Managed Grafana](../../managed-grafan) | Fully managed implementation of [Grafana](https://grafana.com/), which is an open-source data visualization platform commonly used to present Prometheus and other data. Multiple predefined Grafana dashboards are available for monitoring Kubernetes and full-stack troubleshooting. You may choose to use Grafana for performance monitoring of your cluster, or you can use Container insights by |

-> You can switch a table's plan once a week.

-# [Portal](#tab/portal-1)

-# [API](#tab/api-1)

-> [!IMPORTANT]

-> Use the bearer token for authentication. Learn more about [using bearer tokens](https://social.technet.microsoft.com/wiki/contents/articles/51140.azure-rest-management-api-the-quickest-way-to-get-your-bearer-token.aspx).

-|Name | Type | Description |

-| | | |

-|properties.plan | string | The table plan. Possible values are `Analytics` and `Basic`.|

-**Example**

-Use this request body to change to Basic logs:

-```http

-{

- "properties": {

- "plan": "Basic"

-}

-```

-Use this request body to change to Analytics Logs:

-```http

-{

- "properties": {

- "plan": "Analytics"

-}

-```

-This sample is the response for a table changed to Basic logs:

-Status code: 200

-```http

-{

- "properties": {

- "retentionInDays": 30,

- "totalRetentionInDays": 30,

- "archiveRetentionInDays": 22,

- "plan": "Basic",

- "lastPlanModifiedDate": "2022-01-01T14:34:04.37",

- "schema": {...}

- },

- "id": "subscriptions/ContosoSID/resourcegroups/ContosoRG/providers/Microsoft.OperationalInsights/workspaces/ContosoWorkspace",

- "name": "ContainerLogV2"

-}

-```

-# [CLI](#tab/cli-1)

-For example:

-# [PowerShell](#tab/azure-powershell)

-Update-AzOperationalInsightsTable -ResourceGroupName RG-NAME -WorkspaceName WORKSPACE-NAME -Plan Basic|Analytics

-# Use diagnostic logs to monitor SignalR Service

- kubectl create secret generic mssql --from-literal=SA_PASSWORD="MyC0m9l&xP@ssw0rd" -n <namespace name>

- - name: SA_PASSWORD

- key: SA_PASSWORD

- * `name: SA_PASSWORD`: Configures the container image to set the SA password, as defined in this section.

- key: SA_PASSWORD

-## Disconnect an Azure NetApp Files-based datastore from your private cloud

-You can use the instructions provided to disconnect an Azure NetApp Files-based datastore using either Azure portal or Azure CLI. There's no maintenance window required for this operation. The disconnect action only disconnects the Azure NetApp Files volume as a datastore, it doesn't delete the data or the Azure NetApp Files volume.

-**Disconnect an Azure NetApp Files datastore using the Azure Portal**

-1. Select the datastore you want to disconnect from.

-1. Right-click on the datastore and select **disconnect**.

-**Disconnect an Azure NetApp Files datastore using Azure CLI**

- `az vmware datastore delete --name ANFDatastore1 --resource-group MyResourceGroup --cluster Cluster-1 --private-cloud MyPrivateCloud`

-Under rare circumstances, Azure VMware Solution might not correctly show the Azure NetApp Files volumes used as datastores after changing the service level for the Azure NetApp Files volume. If the necessary metadata updates could not complete successfully, check the activity log for the Azure NetApp Files volume for a message about Datastore metadata update with a status of failure. To correct the mismatch, rerun the datastore creation in the Azure CLI for the existing datastore with the new Resource ID for the Azure NetApp Files volume:

-<!--

-33## IS ThE FIRST SENTENCE REQUIRED?

-> The parameters for datastore **name**, **resource-group**, **cluster**, and **private-cloud** (SDDC) must be **exactly the same as those on the existing datastore in the private cloud**. The **volume-id** is the updated Resource ID of the Azure NetApp Files volume after the service level change.

-# Event handler in Azure Web PubSub service

-The Web PubSub service delivers client events to the upstream webhook using the [CloudEvents HTTP protocol](https://github.com/cloudevents/spec/blob/v1.0.1/http-protocol-binding.md).

-For every event, the service formulates an HTTP POST request to the registered upstream endpoint and expects an HTTP response.

-The data sending from the service to the server is always in CloudEvents `binary` format.

-## Upstream and Validation

-When you configure the webhook endpoint, the URL can include the `{event}` parameter to define a URL template. The service calculates the value of the webhook URL dynamically when the client request comes in. For example, when a request `/client/hubs/chat` comes in, with a configured event handler URL pattern `http://host.com/api/{event}` for hub `chat`, when the client connects, it will first POST to this URL: `http://host.com/api/connect`. The `{event}` parameter can be useful when a PubSub WebSocket client sends custom events, that the event handler helps dispatch different events to different upstream endpoints. The `{event}` parameter isn't allowed in the URL domain name.

-When setting up the event handler webhook through Azure portal or CLI, the service follows the [CloudEvents Abuse Protection](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md#4-abuse-protection) to validate the upstream webhook. Every registered upstream webhook URL will be validated by this mechanism. The `WebHook-Request-Origin` request header is set to the service domain name `xxx.webpubsub.azure.com`, and it expects the response to have a header `WebHook-Allowed-Origin` to contain this domain name or `*`.

-When doing the validation, the `{event}` parameter is resolved to `validate`. For example, when trying to set the URL to `http://host.com/api/{event}`, the service will try to **OPTIONS** a request to `http://host.com/api/validate`. And only when the response is valid, the configuration can be set successfully.

-For now, we don't support [WebHook-Request-Rate](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md#414-webhook-request-rate) and [WebHook-Request-Callback](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md#413-webhook-request-callback).

-## Authentication between service and webhook