本教程详细介绍了如何将语音留言系统集成到基于Twilio的掩码号码呼叫转接应用中。它涵盖了如何利用Twilio TwiML的Dial动词结合timeout属性来处理未接听的呼叫，以及如何使用Record动词让客户留言。文章还解释了如何配置录音回调，以进行语音留言的处理、存储和转录，确保用户通过电子邮件及时收到通知。
在构建基于Twilio的通信应用时，为用户提供掩码号码（Masked Number）服务，并实现呼叫转接是常见的需求。当客户拨打用户的掩码号码时，呼叫会被转接到用户的真实号码。然而，如果用户因忙碌、无法接听或无法联系到而错过呼叫，提供语音留言功能将极大地提升用户体验。本教程将指导您如何利用Twilio的TwiML动词（Dial和Record）来构建一个健壮的语音留言系统，包括未接听呼叫的检测、语音留言的录制、存储、转录以及通过电子邮件通知用户。
核心挑战与解决方案概述
挑战： 如何在呼叫转接失败（例如，用户未接听）时，自动引导客户进入语音留言流程，并对留言进行后续处理。
解决方案：
- 设置呼叫超时： 使用Dial动词的timeout属性，限制呼叫转接的振铃时间。
- 定义未接通回调： 利用Dial动词的action属性，在呼叫超时或未接通时，将控制权转交给另一个Webhook URL。
- 录制语音留言： 在上述action指向的Webhook中，使用Record动词引导客户留言。
- 处理录音结果： 配置Record动词的recordingStatusCallback属性，接收录音完成后的通知，进而进行存储、语音转文本（Speech-to-Text）处理，并通过邮件发送给用户。
1. 处理未接听的呼叫：Dial动词与超时设置
当客户呼叫掩码号码时，您的Twilio Webhook会接收到CallStatus为ringing的请求。在此阶段，您需要尝试将呼叫转接到用户的真实号码。为了在用户未接听时启动语音留言流程，我们需要在Dial动词中设置timeout和action属性。
timeout属性定义了Twilio尝试连接被叫方的时间（单位：秒）。如果在此时间内被叫方未接听，Twilio将停止拨号并向action属性指定的URL发送一个HTTP请求。
示例代码（webhook/voice端点修改）：
假设您已有一个处理/webhook/voice的Express路由。我们需要修改其中CallStatus为ringing时的逻辑。
const twilio = require("twilio");
const express = require("express");
const router = express.Router();
// 假设您已经有以下数据库和邮件操作函数
// const { getNumberWithoutUser, updateQuota } = require("../db/dbOperations");
// const { sendMessageNotificationEmail } = require("../emailing/email");
// const { appendCall } = require("../db/callsCollectionUtils");
router.post("/webhook/voice", async (req, res) => {
const { To, From, CallStatus } = req.body;
// 假设getNumberWithoutUser函数能够根据掩码号码获取相关用户及设置
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) {
const twiml = new twilio.twiml.VoiceResponse();
switch (CallStatus) {
case "ringing":
// 尝试拨打用户主号码，设置超时和未接通后的回调URL
// 注意：action URL 必须是 Twilio 可访问的公共 URL (例如您的 ngrok 或生产环境域名)
twiml.dial({
timeout: 15, // 设置拨打超时时间，例如15秒
action: `https://your-domain.com/webhook/voicemail?To=${To}&From=${From}`, // 超时或未接通后，Twilio会请求此URL
method: 'POST'
}, 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");
// 您可能还需要处理其他 CallStatus，但 'action' URL 会处理 'no-answer', 'busy' 等情况
}
}
// 如果呼叫转接未启用或套餐已过期
res.send("Call Forwarding is disabled or package has finished");
});说明：
- timeout: 15：设置振铃15秒。如果用户在此时间内未接听，呼叫将转到action指定的URL。
- action: https://your-domain.com/webhook/voicemail?To=${To}&From=${From}：这是关键。当拨号失败时，Twilio会向此URL发送一个POST请求。我们将To（掩码号码）和From（客户号码）作为查询参数传递，以便在后续的语音留言处理中使用。
- 请务必将https://your-domain.com替换为您的实际公共域名或ngrok转发地址。
2. 实现语音留言录制：Record动词
当Dial动词因超时或其他原因失败时，Twilio会向action指定的/webhook/voicemail端点发送请求。在这个端点中，我们将使用Record动词来提示客户留言。
示例代码（/webhook/voicemail端点）：
// ... (之前的导入和设置) ...
router.post("/webhook/voicemail", async (req, res) => {
// 从查询参数中获取掩码号码 (To) 和客户号码 (From)
const { To, From } = req.query;
const twiml = new twilio.twiml.VoiceResponse();
// 播放提示音，引导客户留言
twiml.say({ voice: 'alice', language: 'zh-CN' }, "您拨打的用户暂时无法接听，请在'嘟'声后留言。留言结束后请按星号键。");
twiml.record({
recordingStatusCallback: `https://your-domain.com/webhook/recording-callback?To=${To}&From=${From}`, // 留言完成后，Twilio会请求此URL
recordingStatusCallbackMethod: 'POST',
maxLength: 60, // 最长录音60秒
finishOnKey: '*' // 客户可以按星号键提前结束录音
});
twiml.say({ voice: 'alice', language: 'zh-CN' }, "感谢您的留言，再见。"); // 留言结束后播放感谢语
res.type("text/xml");
res.send(twiml.toString());
});说明：
- twiml.say()：播放一段语音提示，告知客户当前情况并引导留言。您可以自定义语音内容、语言和声音。
- twiml.record()：这是录制语音留言的核心。
- recordingStatusCallback: 录音完成后，Twilio会将录音文件URL及其他相关信息POST到此URL。同样，我们将To和From作为查询参数传递。
- maxLength: 设置录音的最大时长，防止录音过长。
- finishOnKey: 允许客户通过按特定按键（例如*星号键）提前结束录音。
3. 语音留言的后续处理：存储、转录与通知
当客户完成留言后，Twilio会向recordingStatusCallback指定的/webhook/recording-callback端点发送一个POST请求。这个请求包含了录音文件的URL以及其他有用的信息。
示例代码（/webhook/recording-callback端点）：
// ... (之前的导入和设置) ...
// const { getNumberWithoutUser, sendMessageNotificationEmail } = require("../db/dbOperations");
// const { appendMessage } = require("../db/messagingCollectionUtils"); // 用于存储留言信息
// const { client } = require("../twilioFunctions"); // 如果需要调用Twilio REST API进行转录
router.post("/webhook/recording-callback", async (req, res) => {
const { To, From } = req.query; // 掩码号码 (To) 和客户号码 (From)
const { RecordingUrl, RecordingDuration, CallSid, TranscriptionText, TranscriptionSid } = req.body; // Twilio发送的录音详情
// 假设getNumberWithoutUser函数能够根据掩码号码获取相关用户
const [numbers] = await getNumberWithoutUser(To);
if (!numbers) {
console.error(`User for masked number ${To} not found.`);
return res.status(404).send("User not found");
}
try {
// 1. 存储录音信息到数据库
// 您可以将 RecordingUrl、RecordingDuration、From、To 等信息存储到数据库中
await appendMessage(numbers._id, To, From, {
type: 'voicemail', 
