1. 项目概述从“按0转人工”说起如果你接过任何一家银行、运营商或者大公司的客服电话那你一定对IVR不陌生。就是那个“普通话服务请按1For English press 2...业务查询请按3人工服务请按0”的语音导航菜单。在通信领域IVRInteractive Voice Response交互式语音应答是连接用户与后台服务的第一个也是最重要的门户。它的体验好坏直接决定了用户是能顺利解决问题还是在一通乱按后愤怒地挂断电话。FreeSWITCH作为一款强大且开源软交换平台其内置的XML拨号计划配合Lua、JavaScript等脚本语言为我们搭建灵活、高效的IVR系统提供了绝佳的工具箱。但很多刚接触的朋友面对FreeSWITCH繁杂的配置项和文档常常感到无从下手觉得配置一个IVR菜单是件很复杂的事情。其实核心逻辑远比想象中简单。今天我就以一个最常见的三层语音菜单为例带你实战一遍。目标很明确在5分钟内从零开始在FreeSWITCH上配置并上线一个可用的IVR语音菜单并且用Lua脚本实现一些动态逻辑。我们不止讲配置更会拆解背后的“为什么”比如为什么选XML而不是纯脚本菜单超时了怎么办如何让脚本和FreeSWITCH高效交互这些都是实战中一定会踩到的坑。2. 核心需求与方案设计拆解在动手写一行配置之前我们必须先想清楚这个IVR要干什么。一个设计良好的IVR绝不是功能的简单堆砌它需要引导用户、分流业务、并收集必要信息。2.1 业务场景与用户路径分析假设我们要为一个“虚拟技术支持中心”设计IVR。核心需求如下欢迎与主菜单播放欢迎语并提供三个明确选项。业务分流选项1账户查询如余额、套餐。选项2故障报修需引导用户描述问题。选项3转接人工坐席。容错处理用户按键错误、超时不按键、直接要求转人工等情况都需要有明确的处理路径不能让用户陷入“死循环”。动态性某些菜单提示音可能需要根据时间如工作时间/非工作时间或主叫号码动态变化。基于此我们可以规划出清晰的用户路径图虽然不用mermaid但心里要有数来电 - 播放欢迎语 - 播放主菜单1.账户2.报修3.人工- 等待用户按键 - 按键‘1’ - 进入“账户查询”子流程可进一步细分或直接播报信息 - 按键‘2’ - 进入“故障报修”子流程播放提示开始录音或转工单 - 按键‘3’ - 直接转接到人工坐席队列 - 按键超时/错误 - 播放错误提示并允许重试或直接转人工2.2 技术方案选型XML Dialplan Lua 脚本FreeSWITCH实现IVR主要有两种主流方式纯XML Dialplan和XML Dialplan 内嵌脚本如Lua。纯XML Dialplan所有逻辑菜单定义、按键处理、跳转都用FreeSWITCH的XML标签来描述。优点是结构清晰、执行效率高适合逻辑固定、简单的菜单。缺点是灵活性差难以实现复杂的业务判断比如根据数据库查询结果动态播放语音。XML Lua脚本用XML定义菜单的“骨架”如菜单层级、超时时间、最大失败次数而将复杂的业务逻辑如数据库查询、动态TTS、外部API调用交给Lua脚本来处理。这是本次实战采用的方案因为它兼顾了配置的简洁性和业务的灵活性。为什么选择Lua而不是其他语言FreeSWITCH内嵌了Lua虚拟机Lua脚本可以直接调用丰富的FreeSWITCH API如session:sayPhrase,session:recordFile交互延迟极低无需进程间通信。对于Python、JavaScript等虽然也可以通过ESLEvent Socket Library外部控制但实时性和复杂度上不如内嵌Lua直接。对于IVR这种强实时、轻量级逻辑的场景Lua是“原生且最佳”的选择。我们的混合方案设计如下XML负责“流程控制”定义menu设定max_attempts最大尝试次数、timeout超时时间、inter-digit-timeout按键间隔超时等参数并指定每个按键对应的action执行的动作通常是执行一个Lua脚本。Lua负责“业务实现”在脚本中我们可以自由地访问呼叫变量如主叫号码caller_id_number、播放语音文件、进行逻辑判断、读写数据库最后决定下一步将呼叫路由到哪里如session:transfer到某个分机或队列。这种分工让XML配置保持清爽而所有“脏活累活”和复杂逻辑都封装在了Lua脚本里维护和升级都非常方便。3. 环境准备与核心配置解析在开始编写我们的IVR之前需要确保FreeSWITCH已经正确安装并运行。这里假设你使用的是典型的Linux环境并且FreeSWITCH已通过源码或包管理器安装完毕。3.1 语音文件准备与存放规范IVR离不开语音提示。我们需要录制或生成对应的语音文件如.wav或.mp3格式。为了管理清晰建议在FreeSWITCH的声音文件目录下建立专属文件夹。FreeSWITCH默认的声音文件路径通常是/usr/local/freeswitch/sounds/源码安装或/var/lib/freeswitch/sounds/包安装。我们在此目录下创建一个子目录来存放本次IVR的语音文件。# 进入声音文件目录 cd /usr/local/freeswitch/sounds/ # 创建ivr目录及子目录按语言分类是良好实践 mkdir -p ivr/zh/cn接下来准备以下语音文件并放入ivr/zh/cn/目录welcome.wav- “欢迎致电虚拟技术支持中心。”main_menu.wav- “账户查询请按1故障报修请按2人工服务请按3。”account_enter_id.wav- “请输入您的账户编号以井号键结束。”account_balance.wav- “您的当前余额是100元。” 此为示例实际应由脚本动态合成repair_prompt.wav- “请简要描述您遇到的问题描述完毕后按井号键结束。”transferring.wav- “正在为您转接人工坐席请稍候。”invalid_option.wav- “输入错误请重新输入。”goodbye.wav- “感谢您的来电再见。”实操心得语音文件制作可以使用文本转语音TTS工具生成如微软Azure、谷歌Cloud TTS或者一些开源工具。关键点在于音频格式必须是FreeSWITCH支持的编解码器如PCM 16bit 8kHz的WAV文件兼容性最好并且文件名不要包含空格或中文用英文或拼音命名。将文件放入正确目录后记得修改文件权限确保FreeSWITCH的运行用户通常是freeswitch或daemon有读取权限。3.2 拨号计划Dialplan配置详解拨号计划是FreeSWITCH的路由核心。我们需要编辑XML配置文件通常是/usr/local/freeswitch/conf/dialplan/default.xml或在default/目录下新建一个XML文件。这里我们在default.xml中增加一个针对特定号码比如8888的IVR入口。!-- 在 /usr/local/freeswitch/conf/dialplan/default.xml 的 context namedefault 部分添加 -- extension nameivr_demo condition fielddestination_number expression^8888$ action applicationanswer/ action applicationsleep data1000/ !-- 等待1秒稳定通道 -- !-- 执行主IVR菜单的Lua脚本 -- action applicationlua dataivr_main.lua/ /condition /extension配置解析extension定义一个路由扩展。condition路由条件。这里使用正则表达式^8888$匹配被叫号码8888。action application”answer”应答来电。action application”sleep”暂停1000毫秒。这是一个非常实用的小技巧在应答后稍作等待可以让一些早期媒体如回铃音完全停止确保后续播放的语音清晰避免开头被“吃掉”。action application”lua”最关键的一步调用我们的主Lua脚本ivr_main.lua。FreeSWITCH会在其脚本目录通常是/usr/local/freeswitch/scripts/中寻找这个文件。至此所有来电到8888的呼叫都会被路由到ivr_main.lua脚本执行。真正的IVR逻辑将在Lua脚本中构建。4. Lua脚本实战构建智能语音菜单Lua脚本是IVR的大脑。我们将创建一个结构清晰的脚本实现之前设计的完整流程。4.1 脚本框架与会话初始化首先在FreeSWITCH的脚本目录创建文件ivr_main.lua。-- ivr_main.lua -- 虚拟技术支持中心主IVR脚本 -- 1. 获取当前会话对象 session freeswitch.Session if not session then freeswitch.consoleLog(ERR, 无法获取会话对象脚本非在呼叫上下文中执行。\n) return end -- 2. 定义常用变量和函数 local sound_path ivr/zh/cn/ -- 语音文件基础路径 local max_failures 3 -- 最大允许输入错误次数 local failure_count 0 -- 当前错误计数 -- 辅助函数播放语音文件 local function play_prompt(filename) session:streamFile(sound_path .. filename) end -- 辅助函数播放TTS如需动态内容 local function play_tts(text) session:speak(text) -- 需要配置TTS模块如mod_flite end freeswitch.consoleLog(NOTICE, IVR脚本启动主叫号码: .. session:getVariable(caller_id_number) .. \n) -- 3. 播放欢迎语 play_prompt(welcome.wav)代码解析与避坑指南session对象是与当前电话呼叫交互的核心。所有播放、收号、转接操作都通过它进行。sound_path定义了语音文件的相对路径。FreeSWITCH会在配置的sound_prefix通常是sounds目录下寻找。使用相对路径便于移植。play_prompt函数封装了session:streamFile这是播放预录制音频文件的标准方法。重要提示session:speak用于文本转语音但前提是安装了TTS模块如mod_flite、mod_tts_commandline并正确配置。如果没配置调用它会报错。对于稳定性要求高的生产环境建议优先使用预录制的音频文件TTS作为动态内容如读金额、日期的补充。在脚本开头用freeswitch.consoleLog输出日志是调试的黄金法则。通过fs_cli命令行工具执行sofia global loglevel 6提高日志级别再tail -f /usr/local/freeswitch/log/freeswitch.log就能实时看到脚本的执行轨迹和变量值。4.2 实现多层菜单与收号逻辑接下来我们实现主菜单的播放和收号逻辑。这里会用到session:playAndGetDigits这个关键API。-- 4. 主菜单循环 while failure_count max_failures do play_prompt(main_menu.wav) -- 收号参数详解 -- min: 最少收号位数1 -- max: 最多收号位数1我们只收1位 -- tries: 本菜单内最大尝试次数3 -- timeout: 首次等待按键超时毫秒50005秒 -- inter-digit-timeout: 按键间隔超时毫秒20002秒 -- terminators: 结束符这里用‘#’但因为我们只收1位收到任意有效键即结束 -- regex: 输入验证正则表达式^[123]$ 只允许1,2,3 -- file: 要播放的提示音文件已经在上面的play_prompt播放了这里填nil -- invalid_file: 输入无效时播放的提示音 local digit session:playAndGetDigits(1, 1, 3, 5000, #, ivr/zh/cn/invalid_option.wav, nil, ^[123]$) -- 判断收号结果 if digit then -- 超时未按键 session:speak(您未做出选择即将挂断。) play_prompt(goodbye.wav) session:hangup() return elseif digit 1 then -- 进入账户查询子流程 handle_account_query() return -- 子流程结束后本通呼叫结束或转走主脚本退出 elseif digit 2 then -- 进入故障报修子流程 handle_repair_request() return elseif digit 3 then -- 转接人工坐席 play_prompt(transferring.wav) -- 这里假设人工坐席分机号为1000 session:transfer(1000, XML, default) return else -- 输入了非1/2/3的字符虽然正则已过滤但此处是额外保障 failure_count failure_count 1 if failure_count max_failures then session:speak(输入错误次数过多即将转接人工坐席。) session:transfer(1000, XML, default) return end end end -- 如果循环退出失败次数超限默认转人工 session:speak(输入错误次数过多即将转接人工坐席。) session:transfer(1000, XML, default)核心APIplayAndGetDigits深度解析 这个函数是IVR收号的瑞士军刀参数虽多但每个都至关重要min/max定义了输入数字的长度范围。对于单层菜单通常设为1。如果需要输入工单号如6位则max设为6。tries当前这轮提示音播放后允许用户输入错误不符合regex的最大次数。注意它和整个菜单的失败次数我们用的failure_count是两回事。这里设为3意味着用户连续输错3次本次playAndGetDigits调用会返回空字符串。timeout等待用户按下第一个数字的超时时间。设置太短用户反应不过来太长则影响效率。5秒是一个比较通用的起始值。inter-digit-timeout在输入多位数字时等待下一个数字的超时。本例中只收1位此参数不生效但必须填写。regex输入验证的利器。^[123]$确保输入只能是1、2或3。你可以用它做复杂验证比如^[0-9]{6}$验证6位数字。invalid_file输入不符合regex时立即播放的提示音。这是一个即时反馈能有效引导用户。实操心得超时与重试策略playAndGetDigits的tries参数和脚本中自己维护的failure_count共同构成了两级容错。前者处理单次输入的瞬时错误后者处理多次选择错误的累积。这种设计让体验更友好用户按错一次马上听到“输入错误”并重听菜单连续几次都进错菜单则直接转人工避免用户陷入绝望。务必在脚本开头或配置文件中定义好这些阈值方便后续调整。4.3 实现动态业务子流程现在我们来填充两个业务子流程的函数handle_account_query和handle_repair_request。这里会展示Lua脚本如何实现动态逻辑。-- 账户查询子流程 function handle_account_query() play_prompt(account_enter_id.wav) -- 收取6位账户ID local account_id session:playAndGetDigits(6, 6, 2, 8000, #, sound_path .. invalid_option.wav, nil, ^[0-9]{6}$) if account_id or string.len(account_id) ~ 6 then session:speak(账户ID输入无效。) play_prompt(goodbye.wav) session:hangup() return end freeswitch.consoleLog(NOTICE, 用户查询账户ID: .. account_id .. \n) -- 这里是动态业务逻辑的核心 -- 模拟根据账户ID查询数据库生产环境应使用luasql等库连接真实数据库 local balance 一百二十 -- 假设从数据库查询到的余额是120 -- 可以在这里加入更复杂的逻辑比如判断账户状态、套餐信息等 -- 动态播放查询结果 session:speak(账户 .. account_id .. 的当前余额是 .. balance .. 元。) -- 可以继续播放更多菜单这里简单挂断 play_prompt(goodbye.wav) session:hangup() end -- 故障报修子流程 function handle_repair_request() play_prompt(repair_prompt.wav) -- 设置录音参数 local caller_id session:getVariable(caller_id_number) or unknown local timestamp os.time() local record_filename /tmp/repair_ .. caller_id .. _ .. timestamp .. .wav -- 开始录音等待#号键结束 -- 参数最大录音时长毫秒静音阈值静音超时毫秒结束按键 local result session:recordFile(record_filename, 300000, 200, 3000, #) if result then session:speak(问题已记录我们的工程师将尽快处理。) -- 在实际应用中这里可以触发一个工单系统API将录音文件名和主叫号码等信息发送过去 freeswitch.consoleLog(NOTICE, 故障录音已保存至: .. record_filename .. \n) -- 模拟调用外部API创建工单 -- local http require(socket.http) -- local response http.request(http://your-ticket-system/api/create?file .. record_filename .. caller .. caller_id) else session:speak(录音失败。) end play_prompt(goodbye.wav) session:hangup() end动态逻辑与外部集成详解数据库查询在handle_account_query中我们模拟了数据库查询。实际应用中你需要使用Lua的数据库连接库如luasql.mysql。关键点数据库操作是阻塞的如果查询慢会导致通话卡顿。因此务必确保数据库查询高效或考虑使用连接池、缓存如Redis来加速。复杂的查询最好放在后端APILua脚本通过HTTP请求去调用。动态TTS我们使用session:speak拼接动态文本账户ID和余额。这比预录制“您的账户”、“余额是”、“元”等多个文件再拼接播放要灵活得多。但再次强调确保TTS模块稳定可用。录音与工单集成在handle_repair_request中session:recordFile实现了录音功能。参数300000表示最长录音5分钟200是静音检测阈值值越小越敏感3000是检测到静音持续3秒后自动停止录音。录音文件命名包含了主叫号码和时间戳便于追溯。生成录音文件后脚本可以调用外部HTTP API将工单信息提交到CRM或工单系统实现自动化流程闭环。这里我们注释掉了HTTP调用代码实际使用时需要安装luasocket库并处理网络超时等异常。5. 高级技巧与生产环境优化一个能跑通的Demo和一個稳定可靠的生產環境IVR之間還有不少距離。以下是一些提升IVR質量和可維護性的關鍵技巧。5.1 错误处理与日志记录Lua脚本中的错误处理至关重要一个未捕获的异常可能导致整个呼叫被意外挂断。-- 在脚本最外层包裹一个pcall进行错误捕获 local function main() -- 上面所有的IVR逻辑代码放在这里 -- ... end local status, err pcall(main) if not status then freeswitch.consoleLog(CRIT, IVR脚本发生严重错误: .. tostring(err) .. \n) -- 发生错误时给用户一个友好的提示然后转人工或挂断 session:speak(系统发生错误正在为您转接人工服务。) session:transfer(1000, XML, default) -- 或 session:hangup() end日志分级合理使用freeswitch.consoleLog的不同级别DEBUG,INFO,NOTICE,WARNING,ERR,CRIT。在开发调试时用DEBUG输出详细变量上线后调整为NOTICE或WARNING只记录关键业务事件和错误避免日志文件膨胀过快。5.2 性能优化与资源管理语音文件缓存FreeSWITCH会自动缓存常用的语音文件到内存。对于核心的、频繁播放的提示音如欢迎语、主菜单确保它们被常访问以利用缓存。对于动态生成的TTS可以考虑使用mod_tts_commandline并配合本地缓存机制避免重复合成相同文本。脚本模块化当IVR菜单变多、逻辑变复杂时不要把上万行代码塞进一个lua文件。将通用函数如播放、收号、数据库查询抽取到独立的lua模块文件中通过require引入。这极大提升了代码的可读性和可维护性。避免阻塞操作如前所述在Lua脚本中执行同步HTTP请求、复杂数据库查询是危险的。如果必须做务必设置超时。更好的架构是将耗时业务逻辑剥离到后端服务IVR脚本通过消息队列或快速RPC如通过mod_event_socket发送事件异步触发然后通过session:setVariable和session:getVariable在后续的拨号计划步骤中获取结果。5.3 用户体验细节打磨背景音与等待音在用户输入或系统处理时播放舒适的背景音乐MOHMusic On Hold比死寂的等待要好得多。可以在Lua中使用session:execute(“playback”, “local_stream://moh”)来播放默认等待音。输入确认对于重要的输入如账户ID可以增加一个确认环节。“您输入的是123456按1确认按2重新输入。” 这能有效减少因误按导致的后续问题。超时与中断始终允许用户在任何时候按*键返回上一级菜单或按#键直接跳转到人工服务。这需要在每个playAndGetDigits调用中仔细设置terminators参数并在脚本中处理这些特殊按键。变量传递使用session:setVariable和session:getVariable在不同菜单层级或脚本之间传递信息。例如在账户查询子流程中获取的account_id可以存入变量后续如果转人工坐席端的屏幕弹出Popup就能显示这个ID实现“数据随呼叫流转”。6. 部署测试与常见问题排查配置和脚本写完了如何验证它是否工作6.1 部署与重载配置将准备好的语音文件放入正确的sounds子目录。将ivr_main.lua脚本放入FreeSWITCH的脚本目录如/usr/local/freeswitch/scripts/。修改dialplan/default.xml文件添加上面提到的extension。在FreeSWITCH命令行界面fs_cli中重载配置使其生效reloadxml reload mod_lua # 如果修改了Lua脚本需要重载Lua模块或整个系统注意直接修改Lua脚本文件FreeSWITCH可能不会自动检测到。最稳妥的方式是执行reload mod_lua或者在fs_cli中执行luarun ivr_main.lua进行语法检查虽然不运行但会报语法错误。6.2 模拟测试与调试使用fs_cli发起测试呼叫originate user/1000 8888这命令模拟分机1000呼叫8888。你需要一个注册了的分机1000来接收转接。更简单的测试方法——内联调试在fs_cli中直接执行eval ${lua(debugfile/tmp/ivr.log, ivr_main.lua)}这会在当前通道上下文中执行脚本并将调试输出重定向到/tmp/ivr.log。结合fs_cli中的console loglevel 7可以获取最详细的日志。监听通话音频通过fs_cli命令show channels找到通话的UUID然后使用uuid_dump uuid可以查看通道的详细状态和变量。对于音频问题可以开启rtp debug但更直接的方法是使用软电话如Zoiper、MicroSIP注册到FreeSWITCH进行真实呼叫测试亲耳听一遍流程。6.3 常见问题速查表问题现象可能原因排查步骤与解决方案呼叫8888直接忙音或失败Dialplan未正确匹配或加载1. 在fs_cli执行show channels看呼叫是否进来。2. 执行sofia global capture on开启SIP信令捕获看INVITE是否到达和被处理。3. 检查dialplan/default.xml语法执行reloadxml后查看日志有无错误。能接通但听不到欢迎语音语音文件路径错误或格式不支持1. 在fs_cli执行file_exists ivr/zh/cn/welcome.wav检查文件路径。2. 用sox或ffmpeg检查音频文件格式确保是单声道、8kHz或16kHz采样率、PCM编码的WAV文件。3. 检查文件权限ls -l /usr/local/freeswitch/sounds/ivr/zh/cn/。收号无效按任何键都没反应playAndGetDigits参数设置问题或DTMF格式不匹配1. 检查FreeSWITCH的DTMF检测设置rtp-dtmf-type。2. 在fs_cli执行dtmf_dump on开启DTMF调试看按键事件是否被正确接收。3. 检查playAndGetDigits的regex参数是否正确比如^[123]$是否写成了^[123]缺少结尾$。Lua脚本语法错误呼叫中断Lua脚本存在语法错误或运行时错误1. 在fs_cli执行luarun /path/to/ivr_main.lua进行语法检查。2. 查看FreeSWITCH日志文件log/freeswitch.log搜索LUA ERROR。3. 在脚本中增加更多freeswitch.consoleLog(“DEBUG”, …)语句输出关键变量值。转接人工坐席失败目标分机未注册或转接字符串错误1. 执行sofia status profile internal reg查看分机1000是否已注册。2. 检查session:transfer的参数格式通常是(“目标号码”, “拨号计划类型”, “拨号计划上下文”)。3. 尝试直接拨打分机1000看是否正常。配置一个FreeSWITCH IVR从理解业务流到写出可用的脚本核心在于对playAndGetDigits等几个关键API的熟练掌握以及对呼叫状态机的清晰认识。把XML看作路由地图把Lua看作地图上每个节点的智能管家这种分工能让你的IVR系统既稳定又灵活。最后多测试、多听日志从用户的每一次按键中感受流程的顺畅与否不断迭代优化提示语和超时时间这才是打造一个优秀语音体验的不二法门。