本文详细介绍了如何利用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 = ` <p>您好，</p> <p>您有一个新的语音留言。</p> <p><b>呼叫方:</b> ${From}</p> <p><b>录音时长:</b> ${RecordingDuration} 秒</p> <p><b>录音链接:</b> <a href="${RecordingUrl}">${RecordingUrl}</a></p> ${TranscriptionText ? `<p><b>转录文本:</b> ${TranscriptionText}</p>` : ''} <p>请点击链接收听。</p> <p>祝您愉快！</p> `; 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安全且可访问，并妥善处理录音文件的存储和隐私问题。