本文详解如何通过 whatsapp cloud api 的媒体端点获取图片 url，并正确下载二进制图像文件，重点解决因 user-agent 限制导致的“something went wrong”错误。
本文详解如何通过 whatsapp cloud api 的媒体端点获取图片 url，并正确下载二进制图像文件，重点解决因 user-agent 限制导致的“something went wrong”错误。
在使用 WhatsApp Cloud API 接收消息时，若用户发送了图片，Webhook 仅会返回一个 media_id（如 123456789012345），而非原始文件。需分两步完成图片下载：
✅ 第一步：通过 Media ID 获取临时访问 URL
调用 Facebook Graph API 的 /v14.0/{media-id} 端点，传入有效的 Bearer Token，响应中将包含 url 字段——这是一个带签名、限时有效的直链（如 https://lookaside.fbsbx.com/...）。
$token = 'YOUR_TEMPORARY_ACCESS_TOKEN';
$mediaId = '123456789012345';
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://graph.facebook.com/v14.0/{$mediaId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer {$token}",
"Content-Type: application/json"
]
]);
$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($httpCode !== 200) {
throw new Exception("Media fetch failed: HTTP {$httpCode}, Response: {$response}");
}
$data = json_decode($response, true);
if (!isset($data['url'])) {
throw new Exception("No 'url' field in media response");
}
$tempUrl = $data['url']; // e.g., https://lookaside.fbsbx.com/whatsapp_business/...✅ 第二步：下载图片二进制内容（关键！）
⚠️ 注意：此处极易出错。 WhatsApp Cloud API 对该临时 URL 的请求有严格 UA（User-Agent）校验：默认空 UA 或常见浏览器 UA（如 Chrome/Safari）会被拒绝，返回 HTML 错误页（含 “something went wrong”）。官方虽未明文文档化此限制，但实践证实：必须使用 Postman-like 或 WhatsApp 官方 SDK 常用的 UA 才能成功。
✅ 正确做法（核心修复）：
立即学习“PHP免费学习笔记（深入）”；
- 设置
User-Agent: PostmanRuntime/7.34.0（或其他被接受的 UA，如WhatsApp/2.23.15.75） -
无需 Authorization 头 —— 该临时 URL 已内嵌鉴权参数（
mid,ext,hash），携带 Token 反而可能触发校验失败 - 使用
CURLOPT_BINARYTRANSFER => true确保二进制流不被编码破坏 - 显式设置
CURLOPT_HEADER => false避免响应头混入文件内容
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => $tempUrl,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_BINARYTRANSFER => true, // 关键：确保二进制原样返回
CURLOPT_HEADER => false, // 关键：排除响应头污染
CURLOPT_USERAGENT => 'PostmanRuntime/7.34.0', // ✅ 必须设置有效 UA
// ❌ 不要加 Authorization 头！临时 URL 自含鉴权
]);
$imageData = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($httpCode !== 200 || !$imageData) {
throw new Exception("Image download failed: HTTP {$httpCode}");
}
// 保存为文件（示例）
$extension = pathinfo(parse_url($tempUrl, PHP_URL_PATH), PATHINFO_EXTENSION) ?: 'jpg';
$filename = 'downloaded_image.' . $extension;
file_put_contents($filename, $imageData);
echo "✅ Image saved as {$filename} ({$data['file_size']} bytes, MIME: {$data['mime_type']})";? 补充说明与最佳实践
-
Token 安全性：第一步的
Bearer Token是短期有效的 WhatsApp Business Platform 访问令牌，请勿硬编码或泄露；建议从环境变量读取。 -
MIME 类型验证：下载前可检查
$data['mime_type']（如image/jpeg）以避免处理非预期类型。 -
错误处理增强：生产环境应捕获
curl_error()并记录完整上下文，便于调试网络或权限问题。 -
临时 URL 时效性：
ext参数为 Unix 时间戳，URL 通常 1 小时内有效，务必及时下载。 - 替代方案：若需更高可靠性，可考虑将图片上传至自有存储（如 AWS S3）并保存路径，而非长期依赖临时链接。
遵循以上步骤，即可稳定、安全地从 WhatsApp Cloud API 下载用户发送的图片资源。
