400错误主因是userid错误或access_token配置不当:必须用管理后台的精确userid(非邮箱/手机号),且corpid与应用secret需匹配;消息发送成功但收不到则需检查应用可见范围和用户通知设置。

curl 发送应用消息时 400 错误:invalid user 或 user not exist
企业微信 API 对用户 ID 校验极严,传错一个字母、大小写不匹配、或用了邮箱/手机号而非 userid,都会直接报这个错。不是接口调不通,是企微服务器当场拒绝。
- 必须用成员在「管理后台 → 成员管理」里看到的
userid(如ZhangSan),不能用姓名、邮箱、手机号代替 - 如果用户是通过 API 批量导入的,确认导入时是否设置了
userid字段;没设的话默认为空,后续无法推送 - 测试前先用
https://qyapi.weixin.qq.com/cgi-bin/user/get?access_token=xxx&userid=xxx手动查一次,看返回是否含"errcode":0和正确姓名 - 多个用户用英文逗号拼接:
"touser":"ZhangSan,WangWu",注意不能有空格、中文逗号、换行
获取 access_token 失败:corpid 和 corpsecret 对不上
企微的 access_token 不是全局通用的,它绑定具体应用(AgentId)和企业(CorpId)。常见问题是把「应用 Secret」当成「企业 Secret」,或者填反了。
-
corpid是企业 ID(16 位字符串,形如wwe1234567890abc),在「我的企业 → 企业信息」页最底下 -
corpsecret必须是目标应用的「Secret」(不是企业的总 secret),在「应用管理 → 自建应用 → 进入应用 → Secret」里复制 - 请求地址必须是:
https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=xxx&corpsecret=xxx,少一个参数或拼写错误(比如写成corp_secret)都会返回{"errcode":40013,"errmsg":"invalid corpid"} - access_token 有效期 2 小时,别每次发消息都重新取;建议缓存到文件或 Redis,失效后再刷新
发送文本消息的最小可行代码:绕过 SDK 直接用 curl
很多 PHP 项目不想引入 SDK,其实几行 curl 就够用。关键不是“怎么发”,而是“怎么确保字段不漏、格式不崩”。
- 消息体必须是 JSON,且
Content-Type: application/json; charset=utf-8,漏掉 charset 容易导致中文乱码 -
agentid是数字(不是字符串!),从应用详情页复制过来后检查有没有引号包着 - 完整示例(替换
ACCESS_TOKEN、AGENTID、USERID后可直接运行):
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=ACCESS_TOKEN');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'touser' => 'USERID',
'msgtype' => 'text',
'agentid' => AGENTID,
'text' => ['content' => "你好,这是一条测试消息"],
'safe' => 0
], JSON_UNESCAPED_UNICODE));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json; charset=utf-8']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
消息发出去了但用户收不到:检查「应用可见范围」和「接收人权限」
API 返回 {"errcode":0,"errmsg":"ok"} 只代表企微服务器接受了请求,不代表用户真能收到。最常被忽略的是后台配置。
- 进「应用管理 → 编辑应用 → 可见范围」,确认目标用户或部门已被勾选;未加入范围的用户,哪怕
userid正确也收不到 - 用户个人设置里可能关闭了该应用的消息通知(手机端「我 → 设置 → 新消息通知 → 应用消息」),这个没法用 API 控制
- 如果是给部门发(
touser留空 +toparty),注意部门 ID 是数字,且需确认该部门在应用可见范围内 - 测试时优先用管理员账号的
userid,避免权限干扰
企微 API 的坑不在代码多难写,而在每个字段背后都连着后台的一个开关、一个配置项、一个 ID 类型限制。少点一次「确定」,就可能卡住一整天。
大量免费API接口:立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游,为数据API应用能力赋能!











