使用WhatsApp Cloud API上传媒体文件遇OAuthException错误求助

问题描述 #

使用PHP 8.1 + CI4框架的cURL代码上传文件到WhatsApp Cloud API时失败，返回如下错误：

"error": {
"message": "An unknown error has occurred.",
"type": "OAuthException",
"code": 1,
"fbtrace_id": "ActSWlPfhEOVpbiN2QmIf7X"
}

原代码如下：

public function meta_upload_media2($token,$phonesid,$tipo,$archivo,$filename)
{

    $ch = curl_init();
    $url = 'https://graph.facebook.com/v18.0/'.$phonesid.'/media';

    $fileFinal=new \CURLFile($archivo,$tipo,$filename);
    
    $data = array(
        'file' => $fileFinal,
        'type' => $tipo,
        'messaging_product' => 'whatsapp'
    );
    $headers = array(); 
    
    $headers[] = 'Authorization: Bearer ' . $token ;

    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    
    $result = curl_exec($ch);        

    if($result === false) {
        $result = curl_error($ch) . " - ".curl_errno($ch);
        //return false;
        
    }else{
        $resultDecode = json_decode($result);
        if($resultDecode!=null){
            $result = $resultDecode;
        }
        return($result);
        //return true;
    }
    curl_close($ch);
}  

排查与修复方案 #

1. 验证文件路径与权限 #

• 确认$archivo指向的文件真实存在，且PHP运行进程（如web服务器用户www-data）拥有该文件及上级目录的读取权限
• 在代码开头增加文件校验逻辑，提前拦截无效文件：

  if (!file_exists($archivo) || !is_readable($archivo)) {
      return (object)['error' => ['message' => '文件不存在或无读取权限']];
  }
  

2. 移除重复的API参数 #

根据WhatsApp Cloud API文档，上传本地文件时：

• type参数为可选，且CURLFile已经通过第二个参数传递了MIME类型，重复传递'type' => $tipo可能引发参数冲突
• 修改请求数据数组，移除重复的type字段：

  $data = array(
      'file' => $fileFinal,
      'messaging_product' => 'whatsapp'
  );
  

3. 验证Token与Phone Number ID有效性 #

• 确认$token是有效的WhatsApp Business API令牌，未过期且拥有whatsapp_business_messaging权限
• 确认$phonesid是正确的Phone Number ID，且与令牌所属的Meta Business Account匹配

4. 开启cURL调试收集详细日志 #

添加调试参数获取完整的请求/响应细节，便于定位深层问题：

// 开启cURL verbose模式
curl_setopt($ch, CURLOPT_VERBOSE, true);
$verboseLogFile = fopen('php://temp', 'w+');
curl_setopt($ch, CURLOPT_STDERR, $verboseLogFile);

// 在curl_exec后读取调试日志
if($result === false) {
    rewind($verboseLogFile);
    $verboseContent = stream_get_contents($verboseLogFile);
    fclose($verboseLogFile);
    $result = curl_error($ch) . " - ".curl_errno($ch) . "\n调试日志：".$verboseContent;
}

修正后的完整代码 #

public function meta_upload_media2($token,$phonesid,$tipo,$archivo,$filename)
{
    // 前置文件校验
    if (!file_exists($archivo) || !is_readable($archivo)) {
        return (object)['error' => ['message' => '文件不存在或无读取权限']];
    }

    $ch = curl_init();
    $url = 'https://graph.facebook.com/v18.0/'.$phonesid.'/media';

    $fileFinal = new \CURLFile($archivo, $tipo, $filename);
    
    $data = array(
        'file' => $fileFinal,
        'messaging_product' => 'whatsapp'
    );
    
    $headers = array(
        'Authorization: Bearer ' . $token
    );

    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    
    // 开启调试模式（可选，排查时启用）
    curl_setopt($ch, CURLOPT_VERBOSE, true);
    $verboseLogFile = fopen('php://temp', 'w+');
    curl_setopt($ch, CURLOPT_STDERR, $verboseLogFile);
    
    $result = curl_exec($ch);        

    if($result === false) {
        rewind($verboseLogFile);
        $verboseContent = stream_get_contents($verboseLogFile);
        fclose($verboseLogFile);
        $result = curl_error($ch) . " - ".curl_errno($ch) . "\n调试日志：".$verboseContent;
    } else {
        $resultDecode = json_decode($result);
        if($resultDecode !== null){
            $result = $resultDecode;
        }
    }
    curl_close($ch);
    return $result;
}

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