PHP调用WhatsApp Business Cloud API下载媒体返回空串及500错误

问题现象 #

成功获取媒体URL并存入$mediaURL变量用于文件请求后，调用PHP cURL执行媒体下载操作时返回空字符串；使用Postman发起完全相同的请求，接口返回500内部服务器错误。

现有实现代码 #

self::writeLog('Media URL: '.$mediaURL);
self::writeLog('Preparing to download media - id: '.$media_id);

$curl = curl_init($mediaURL);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

$headers = array(
    "Authorization: Bearer ".self::$auth_token,
);

curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);

if (($resp = curl_exec($curl)) === false) {
    self::writeLog('cURL Error: '.curl_error($curl));
} else if ($resp == '') {
    self::writeLog('Empty string.');
    self::writeLog('URL: '.$mediaURL);
    self::writeLog('Headers: '.$headers[0]);
} else {
    self::writeLog($resp);
}

• 代码中writeLog为自定义方法，作用是将各类日志信息写入txt文件。

排查与修复步骤 #

1. 补充状态码和响应头日志定位根因 #

现有代码没有采集HTTP响应状态和返回头，无法判断500错误的具体触发原因，先添加以下配置采集完整信息：

// 开启响应头采集
curl_setopt($curl, CURLOPT_HEADER, true);
// 请求执行后打印HTTP状态码
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
self::writeLog('HTTP Status Code: '.$httpCode);

拿到状态码和完整响应内容后，先区分是接口侧权限校验失败、参数缺失，还是请求格式不符合要求触发的服务端错误。

2. 补全常规cURL配置避免被拦截 #

当前代码缺少大部分接口默认要求的请求配置，很容易被服务端拦截触发500错误，补充以下配置：

// 配置常规UA，模拟浏览器请求避免被反爬/防盗链拦截
curl_setopt($curl, CURLOPT_USERAGENT, 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36');
// 开启自动跟随跳转，多数媒体资源URL会做3xx跳转
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
// 设置合理超时时间，避免大文件下载中途被截断
curl_setopt($curl, CURLOPT_TIMEOUT, 30);
// 补充常规请求头
$headers[] = "Accept: */*";
$headers[] = "Accept-Encoding: gzip, deflate, br";

3. 校验请求基础参数合法性 #

• 打印完整$mediaURL确认地址无异常，路径中存在中文或特殊字符时，需要对路径部分做urlencode()转义处理
• 校验self::$auth_token有效性，确认token未过期、格式正确，Bearer和token值之间的空格不能遗漏
• 如果资源配置了防盗链，需要在headers中补充对应Referer地址

4. 对齐Postman请求配置 #

将Postman中可正常触发请求的配置导出为cURL代码，和现有代码逐项对比头字段、请求方法、参数传递的差异，补全缺失的配置项即可。

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