企业微信二次开发：用 sendText 做外部群工单播报

文档里的发送纯文本接口只做一件事：给某个 userId 或 roomId 发一句字。工单进度播报不是新接口，是业务事件来了之后，反复调用这一条。

接口形态固定：

方法：/msg/sendText
必填：guid、toId、content、isNoNeedRead
toId：私聊填联系人 userId，群聊填 roomId

下面把工单系统接到这条接口上。

功能怎么从接口长出来

工单状态变更（新建、处理中、待客户确认、完成）在业务库里已经有了。缺的是「写到客户所在的外部群」。映射只有三列：

工单ID → 客户ID → 外部群 roomId → 发送用的 guid

状态机每走一步，拼一句人话，调一次 /msg/sendText。不要为「播报」再封装一套群协议，协议层已经在接口里。

复制代码

{
  "method": "/msg/sendText",
  "params": {
    "guid": "该交付群对应的设备ID",
    "toId": "该客户外部群roomId",
    "content": "工单 #1024 状态：处理完成。如需补充材料请在本群回复。",
    "isNoNeedRead": true
  }
}

isNoNeedRead 按场景取：进度通知一般 true，避免群里一堆已读回执；需要确认客户看到再跟进时再改 false。不要每条都当成已读回执去实现对账，对账用你自己的发送日志。

成功只认：code 为 0 且 data.isSendSuccess 为 1。此时把 msgServerId、msgUniqueIdentifier 和工单号写进同一行日志，后面要对账或撤回才有依据。

发送前必须挡住的三种错

toId填成客户个人 ID。 接口会当私聊发出去，群里没有这条进度。播报场景 toId 只能是群 roomId。
guid不是还在该群里的账号。 多客服时尤其容易写死一台设备。发送前用该 guid 调 /room/getRoomList（或查你自己的校准表），列表里没有这个群就不要发。
同一状态推两次。 工单系统重试、MQ 重复消费都会发生。键用 工单ID + 状态值，占坑成功才调用发送；超时未确认不要立刻再发同样文案。

文案里带工单号，方便群里搜索。不要在 content 里塞文件二进制。需要 PDF 时另走发送文件接口，本功能只负责状态句。

和收消息怎么衔接

播报是出站。客户在群里回「已确认」是入站，走回调，不走 /msg/sendText。接口主动发出的内容不会再进回调，所以不要等回调来证明「群里出现了这句话」，以发送响应为准。

客户回复要关单，另做：回调入队 → 识别工单号 → 改工单状态。那是第二条链路，不要塞进发送函数。

Header 仍是 X-QIWEI-TOKEN，Body 仍是 method + params。工单服务只持有 Token、guid、roomId 对照表，不解析企微客户端协议。

上线时怎么验

用测试外部群绑一张测试工单。工单从「处理中」改到「完成」，群里只应出现一条对应文本。把工单服务重启再灌一次同一状态，群里不应再多一条。把 guid 换成未入该群的设备，请求应在你自己的校验层被拒绝，而不是把错误丢给接口再猜。

字段以发送纯文本接口文档为准，不要给 params 增加文档没有的键。