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

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:

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.