Add speech to messages in the v3 C# SDK

  • Article

APPLIES TO: SDK v3

If you are building a bot for a speech-enabled channel such as Cortana, you can construct messages that specify the text to be spoken by your bot. You can also attempt to influence the state of the client's microphone by specifying an input hint to indicate whether your bot is accepting, expecting, or ignoring user input.

Specify text to be spoken by your bot

Using the Bot Framework SDK for .NET, there are multiple ways to specify the text to be spoken by your bot on a speech-enabled channel. You can set the Speak property of the message, call the IDialogContext.SayAsync() method, or specify prompt options speak and retrySpeak when sending a message using a built-in prompt.

IMessageActivity.Speak

If you are creating a message and setting its individual properties, you can set the Speak property of the message to specify the text to be spoken by your bot. The following code example creates a message that specifies text to be displayed and text to be spoken and indicates that the bot is accepting user input.

Activity reply = activity.CreateReply("This is the text that will be displayed."); 
reply.Speak = "This is the text that will be spoken.";
reply.InputHint = InputHints.AcceptingInput;
await connector.Conversations.ReplyToActivityAsync(reply);

IDialogContext.SayAsync()

If you are using dialogs, you can call the SayAsync() method to create and send a message that specifies the text to be spoken, in addition to the text to be displayed and other options. The following code example creates a message that specifies text to be displayed and text to be spoken.

await context.SayAsync(text: "Thank you for your order!", speak: "Thank you for your order!");

Prompt options

Using any of the built-in prompts, you can set the options speak and retrySpeak to specify the text to be spoken by your bot. The following code example creates a prompt that specifies text to be displayed, text to be spoken initially, and text to be spoken after waiting a while for user input. It uses SSML formatting to indicate that the word "sure" should be spoken with a moderate amount of emphasis.

PromptDialog.Confirm(context, AfterResetAsync, 
    new PromptOptions<string>(prompt: "Are you sure that you want to cancel this transaction?", 
        speak: "Are you <emphasis level=\"moderate\">sure</emphasis> that you want to cancel this transaction?",
        retrySpeak: "Are you <emphasis level=\"moderate\">sure</emphasis> that you want to cancel this transaction?"));

Speech Synthesis Markup Language (SSML)

To specify text to be spoken by your bot, you can give it a string that is formatted as Speech Synthesis Markup Language (SSML). SSML is an XML-based markup language (and therefore must be valid XML) that enables you to control various characteristics of your bot's speech such as voice, rate, volume, pronunciation, pitch, and more. For details about SSML, see Speech Synthesis Markup Language Reference.

When providing the SSML formatted string, the outer SSML wrapper element may be omitted.

Input hints

When you send a message on a speech-enabled channel, you can attempt to influence the state of the client's microphone by also including an input hint to indicate whether your bot is accepting, expecting, or ignoring user input. For more information, see Add input hints to messages.

Sample code

For a complete sample that shows how to create a speech-enabled bot using the Bot Framework SDK for .NET, see the Roller Skill sample in GitHub.

Additional resources