使用Twilio WhatsApp API发送多类型文件时格式不匹配问题排查

问题分析 #

从错误日志msg=header: Format mismatch, expected IMAGE, received VIDEO可以看出，Twilio预期接收的是图片类型媒体，但实际收到的是其他类型（哪怕是PDF也触发这个错误），核心原因集中在两点：

• WhatsApp模板中对应的变量类型定义错误
• 代理服务器返回的响应头不完整，导致Twilio无法正确识别文件类型

解决方案 #

1. 修正WhatsApp模板的变量类型 #

你创建的模板中，{{6}}这个变量如果被定义为IMAGE类型，无论代理返回什么文件，Twilio都会强制校验为图片，从而触发格式不匹配错误。需要：

• 登录Twilio控制台找到对应WhatsApp模板
• 将{{6}}的变量类型修改为对应媒体类型：
  • 发送文档时设为DOCUMENT
  • 发送视频时设为VIDEO
  • 注意：单个模板的变量类型固定，若需发送多种类型文件，需创建对应类型的多个模板

2. 完善代理服务器的响应头处理 #

当前代理代码仅处理了部分文件类型的Content-Type，且缺少Content-Disposition头，这可能导致Twilio无法正确识别文件类型。修改后的代码如下：

app.get('/proxy-file', async (request, reply) => {
    const { file: fileUrl } = request.query;

    if (!fileUrl) {
        reply.status(400).send('File URL is required');
        return;
    }

    try {
        const response = await axios.get(fileUrl, {
            responseType: 'arraybuffer',
        });

        let contentType = 'application/octet-stream';
        let fileName = 'file';
        
        // 根据文件后缀设置正确的Content-Type和文件名
        if (fileUrl.endsWith('.pdf')) {
            contentType = 'application/pdf';
            fileName = 'document.pdf';
        } else if (fileUrl.endsWith('.doc')) {
            contentType = 'application/msword';
            fileName = 'document.doc';
        } else if (fileUrl.endsWith('.docx')) {
            contentType = 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
            fileName = 'document.docx';
        } else if (fileUrl.endsWith('.mp4')) {
            contentType = 'video/mp4';
            fileName = 'video.mp4';
        } else if (fileUrl.match(/\.(jpg|jpeg|png|gif)$/i)) {
            // 补全图片类型的Content-Type
            const ext = fileUrl.split('.').pop().toLowerCase();
            contentType = ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg' : `image/${ext}`;
            fileName = `image.${ext}`;
        }

        // 添加Content-Disposition头，帮助Twilio识别文件类型和名称
        reply.header('Content-Type', contentType);
        reply.header('Content-Disposition', `attachment; filename="${fileName}"`);
        reply.send(response.data);
    } catch (error) {
        reply.status(500).send('Erro ao obter o arquivo');
    }
});

3. 验证文件内容完整性 #

确保代理请求的源文件URL可访问，且axios获取的response.data是完整的二进制数据。可通过直接访问代理URL，检查浏览器能否正确下载并打开文件，验证内容是否正常。

额外注意事项 #

• WhatsApp对文件大小有限制：文档最大100MB，视频最大16MB，需确保文件符合要求
• 代理服务器需公网可访问，且无防火墙或IP限制导致Twilio无法请求

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