通用消息接口

通用接口允许业务系统选择已授权的公众号通道，发送模板通知或客服文本。固定的 CRM 客户跟进场景可使用字段更简洁的 CRM 专用接口。

地址与鉴权

https://14.103.113.229

当前 IP 入口使用自签名证书。请从管理员取得并信任服务器证书，例如在 cURL 中使用 --cacert ./pushmsg-server.crt。

同时携带调用系统的 Key 和 Secret：

X-API-Key: YOUR_BUSINESS_API_KEY
X-API-Secret: YOUR_BUSINESS_API_SECRET
Content-Type: application/json

Key 也支持 Authorization: Bearer YOUR_BUSINESS_API_KEY，仍须提供 X-API-Secret。调用系统必须拥有目标 channelId 权限，且 openId 已由管理员绑定到该系统及通道。未授权接收人返回 403 RECIPIENT_FORBIDDEN，不会入队；新系统默认没有接收人权限。

授权按系统、通道和区分大小写的 OpenID 精确匹配。发送前队列再次校验权限，撤销后未开始发送的任务会被阻止。其他系统不能使用未分配给自己的接收人，也不能查询本系统消息。

提交模板消息

POST /api/v1/messages

以下示例使用已配置的“收到工单通知”模板。修改业务请求标识、接收人和工单内容后提交。

{
  "requestId": "workorder-WO20261026001-created",
  "channelId": "xianbao",
  "type": "TEMPLATE",
  "openId": "YOUR_OPENID",
  "templateId": "6UZkNMe8nSjxoX1GX2pVlcD2CxzpaQajDo6mnSF2bkg",
  "url": "https://crm.example.com/workorders/WO20261026001",
  "data": {
    "thing4": {"value": "测试工单"},
    "character_string11": {"value": "WO20261026001"},
    "character_string2": {"value": "CRM20261026001"}
  }
}

data 中的字段名以英文字母开头，后续可包含字母、数字、下划线，最长 64 字符。每项接受字符串简写或包含字符串 value 的对象，value 最长 500 字符。微信对 thing、电话等字段类型的更细限制仍由微信接口校验。

{
  "thing4": "测试工单",
  "character_string11": {"value": "WO20261026001"},
  "character_string2": {"value": "CRM20261026001"}
}

字段名必须与该模板的内容一致，映射表见 微信模板。模板 ID 从账号已添加的“我的模板”读取。

cURL 示例

将完整请求保存为 message.json：

export PUSHMSG_API_KEY='YOUR_BUSINESS_API_KEY'
export PUSHMSG_API_SECRET='YOUR_BUSINESS_API_SECRET'

curl --fail-with-body --cacert ./pushmsg-server.crt \
  'https://14.103.113.229/api/v1/messages' \
  -H "X-API-Key: $PUSHMSG_API_KEY" \
  -H "X-API-Secret: $PUSHMSG_API_SECRET" \
  -H 'Content-Type: application/json' \
  --data-binary @message.json

提交客服文本

{
  "requestId": "support-CASE20261026001-reply",
  "channelId": "xianbao",
  "type": "TEXT",
  "openId": "YOUR_OPENID",
  "content": "你的服务申请已受理，请在业务系统查看处理进度。"
}

客服文本受微信的账号权限、关注状态和允许互动时限约束。仅获取 OpenID 不能获得无限期客服发送资格；微信返回 45015 时，需要接收人先在公众号中主动发起符合条件的互动。应用会将明确拒绝记录为 FAILED。

接收响应与幂等

新任务返回 HTTP 202：

{"id":"11111111-2222-4333-8444-555555555555","status":"PENDING","duplicate":false}

去重范围是“当前调用方 + requestId”，请求标识区分大小写。相同内容重复提交返回 HTTP 200、原消息 ID、当前状态和 duplicate:true。同一标识配上不同内容返回 409 IDEMPOTENCY_CONFLICT。

对象字段顺序不影响去重。接收人、模板、数据和详情 URL 等消息内容应在网络重试时保持一致。

查询消息

GET /api/v1/messages/{id}
X-API-Key: YOUR_BUSINESS_API_KEY
X-API-Secret: YOUR_BUSINESS_API_SECRET

当前业务应用只能查询自己创建且仍有渠道权限的消息；其他应用的消息返回 404。

{
  "id": "11111111-2222-4333-8444-555555555555",
  "requestId": "workorder-WO20261026001-created",
  "clientId": "CALLER_ID",
  "channelId": "xianbao",
  "type": "TEMPLATE",
  "openId": "YOUR_OPENID",
  "templateId": "YOUR_TEMPLATE_ID",
  "status": "SENT",
  "attempts": 1,
  "maxAttempts": 5,
  "wechatMessageId": "WECHAT_MESSAGE_ID",
  "lastError": null,
  "createdAt": "2026-10-26T11:00:00",
  "updatedAt": "2026-10-26T11:00:01"
}

SENT 表示微信接受请求，FAILED 表示明确失败，UNKNOWN 表示结果不确定。完整处理方式见 运行维护。

请求限制与错误

请求正文最大 64KB，序列化后的消息 JSON 最长 16000 字符。生产业务入口按来源 IP 限流；当前配置为每秒 20 个请求，允许突发队列 40 个请求。

微信返回的发送错误通常记录在消息的 lastError 中。HTTP 接收成功后仍需查询队列最终状态。