Web Chat中带Speak属性的Adaptive Card语音功能技术咨询

阿华AIGC实验室

2026-5-20

Hey there! Let's walk through everything you need to know about getting the Speak property of your Adaptive Card working properly in Web Chat:

Web Chat中Adaptive Card语音功能核心技术指南

1. 基础支持前提

Web Chat原生支持Adaptive Card的Speak属性，但必须先配置语音合成（TTS）能力才能触发播报。默认状态下Web Chat不会自动启用语音功能，你需要在初始化时明确配置相关模块。

2. `Speak`属性的语法规范

你代码里使用SSML格式的<s>标签是完全正确的——Adaptive Card的Speak属性支持标准SSML（语音合成标记语言），用来控制语音的停顿、语调、分段等细节。需要注意：

确保SSML标签闭合完整，使用Web Chat支持的元素（比如<s>分段、<break>停顿、<prosody>调节语速音量等）
如果不需要复杂控制，直接传入纯文本字符串也能触发播报，但SSML能提供更自然的语音体验

3. Web Chat语音功能配置步骤

要让Speak内容正常播报，你需要在Web Chat初始化代码中做如下配置：

选择语音合成方案：可以用浏览器原生的SpeechSynthesis API，也可以接入Azure认知服务等云语音服务
将语音合成实例传入Web Chat配置，确保卡片渲染时能触发播报

下面是一个基于浏览器原生TTS的简单配置示例：

// 创建浏览器原生语音合成实例
const speechPonyfill = window.WebChat.createBrowserSpeechSynthesisPonyfillFactory();

// 初始化Web Chat并启用语音
window.WebChat.renderWebChat({
  directLine: window.WebChat.createDirectLine({ token: 'YOUR_DIRECT_LINE_TOKEN' }),
  speechSynthesis: speechPonyfill.speechSynthesis
}, document.getElementById('webchat'));

4. 常见问题排查

语音无播报：检查浏览器是否允许网页访问扬声器权限；验证Speak的SSML格式是否合规（可以先替换为纯文本测试）；确认Web Chat的语音配置是否生效
播报时机自定义：默认Web Chat会在卡片加载完成后自动播报，若需要用户触发（比如点击按钮后播报），可以通过Adaptive Card的Action事件，结合Web Chat的事件回调手动调用语音合成API
多语言支持：如果需要播报非默认语言，要确保语音合成服务支持目标语言，同时在SSML中用<lang>标签指定语言，或在语音配置中设置对应语言参数