S3预签名URL对接WhatsApp Cloud API发送MP3音频问题排查

核心问题根源 #

WhatsApp Cloud API对音频链接的兼容性要求包括：正确的Content-Type、可直接访问的资源、URL格式符合标准。S3预签名URL失效的常见原因包括：

1. 音频文件的Content-Type未设置为audio/mpeg，S3默认会标记为binary/octet-stream，导致WhatsApp无法识别文件类型
2. 预签名URL的有效性未验证（如权限、过期时间）
3. WhatsApp API返回成功状态码但在响应体中包含错误信息，未被日志捕获

解决方案 #

1. 强制设置S3音频文件的Content-Type #

修改upload_audiostream_to_s3函数，在上传时指定正确的MIME类型，确保WhatsApp能识别音频格式：

def upload_audiostream_to_s3(audio_stream) -> str:
    s3_file_name = f"{uuid.uuid4()}.mp3"
    s3.upload_fileobj(
        audio_stream,
        "AWS_S3_BUCKET_NAME",
        s3_file_name,
        ExtraArgs={"ContentType": "audio/mpeg"}
    )
    return s3_file_name

2. 捕获WhatsApp API的详细响应信息 #

当前代码仅捕获HTTP错误状态码，但WhatsApp可能返回200状态码但在响应体中包含处理失败的细节。修改send_message函数的日志逻辑，打印完整响应内容：

else:
    response_data = response.json()
    logging.info(f"WhatsApp API Response: {response_data}")
    # 检查是否存在错误字段
    if 'error' in response_data:
        logging.error(f"WhatsApp processing error: {response_data['error']}")
    log_http_response(response)
    return response

3. 验证预签名URL的有效性 #

在testingElevenLabs函数中添加预签名URL的访问验证，确保S3资源可正常获取：

import requests

def testingElevenLabs(text: str):
    audio_stream = text_to_speech_stream(text)
    s3_file_name = upload_audiostream_to_s3(audio_stream)
    signed_url = generate_presigned_url(s3_file_name)
    
    # 验证URL可访问且Content-Type正确
    try:
        resp = requests.head(signed_url, timeout=5)
        resp.raise_for_status()
        content_type = resp.headers.get('Content-Type')
        if content_type != 'audio/mpeg':
            logging.warning(f"Incorrect Content-Type: {content_type}")
    except requests.RequestException as e:
        logging.error(f"Presigned URL validation failed: {e}")
        raise
    
    print(f"Signed URL to access the file: {signed_url}")
    return signed_url

4. 替代方案：使用CloudFront分发（更稳定的私有资源访问） #

如果预签名URL仍存在兼容性问题，可通过CloudFront搭配Origin Access Identity（OAI）实现私有S3资源的稳定分发：

• 创建CloudFront分发，关联S3桶并启用OAI，确保只有CloudFront能访问S3资源
• 配置CloudFront缓存行为，设置Cache-Control和Content-Type头
• 使用CloudFront的URL替代S3预签名URL，无需额外签名（或使用CloudFront签名URL，兼容性更好）

验证步骤 #

1. 生成预签名URL后，直接在浏览器中打开，确认音频可正常下载
2. 检查S3控制台中文件的Content-Type是否为audio/mpeg
3. 查看WhatsApp API的响应日志，确认是否存在未被捕获的错误信息

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