Facebook Meta cURL转PHP实现及接口报错排查

安全阿岳

2026-8-28

问题根因

代码存在两个明确问题，对应报错和功能异常：

字段拼写错误：template数组下的键名误写为languauge（多了1个字母u），官方接口要求的正确键名是language，这就是返回(#100) Unexpected key "languauge"错误的直接原因。
缺失鉴权请求头：原cURL请求携带的Authorization: Bearer ACCESS_TOKEN头没有在PHP代码中配置，会导致接口鉴权不通过，无法正常调用。
兼容优化项：未显式指定请求方法为POST，虽然传了CURLOPT_POSTFIELDS时多数环境会自动识别为POST请求，显式配置可以避免不同环境下的兼容问题。

正确可运行代码

// 替换为你自己的配置项
$whatsappPhoneNumberId = "你的FROM_PHONE_NUMBER_ID";
$accessToken = "你的接口ACCESS_TOKEN";
$toPhoneNumber = "接收消息的手机号，格式为国家代码+号码，例：8613800138000";

$endpoint = "https://graph.facebook.com/v12.0/".$whatsappPhoneNumberId."/messages";

// 配置请求头，补全鉴权字段
$headers = [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $accessToken
];

// 请求体，修正language字段拼写
$bodyFields = [
    "messaging_product" => "whatsapp",
    "to" => $toPhoneNumber,
    "type" => "template",
    "template" => [
        "name" => "hello_world",
        "language" => [
            "code" => 'en_US',
        ]
    ],
];

$cUrl = curl_init($endpoint);
curl_setopt($cUrl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($cUrl, CURLOPT_POST, true); // 显式指定POST请求
curl_setopt($cUrl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($cUrl, CURLOPT_POSTFIELDS, json_encode($bodyFields));
// 生产环境建议开启SSL校验，本地调试如果有证书问题可临时设为false
curl_setopt($cUrl, CURLOPT_SSL_VERIFYPEER, true);

$response = curl_exec($cUrl);
// 捕获cURL层错误
if(curl_errno($cUrl)){
    $error = curl_error($cUrl);
    // 按需处理错误，比如打印日志
}
curl_close($cUrl);

// 处理返回结果，转数组方便读取
$result = json_decode($response, true);

注意事项

Access Token需要拥有WhatsApp消息发送的对应权限，测试阶段可以使用Meta开发者平台生成的测试Token，生产环境建议使用长期有效Token。
测试环境发送消息时，接收手机号必须提前添加到Meta开发者平台的测试号码白名单中，否则会返回权限错误。
所有请求字段的拼写、大小写必须严格和官方接口定义一致，任意字段名错误都会返回100参数错误。
接口返回的$response是JSON字符串，用json_decode转成数组后可以更方便判断发送结果、错误码等信息。

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