Twilio外呼自定义参数无法传递至后端Webhook问题求助

问题描述 #

• 前端通过Twilio Device.connect()发起外呼时传入自定义参数user_id和hospital_id，但后端Webhook的req.body中接收不到这两个参数。
• Webhook可正常接收Twilio标准参数（如CallSid、From、To等），仅自定义参数缺失。

前端代码 #

const call = useCallback(
  async (phone: string) => {
    if (!twilioDevice || twilioDevice.state !== Device.State.Registered) {
      return Promise.reject(new Error(Messages.STILL_TWILIO_DEVICE_SETUP_IS_NOT_DONE));
    }
    if (hasOutboundCall) {
      return Promise.reject(new Error(Messages.OUTBOUND_CALL_IN_PROGRESS));
    }

    const newCall = await twilioDevice.connect({
      params: {
        To: phone,
        type: 'outgoing',
        user_id: String(user!.id),
        hospital_id: String(user!.hospital_id),
      },
    });
    setActiveCall(newCall);
  },
  [user?.id, twilioDevice, hasOutboundCall, user?.hospital_id]
);

后端Webhook代码 #

gvcommRoute.route(/voice/call/hook).post(
  async (req, res) => {
    console.log("Incoming Twilio Call Data:", req.body);
  }
);

预期与实际行为 #

• 预期：Webhook的req.body中能获取到user_id和hospital_id参数。
• 实际：仅能收到Twilio标准参数，自定义参数缺失。

解决方案 #

1. 修正Token生成逻辑，传递自定义参数 #

前端Twilio Device的Token由后端生成，自定义参数需在Token生成阶段传递，而非仅在connect()方法中传入。示例代码如下：

// 后端生成Twilio Capability Token的示例
const capability = new twilio.jwt.ClientCapability({
  accountSid: process.env.TWILIO_ACCOUNT_SID,
  authToken: process.env.TWILIO_AUTH_TOKEN,
});

// 将自定义参数通过OutgoingClientScope传入
capability.addScope(
  new twilio.jwt.ClientCapability.OutgoingClientScope({
    applicationSid: process.env.TWILIO_TWIML_APP_SID,
    params: {
      user_id: user.id,
      hospital_id: user.hospital_id,
    },
  })
);

const token = capability.toJwt();

2. 配置Twilio控制台的参数转发 #

登录Twilio控制台，找到对应TwiML应用：

• 在「Voice」板块的「Outgoing Caller ID」下方，设置「Request URL」为你的后端Webhook地址
• 确保请求方法为POST，并开启参数转发选项（部分版本需手动在Webhook URL后拼接参数，或在TwiML中显式传递）

3. 确保后端正确解析请求 #

检查后端是否配置了表单解析中间件，Twilio默认以application/x-www-form-urlencoded格式发送请求：

// 先配置解析中间件
app.use(express.urlencoded({ extended: true }));
app.use(express.json());

gvcommRoute.route('/voice/call/hook').post(
  async (req, res) => {
    // 此时可直接从req.body中获取自定义参数
    console.log("自定义参数:", req.body.user_id, req.body.hospital_id);
    console.log("Incoming Twilio Call Data:", req.body);
  }
);

4. 在TwiML响应中显式传递参数 #

如果上述方法无效，可在后端返回TwiML时，通过<Dial>标签的parameters属性传递参数：

const twiml = new twilio.twiml.VoiceResponse();
const dial = twiml.dial({
  parameters: {
    user_id: req.body.user_id,
    hospital_id: req.body.hospital_id,
  },
});
dial.number(req.body.To);

res.type('text/xml');
res.send(twiml.toString());

内容的提问来源于stack exchange，提问作者Harvinder Singh