erpnew/docs/MESSAGE_API.md

消息发送 API

这组 API 用于对外主动发送企业微信应用消息。

当前提供两个接口：

• POST /api/message/send：发送文本消息
• POST /api/message/send/news：发送单篇图文消息，可同时投递到多个 agent_id

鉴权

仅这组消息发送 API 需要固定 Authorization 请求头。

服务端读取环境变量：

• MESSAGE_API_AUTHORIZATION

默认值：

• hophopkk

请求示例：

Authorization: hophopkk
Content-Type: application/json

鉴权失败时返回：

{
  "detail": "Invalid Authorization header"
}

HTTP 状态码：401 Unauthorized

发送文本消息

请求

POST /api/message/send

{
  "agent_id": 1000007,
  "content": "库存盘点将在 18:00 开始",
  "user_ids": ["zhangsan", "lisi"]
}

字段说明：

字段	类型	必填	说明
agent_id	integer	是	企业微信应用 ID
content	string	是	文本内容，1-2048 字节
user_ids	string[]	否	接收用户 UserID 列表；为空时发送给应用可见范围内全部成员

成功响应

{
  "errcode": 0,
  "errmsg": "ok"
}

curl 示例

curl -X POST 'http://localhost:8198/api/message/send' \
  -H 'Authorization: hophopkk' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": 1000007,
    "content": "库存盘点将在 18:00 开始",
    "user_ids": ["zhangsan", "lisi"]
  }'

发送图文消息

请求

POST /api/message/send/news

{
  "agent_ids": [1000007, 1000008],
  "title": "销售日报",
  "description": "点击查看今日各区域销售汇总",
  "url": "https://example.com/reports/daily-sales",
  "image_url": "https://example.com/static/daily-sales-cover.png",
  "user_ids": ["zhangsan"]
}

字段说明：

字段	类型	必填	说明
agent_ids	integer[]	是	目标应用 ID 列表，至少 1 个
title	string	是	图文标题，1-128 字符
description	string	是	图文描述，1-512 字符
url	string	是	点击跳转链接
image_url	string	是	封面图片 URL，直接映射到企业微信 picurl
user_ids	string[]	否	接收用户 UserID 列表；为空时发送给应用可见范围内全部成员

成功响应

至少一个 agent_id 发送成功时返回 200，并带每个应用的发送结果：

{
  "results": [
    {
      "agent_id": 1000007,
      "ok": true,
      "response": {
        "errcode": 0,
        "errmsg": "ok"
      },
      "error": null
    },
    {
      "agent_id": 1000008,
      "ok": false,
      "response": null,
      "error": "agent not found"
    }
  ]
}

如果所有 agent_id 都失败，则返回 502 Bad Gateway：

{
  "detail": "All agent sends failed"
}

curl 示例

curl -X POST 'http://localhost:8198/api/message/send/news' \
  -H 'Authorization: hophopkk' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_ids": [1000007, 1000008],
    "title": "销售日报",
    "description": "点击查看今日各区域销售汇总",
    "url": "https://example.com/reports/daily-sales",
    "image_url": "https://example.com/static/daily-sales-cover.png",
    "user_ids": ["zhangsan"]
  }'

发布建议

• 如果要对外给第三方系统调用，至少同步交付这份文档和环境变量名 MESSAGE_API_AUTHORIZATION
• 当前是固定密钥模式，适合内网或受控系统对接，不适合开放互联网暴露
• 如果后续要接入更多对外方，建议升级为签名、时间戳或短期 token 模式