本文详细介绍了如何利用Twilio的TwiML功能，为基于掩码号码的呼叫转接系统添加语音留言功能。当用户的主号码因无人接听、忙线或无法接通时，系统将引导呼叫方录制语音留言。教程涵盖了通过`twiml.dial`设置呼叫超时、使用`twiml.record`进行留言录制，以及配置`recordingStatusCallback`处理录音文件并集成语音转文本及邮件通知的实现细节。
在构建基于掩码号码（Masked Number）的通信应用时，实现呼叫转接是核心功能之一。用户通过购买的掩码号码接收客户来电，系统将这些来电转接到用户的真实号码上。然而，当用户的真实号码无法接通、忙线或无人应答时，提供一个语音留言机制将极大提升用户体验，确保重要信息不丢失。本文将指导您如何利用Twilio的TwiML指令，为您的应用集成这一关键功能。
1. 呼叫转接与未接通处理
首先，我们需要确保呼叫能够正确地从掩码号码转接到用户的真实号码。在您的Twilio语音Webhook中，当接到来自客户的来电时，您会获取到呼叫信息，并通过查询数据库获取掩码号码对应的用户真实号码（primaryPhoneNumber）。
在现有的代码逻辑中，router.post("/webhook/voice", ...) 负责处理入站语音呼叫。当CallStatus为"ringing"时，我们通过twiml.dial(primaryPhoneNumber)将呼叫转接出去。为了处理未接通的情况，我们需要为dial动词添加timeout属性。
设置呼叫转接超时：
timeout属性定义了Twilio在放弃尝试连接被叫方之前等待的秒数。一旦达到超时，如果呼叫未成功建立，Twilio将继续执行TwiML响应中的下一个动词。
const twilio = require("twilio");
const express = require("express");
const router = express.Router();
// ... (其他引入和数据库操作函数)
router.post("/webhook/voice", async (req, res) => {
const { To, From, CallStatus } = req.body;
const [numbers] = await getNumberWithoutUser(To);
if (!numbers) return res.status(400).send("User does not own this number");
const type = numbers.numbers.subscriptions.find(
(subscription) => subscription.active
).type;
const isToPrimaryPhone =
numbers?.numbers?.settings?.forwarding?.toPrimaryPhone;
const primaryPhoneNumber =
numbers?.numbers?.settings?.forwarding?.primaryPhoneNumber;
if (isToPrimaryPhone) {
switch (CallStatus) {
case "ringing":
const twiml = new twilio.twiml.VoiceResponse();
// 1. 尝试呼叫用户的真实号码，设置超时为7秒
// 如果在7秒内未接通，Twilio将继续执行TwiML中的下一个指令
const dial = twiml.dial({
timeout: 7 // 设置呼叫超时时间，单位：秒
});
dial.number(primaryPhoneNumber); // 拨打用户的真实号码
// ... (后续的语音留言逻辑将在此处添加)
await updateQuota(numbers._id, To, "callForwarding", type);
res.type("text/xml");
return res.send(twiml.toString());
case "completed":
await appendCall(numbers._id, To, From, req.body);
return res.send("success");
}
}
res.send("Call Forwarding is disabled or package has finished");
});2. 实现语音留言录制
在dial动词超时或失败后，我们可以使用twiml.record动词来提示呼叫方录制语音留言。
twiml.record的关键属性：
- recordingStatusCallback: 这是最重要的属性。当录音完成后，Twilio会向这个URL发送一个POST请求，其中包含录音文件的URL (RecordingUrl)、录音时长 (RecordingDuration) 等详细信息。您需要在此回调URL对应的端点处理录音文件。
- maxLength: 设置录音的最大时长（秒）。
- finishOnKey: 允许呼叫方按下指定按键（如*或#）提前结束录音。
- playBeep: 是否在录音开始前播放提示音（蜂鸣声）。
集成语音留言功能：
在上述case "ringing"的代码块中，紧跟在twiml.dial之后添加twiml.say和twiml.record动词。
case "ringing":
const twiml = new twilio.twiml.VoiceResponse();
const dial = twiml.dial({
timeout: 7
});
dial.number(primaryPhoneNumber);
// 如果主号码未接通（超时、忙线、无人接听），则执行以下语音留言逻辑
twiml.say({ voice: 'Polly.Zhiyu', language: 'zh-CN' }, "您好，您拨打的用户暂时无法接听，请在滴声后留言。"); // 语音提示
twiml.record({
recordingStatusCallback: "https://your-ngrok-url/webhook/voice/voicemail-callback", // 替换为您的实际回调URL
maxLength: 60, // 最大录音时长60秒
finishOnKey: '*' // 呼叫方按*号结束录音
});
twiml.say({ voice: 'Polly.Zhiyu', language: 'zh-CN' }, "感谢您的留言，再见。"); // 录音结束后的提示
await updateQuota(numbers._id, To, "callForwarding", type);
res.type("text/xml");
return res.send(twiml.toString());注意事项：
- recordingStatusCallback的URL必须是公开可访问的，Twilio才能发送回调请求。在开发阶段可以使用ngrok。
- twiml.say中的voice和language属性可以根据需求调整，提供更自然的语音提示。
3. 处理语音留言回调
现在，我们需要创建一个新的路由来处理recordingStatusCallback发送的请求。在这个端点中，您将接收到录音文件的URL，并可以执行后续操作，例如：
- 存储录音信息到数据库：保存RecordingUrl、CallSid、呼叫方/被叫方号码等信息。
- 语音转文本（Speech-to-Text）：利用Twilio的转录服务或第三方API（如Google Cloud Speech-to-Text、AWS Transcribe）将语音内容转换为文本。
- 发送邮件通知：将录音链接和转录文本通过邮件发送给用户。
// ... (其他引入)
router.post("/webhook/voice/voicemail-callback", async (req, res) => {
const { RecordingUrl, CallSid, From, To, RecordingDuration, TranscriptionText } = req.body;
console.log(`收到语音留言回调：`);
console.log(`录音URL: ${RecordingUrl}`);
console.log(`呼叫SID: ${CallSid}`);
console.log(`呼叫方: ${From}`);
console.log(`被叫方 (掩码号码): ${To}`);
console.log(`录音时长: ${RecordingDuration} 秒`);
// 如果Twilio自动转录服务已开启，这里可能包含TranscriptionText
console.log(`转录文本: ${TranscriptionText}`);
try {
// 1. 根据To (掩码号码) 查找对应的用户ID和配置
const [numbers] = await getNumberWithoutUser(To);
if (!numbers) {
console.error(`未找到掩码号码 ${To} 对应的用户配置`);
return res.status(400).send("Invalid masked number");
}
const userId = numbers._id;
const userEmail = numbers?.numbers?.settings?.emailForVoicemail; // 假设用户设置了接收语音留言的邮箱
// 2. 将录音信息存储到数据库 (例如，您的messagingCollectionUtils或一个新的voicemailCollection)
// appendMessage(userId, To, From, { type: 'voicemail', url: RecordingUrl, duration: RecordingDuration, transcription: TranscriptionText });
// 或者创建一个专门的appendVoicemail函数
// await appendVoicemail(userId, To, From, RecordingUrl, RecordingDuration, TranscriptionText);
console.log(`语音留言信息已记录到数据库。`);
// 3. 如果Twilio没有提供TranscriptionText，您可以使用Twilio的API手动进行转录
// const transcription = await client.recordings(CallSid).transcriptions.create({
// recordingSid: req.body.RecordingSid // 或者直接使用RecordingSid
// });
// const fullTranscriptionText = transcription.transcriptionText;
// 4. 发送邮件通知用户
if (userEmail) {
const emailSubject = `您有一个新的语音留言来自 ${From}`;
const emailBody = `
您好，
您有一个新的语音留言。
呼叫方: ${From}
录音时长: ${RecordingDuration} 秒
录音链接: ${RecordingUrl}
${TranscriptionText ? `转录文本: ${TranscriptionText}
` : ''}
请点击链接收听。
祝您愉快！
`;
await sendMessageNotificationEmail(userEmail, emailSubject, emailBody); // 假设您有发送邮件的函数
console.log(`语音留言通知邮件已发送至 ${userEmail}。`);
} else {
console.warn(`用户 ${userId} 未配置接收语音留言的邮箱。`);
}
// Twilio期望一个空的TwiML响应或一个简单的消息
res.type("text/xml");
res.send(new twilio.twiml.VoiceResponse().toString());
} catch (error) {
console.error("处理语音留言回调时发生错误:", error);
res.status(500).send("Error processing voicemail callback");
}
});核心模块引用： 在上述示例中，我们假设您已经实现了以下辅助函数或模块：
- getNumberWithoutUser(maskedNumber): 根据掩码号码获取用户及相关配置。
- appendCall(userId, to, from, callDetails): 记录通话详情。
- updateQuota(userId, maskedNumber, type, subscriptionType): 更新用户配额。
- sendMessageNotificationEmail(email, subject, body): 发送邮件通知。
- client: Twilio客户端实例，用于调用Twilio API（例如，如果需要手动进行语音转文本）。
总结
通过结合twiml.dial的timeout属性和twiml.record动词，我们可以为Twilio呼叫转接系统无缝地集成语音留言功能。当用户无法接听电话时，客户可以留下语音信息，并通过回调机制将录音文件发送到您的应用进行处理。进一步结合语音转文本和邮件通知，可以构建一个功能完善且用户友好的通信解决方案。务必确保您的Webhook URL安全且可访问，并妥善处理录音文件的存储和隐私问题。
