Update a command from a web endpoint

Important

Custom Commands will be retired on April 30th 2026. As of October 30th 2023 you can't create new Custom Commands applications in Speech Studio. Related to this change, LUIS will be retired on October 1st 2025. As of April 1st 2023 you can't create new LUIS resources.

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

• A previously created Custom Commands app

Create an Azure function

For this example, you need an HTTP-triggered Azure function that supports the following input (or a subset of this input):

{
  "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:

{
  "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.

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

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.
2. Add just one example sentence with the value increment.
3. Add a new parameter called Counter (same name as specified in the Azure function) of type Number with a default value of 0.
4. Add a new web endpoint called IncrementEndpoint with the URL of your Azure function, with Remote updates set to Enabled.

   

5. Create a new interaction rule called IncrementRule and add a Call web endpoint action.

   

6. 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.

   

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

Test it

1. Save and train your app.
2. Select Test.
3. Send increment a few times (which is the example sentence for the IncrementCounter command).

   

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

Next steps

Enable a CI/CD process for your Custom Commands application