企业微信自动回复怎么实现

先分清：自动回复是四段链路，不是一个开关

「企业微信自动回复怎么实现」在需求里是一句话，落到系统里是四段可以分别替换、也会分别出故障的东西：消息怎么进来（事件回调）、进来之后由谁决定回什么（裁决层）、决定完怎么发出去（发送接口）、以及回错了回重了怎么办（抑制、幂等与转人工）。把这四段混成一件事，就容易得出「上了 AI 自动回复就好了」这种结论，而线上真正出问题的往往是第一段和第四段。

裁决层内部才是常说的三档。它们不是从低到高的升级路线，而是三种不同的输入：关键词规则看消息文本，场景触发看会话状态与时间，AI 生成看语义与上下文。站内另有一篇专门对比这三档的适用边界、真实成本与各自的失效方式，也点出了自动回复最常见的线上事故 —— 关键词服务和 AI 服务各订阅一遍同一批消息，客户收到两条回复。

• 关键词规则：意图能穷举、话术固定、答错代价小的走这一档，命中即定，回什么完全可预测。
• 场景触发：由状态和时间驱动，与客户说了什么无关，比如新客加上后的欢迎语、非服务时段的离线告知。
• AI 生成：只处理前两档没覆盖到的开放式提问，回什么事前不可预测，必须配兜底与转人工。

动手前要备齐的五件事

这五件缺一件，后面的步骤都会卡住，而且通常卡在很难定位的地方。

• 一个在线的账号实例。wecomapi 提供扫码登录、会话保活与实例隔离，多条业务线建议分开跑；开工前先在控制台 https://console.wecomapi.com 确认实例状态是在线。
• 一个公网可达的回调地址，用来接收消息事件。事件回调支持签名校验、投递重试与死信观测，签名校验第一版就要打开，不要留到以后。
• 一份调用凭据。所有接口共用 Authorization: Bearer 这一套鉴权，密钥在控制台创建与轮换。
• 一份初版词表与话术。先把最近一周的真实会话捞出来统计意图分布，再决定哪些进关键词、哪些留给模型，而不是凭想象写词。
• 一处能持久化的状态存储。会话最后活跃时间、抑制窗口、幂等键都要落盘，用进程内的内存变量存，重启一次全丢。

分六步实施

1. 1先打通出口。不接回调，直接手动调一次发送接口，content 写死。判据有两条：响应体是 { "code": 0, "msg": "success" }，以及手机上真的收到了那条消息。只看响应不看设备，会漏掉实例掉线这类问题。
2. 2再打通入口。把回调地址配好，用一个测试账号给实例发一条消息，看回调服务有没有收到、验签是否通过。判据是日志里出现这条事件，并且你能从报文里稳定取出发送方标识与文本内容。
3. 3串成最小闭环。收到任意消息就回一句固定话术。这一步的判据是端到端时延：从发出到收到回复应当在秒级，超过十几秒说明回调处理里混进了同步慢依赖。
4. 4加裁决层。按「用户明确要人 → 敏感规则硬命中 → 关键词 → 场景触发 → AI 兜底 → 都不命中就沉默」排成一条链，命中即返回，不再往下走。默认沉默比默认乱答安全得多。
5. 5加抑制与幂等。同一会话在窗口内只发一次同类话术；每条事件按唯一键去重，避免重复投递变成重复回复。
6. 6加转人工与留痕。每条自动回复至少记三个字段：命中了哪条规则、走的哪一档、发送响应头里的 x-request-id。缺了它们，后面所有排障都只能靠猜。

架构与数据流：谁调谁，状态存哪

数据流是单向的：事件回调 → 队列 → 裁决 → 发送接口。不要有回边，尤其不要在裁决层里反过来触发新的事件消费。

• 回调 handler 只做验签、落库、入队三件事，然后立刻返回 2xx。裁决和发送都不在 handler 里同步做 —— 你在里面多查一次数据库，就多一次超时重投的机会。
• 状态分三处放：会话状态（最后活跃时间、是否已转人工、是否在抑制窗口内）放持久化的键值存储；词表与话术模板放配置，改它不该发版；调用留痕落日志库。
• 重试的责任只在发送这一段。裁决层不重试 —— 同一条消息重算两遍可能得到两个答案，AI 那一档尤其明显。发送失败按错误类型决定重试还是丢弃。
• 幂等键必须带上消费者身份。同一条消息事件常常同时喂给自动回复、会话归档、CRM 同步三个处理器，共用一个键会让后两个被当成重复直接丢掉。重复投递为什么必然发生、去重窗口按什么定，站内另有一篇讲得更细。

