
本教程详细介绍了如何使用Twilio构建一个具备呼叫转发功能的系统,并在此基础上实现未接来电自动转接语音留言。文章将涵盖Twilio TwiML中的`Dial`和`Record`动词的使用,包括设置呼叫超时、录制语音留言,以及通过Webhook处理录音回调和转录,最终实现将语音留言通过邮件通知用户。
在现代通信应用中,为用户提供一个隐私保护的虚拟号码(即掩码号码)并将其呼叫转发至真实号码是一项常见需求。然而,当用户真实号码无法接通、占线或未及时应答时,如何确保客户能够留下语音留言,并及时通知用户,是提升用户体验的关键。本教程将详细阐述如何利用Twilio的强大功能,构建一个完整的呼叫转发与未接来电语音留言系统。
1. 核心需求分析
我们的目标是实现以下功能:
- 客户拨打用户的掩码号码。
- Twilio将呼叫转发至用户的真实号码。
- 如果用户真实号码未接通、占线或未应答,客户可以录制语音留言。
- 语音留言将被存储,并通过Twilio的语音转文本API进行转录。
- 转录文本和语音文件链接将通过电子邮件发送给用户。
2. Twilio TwiML动词:Dial与Record
Twilio通过TwiML(Twilio Markup Language)来控制呼叫流程。实现上述功能主要依赖于Dial和Record这两个核心动词。
2.1 使用 Dial 动词进行呼叫转发与超时设置
Dial动词用于将当前呼叫连接到另一个电话号码或Twilio客户端。为了处理未接来电,我们需要利用Dial动词的timeout和action属性。
- timeout:指定Twilio等待被叫方接听的时间(秒)。如果在此时间内未接听,Twilio将停止尝试连接。
- action:当Dial动词执行结束时(例如,被叫方未接听、占线或失败),Twilio会向此URL发起一个http请求。这个URL将用于处理呼叫的后续逻辑,例如转接至语音留言。
示例代码:主呼叫Webhook (/webhook/voice)
const twilio = require("twilio"); const express = require("express"); const router = express.Router(); // 假设 getNumberWithoutUser 和 updateQuota 是你的数据库操作函数 // const { getNumberWithoutUser, updateQuota } = require("../db/dbOperations"); router.post("/webhook/voice", async (req, res) => { const { To, From, CallStatus } = req.body; // 假设根据 'To' 掩码号码获取用户信息和真实号码 // const [numbers] = await getNumberWithoutUser(To); // if (!numbers) return res.status(400).send("User does not own this number"); // 假设这些信息从数据库中获取 const primaryPhoneNumber = "+8613800138000"; // 示例:用户的真实号码 const isToPrimaryPhone = true; // 示例:是否开启了呼叫转发 if (isToPrimaryPhone) { const twiml = new twilio.twiml.VoiceResponse(); // 可选:在转接前播放欢迎语 twiml.say({ voice: 'alice', language: 'zh-CN' }, "请稍候,我们正在为您转接。"); // 使用Dial动词将呼叫转发到用户的真实号码 // 设置15秒超时,如果未接听,则将控制权转交给 /webhook/handle_dial_outcome twiml.dial({ timeout: 15, // 等待被叫方接听的秒数 action: '/webhook/handle_dial_outcome', // 如果未接听,Twilio将请求此URL hangupOnStar: true // 允许呼叫者按 * 键跳过语音留言 }, primaryPhoneNumber); // 假设更新呼叫配额 // await updateQuota(numbers._id, To, "callForwarding", type); res.type("text/xml"); return res.send(twiml.toString()); } // 如果呼叫转发未启用或套餐已过期 res.send("Call Forwarding is disabled or package has finished"); }); module.exports = router;
2.2 使用 Record 动词录制语音留言
当Dial动词因超时而结束时,Twilio会调用action指定的URL。在这个新的Webhook中,我们将使用Record动词来提示客户录制语音留言。
Record动词的关键属性:
- maxLength:录音的最大时长(秒)。
- finishOnKey:当呼叫者按下此键时,录音结束。
- action:录音完成后,Twilio会向此URL发起HTTP请求,并附带录音的URL和其他信息。
- transcribe:设置为true可以启用Twilio的语音转文本服务。
- transcribeCallback:如果启用了转录,转录完成后Twilio会向此URL发起请求,并附带转录文本。
示例代码:处理Dial动词结果的Webhook (/webhook/handle_dial_outcome)
// ... (之前的require和router定义) router.post("/webhook/handle_dial_outcome", async (req, res) => { const { DialCallStatus, To, From } = req.body; // DialCallStatus 表示Dial动词的执行结果 const twiml = new twilio.twiml.VoiceResponse(); // 检查Dial动词的执行状态 if (DialCallStatus === 'no-answer' || DialCallStatus === 'busy' || DialCallStatus === 'failed') { // 如果呼叫未接听、占线或失败,则提示客户留言 twiml.say({ voice: 'alice', language: 'zh-CN' }, "您拨打的用户暂时无法接听,请在哔声后留言。"); twiml.record({ maxLength: 60, // 最大录音时长60秒 finishOnKey: '#', // 呼叫者按 # 键结束录音 action: '/webhook/recording_status', // 录音完成后,Twilio将请求此URL transcribe: true, // 启用语音转文本 transcribeCallback: '/webhook/transcription_status' // 转录完成后,Twilio将请求此URL }); twiml.say({ voice: 'alice', language: 'zh-CN' }, "留言结束,感谢您的来电。"); } else { // 其他状态,例如呼叫已完成(通常不会进入此分支,因为如果接听,Dial动词会直接连接,不会触发action) // 或者可以播放一个结束语 twiml.say({ voice: 'alice', language: 'zh-CN' }, "感谢您的来电。"); } res.type("text/xml"); return res.send(twiml.toString()); }); // module.exports = router; // 如果是单独的文件,需要导出
3. 处理录音与转录回调
当录音完成或转录完成时,Twilio会分别向action和transcribeCallback指定的URL发送POST请求,其中包含录音或转录的详细信息。
3.1 录音状态回调 (/webhook/recording_status)
这个Webhook会接收到录音的URL、时长等信息。你可以在这里将这些信息存储到数据库,并触发邮件通知。
// ... (之前的require和router定义) router.post("/webhook/recording_status", async (req, res) => { const { RecordingUrl, RecordingDuration, CallSid, From, To } = req.body; console.log(`收到新的语音留言:${RecordingUrl},时长:${RecordingDuration}秒`); // 1. 将录音信息存储到数据库 // const [numbers] = await getNumberWithoutUser(To); // 根据'To'掩码号码获取用户数据 // if (numbers) { // await appendMessage(numbers._id, To, From, { // type: 'voicemail', // url: RecordingUrl, // duration: RecordingDuration, // callSid: CallSid // }); // // 2. 如果不需要等待转录结果,可以直接发送邮件通知 // // await sendMessageNotificationEmail(numbers.userEmail, "您有新的语音留言", `请访问:${RecordingUrl}`); // } // Twilio期望收到一个200 OK响应 res.send("Voicemail recording processed."); });
3.2 转录状态回调 (/webhook/transcription_status)
如果启用了transcribe: true,当Twilio完成语音转文本后,会调用此Webhook。这里可以获取转录文本,并将其与录音链接一同通过邮件发送给用户。
// ... (之前的require和router定义) router.post("/webhook/transcription_status", async (req, res) => { const { TranscriptionStatus, TranscriptionText, RecordingUrl, CallSid, From, To } = req.body; if (TranscriptionStatus === 'completed') { console.log(`语音留言转录完成。录音:${RecordingUrl},转录文本:${TranscriptionText}`); // 1. 更新数据库中对应的语音留言记录,添加转录文本 // const [numbers] = await getNumberWithoutUser(To); // if (numbers) { // // 假设有一个函数可以更新留言记录 // // await updateVoicemailTranscription(CallSid, TranscriptionText); // // 2. 发送包含语音链接和转录文本的邮件通知 // // const emailBody = `您有一个新的语音留言:n语音链接:${RecordingUrl}n转录内容:${TranscriptionText}`; // // await sendMessageNotificationEmail(numbers.userEmail, "您有新的语音留言及转录", emailBody); // } } else { console.log(`语音转录失败或进行中,状态:${TranscriptionStatus}`); } res.send("Voicemail transcription processed."); });
4. 注意事项与最佳实践
- Webhook安全性:所有Twilio Webhook都应该验证请求的签名,以确保请求确实来自Twilio,防止恶意攻击。Twilio官方提供了SDK来帮助进行签名验证。
- 错误处理:在Webhook中,始终要考虑各种异常情况,例如数据库连接失败、邮件发送失败等,并实现相应的错误日志记录和重试机制。
- 用户体验:
- 在转接语音留言前播放清晰的提示音,告知客户即将进入留言环节。
- 明确告知客户如何结束留言(例如“请在哔声后留言,留言结束后请按#号键”)。
- 提供合适的maxLength,避免留言过长或过短。
- 异步处理:邮件发送、数据库更新等操作可能耗时较长。为了不阻塞Twilio的Webhook响应,可以考虑将这些任务放入消息队列进行异步处理。Twilio期望Webhook在几秒内返回TwiML。
- Twilio控制台配置:确保你的Twilio掩码号码已正确配置了主呼叫Webhook URL(例如 https://your-ngrok-url.com/webhook/voice)。
- 开发调试:使用ngrok等工具可以方便地将本地开发环境暴露给Twilio的Webhook请求,进行实时调试。
- 国际化:在twiml.say中使用language属性可以指定语音提示的语言,例如zh-CN代表中文普通话,提升不同地区用户的体验。
总结
通过本教程,我们学习了如何利用Twilio的Dial和Record TwiML动词,结合多个Webhook回调,构建一个功能完善的呼叫转发和未接来电语音留言系统。这不仅提升了用户在无法接听电话时的服务连续性,也为客户提供了便捷的沟通渠道。理解Twilio的Webhook机制和TwiML动词的灵活运用是实现此类复杂通信逻辑的关键。