Add input hints to messages in the v3 JavaScript SDK

  • Article

APPLIES TO: SDK v3

By specifying an input hint for a message, you can indicate whether your bot is accepting, expecting, or ignoring user input after the message is delivered to the client. For many channels, this enables clients to set the state of user input controls accordingly. For example, if a message's input hint indicates that the bot is ignoring user input, the client may close the microphone and disable the input box to prevent the user from providing input.

Accepting input

To indicate that your bot is passively ready for input but is not awaiting a response from the user, set the message's input hint to builder.InputHint.acceptingInput. On many channels, this will cause the client's input box to be enabled and microphone to be closed, but still accessible to the user. For example, Cortana will open the microphone to accept input from the user if the user holds down the microphone button. The following code example creates a message that indicates the bot is accepting user input.

var msg = new builder.Message(session)
    .speak('This is the text that will be spoken.')
    .inputHint(builder.InputHint.acceptingInput);
session.send(msg).endDialog();

Expecting input

To indicate that your bot is awaiting a response from the user, set the message's input hint to builder.InputHint.expectingInput. On many channels, this will cause the client's input box to be enabled and microphone to be open. The following code example creates a prompt that indicates the bot is expecting user input.

builder.Prompts.text(session, 'This is the text that will be displayed.', {                                    
    speak: 'This is the text that will be spoken initially.',
    retrySpeak: 'This is the text that is spoken after waiting a while for user input.',  
    inputHint: builder.InputHint.expectingInput
});

Ignoring input

To indicate that your bot is not ready to receive input from the user, set the message's input hint to builder.InputHint.ignoringInput. On many channels, this will cause the client's input box to be disabled and microphone to be closed. The following code example uses the session.say() method to send a message that indicates the bot is ignoring user input.

session.say('Please hold while I calculate a response. Thanks!', 
    'Please hold while I calculate a response. Thanks!', 
    { inputHint: builder.InputHint.ignoringInput }
);

Default values for input hint

If you do not set the input hint for a message, the Bot Framework SDK will automatically set it for you by using this logic:

  • If your bot sends a prompt, the input hint for the message will specify that your bot is expecting input.
  • If your bot sends single message, the input hint for the message will specify that your bot is accepting input.
  • If your bot sends a series of consecutive messages, the input hint for all but the final message in the series will specify that your bot is ignoring input, and the input hint for the final message in the series will specify that your bot is accepting input.

Additional resources