async function decide(evt) {
  const text = textOf(evt);
  if (wantsHuman(text) || hitSensitive(text)) return { action: "handoff" };

  const kw = matchKeyword(text);
  if (kw) return { action: "reply", content: kw };

  const scene = matchScene(evt);                       // 欢迎语、非服务时段等
  if (scene) return { action: "reply", content: scene };

  const ai = await withTimeout(llm.answer(evt), 3000); // 超时上限必须有
  return ai?.confident ? { action: "reply", content: ai.text } : { action: "handoff" };
}

// 全流程唯一真正发消息的地方
async function reply(guid, toId, content) {
  const res = await fetch("https://manager.wecomapi.com/message/sendText", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ guid, toId, content }),
  });

  // 排障要的两个信息在响应头上，不在响应体里
  log({
    requestId: res.headers.get("x-request-id"),
    remaining: res.headers.get("x-ratelimit-remaining"),
  });
  return res.json();  // { "code": 0, "msg": "success" }
}

错误处理与排障

自动回复的线上问题只有两种形态：该回的没回，和回错了或回重了。前者是链路断在某一段，后者是裁决或抑制的问题。定位断点的顺序是固定的，按下面五步走，不要跳。

1. 1出口有没有被调用。查留痕里这条会话有没有发送记录。没有，说明问题在回调或裁决，继续往上游查，别在发送接口上耗时间。
2. 2调用了但没成功。看响应体的 code 是不是 0。非 0 说明请求被接口拒绝，带上响应头的 x-request-id 就足以定位这一次调用；具体错误码的含义以线上接口文档为准。
3. 3code 是 0 但客户没收到。先在控制台看账号实例是否仍在线，再确认 toId 是不是当前实例的会话对象 —— 换过实例、会话对象对不上，是这一类的高频原因。
4. 4时好时坏。看 x-ratelimit-remaining 的走势。它在高峰期贴近 0，说明自动回复被自己的批量任务挤掉了，要把两者分开限速：回复是有人在等的，批量不是。
5. 5回重了。先查幂等键是不是漏了消费者身份，再确认是不是有两套监听同时在跑 —— 后者在灰度期特别容易发生。

还有三个最贵的误判值得单独记住。

• 把「结果未知」当成失败。网络超时时你并不知道消息发出去没有，无脑重试会让客户收到两条。这类的正确反应是先查后补，不是直接重发。接口报错按「该做什么」而不是按码值分类，站内另有一篇专门讲这四类怎么分。
• 把回调处理里的异常直接抛出去。返回非 2xx 会触发重投，而副作用很可能已经发生了，重投等于再做一遍。
• AI 那一档不设超时上限。一条消息卡住整个消费者，表现出来是「所有人都收不到回复」，排查时却很容易先去怀疑发送接口。

怎么算做对了：六条可观察的判据

「跑起来了」不是判据。下面六条都能被观察到，上线前后各测一遍，测不过就是没做完。

• 端到端时延：从客户消息到达到回复送达，P95 在秒级。这个数变大，第一个该怀疑的是回调处理里混进了同步调用。
• 同一会话不刷屏：同一客户连发五条相同的问题，只应收到一条同类话术，或按抑制窗口收到有限的几条，不是五条。
• 重放不产生第二次副作用：手动把同一条事件重投一次，留痕里应当仍然只有一次发送记录。
• 沉默率是被看见的：什么都不命中时不回复是对的，但这个比例要有数、要有人看。它持续走高，说明词表跟不上真实问法了。
• 转人工可达：连说三次「转人工」，应当在一轮之内停止自动回复并交接，而不是继续挽留。
• 每条回复都可追溯：任取昨天的一条自动回复，能说清它命中了哪条规则、走的哪一档、对应哪个 x-request-id。说不清就是留痕没落地。

curl -i -X POST https://manager.wecomapi.com/message/sendText \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"guid":"7db8...","toId":"78813...","content":"自检消息"}'

# 响应体  { "code": 0, "msg": "success" }
# 响应头  x-request-id            记进日志，排障凭它定位单次调用
# 响应头  x-ratelimit-remaining   剩余额度，贴近 0 就该分开限速