本教程详细介绍了如何使用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动词的灵活运用是实现此类复杂通信逻辑的关键。
