企业微信外部群消息自动推送实战

电商售后、项目协作、B2B 服务里常见需求：订单状态变了、工单转派了、审批通过了，要给外部客户或外部协作群发一条企微文字 。官方应用消息有场景边界；当业务系统需要「指定外部群 roomId 直接发文本」时，RPA 连接器的 /msg/sendText 是常用接入点。

一次请求对一个目标（一个外部联系人或一个外部群），批量触达在业务层做队列，不是一次 HTTP 打多个群。

调用结构

所有 method 走同一网关，Body 形如：

复制代码

{
  "method": "/msg/sendText",
  "params": {
    "guid": "执行节点ID",
    "toid": "外部用户ID 或 外部群 roomId",
    "content": "通知正文"
  }
}

Header 携带 API Token。成功一般 code: 0。

发个人 vs 发外部群

发给外部联系人：toid 填外部用户 ID。
发给外部群：toid 填 roomId，且 guid 对应账号已在该群内。

和业务系统怎么接

复制代码

工单/订单服务 ──事件──► 通知服务 ──队列──► 调 sendText ──► 外部群或客户

CRM、ERP 抛 Webhook 或消息队列事件，通知服务查 roomId / 用户 ID，渲染模板后调用 API。成功后再写业务侧「已通知」记录。

操作步骤

控制台获取 Token，登录执行节点，确认在线。
从群列表或业务库拿到目标 roomId（外部群）或外部联系人 ID。
用 curl 发一条测试通知，群内或私聊肉眼确认。
封装 send_text(guid, toid, content) 供业务调用。
工单状态变更时触发；失败进重试队列。
大流量场景 worker 间隔 3～5 秒，记录每次 code 与耗时。

示例代码

python 复制代码

curl -X POST http://你的网关地址/qw/doApi \
  -H "X-API-TOKEN: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "/msg/sendText",
    "params": {
      "guid": "你的节点ID",
      "toid": "1081449970753",
      "content": "【工单通知】您的服务单 #8821 已受理，预计 2 小时内响应。"
    }
  }'

python 复制代码

import os
import requests

GATEWAY = os.environ["QW_GATEWAY"]
TOKEN = os.environ["QW_API_TOKEN"]

def send_text(guid: str, toid: str, content: str) -> dict:
    return requests.post(
        f"{GATEWAY}/qw/doApi",
        json={
            "method": "/msg/sendText",
            "params": {"guid": guid, "toid": toid, "content": content},
        },
        headers={"X-API-TOKEN": TOKEN, "Content-Type": "application/json"},
        timeout=15,
    ).json()

def on_ticket_created(ticket):
    room_id = crm.get_customer_room(ticket.customer_id)
    if not room_id:
        return
    tpl = "【工单 #{id}】已创建，类别：{category}。"
    content = tpl.format(id=ticket.id, category=ticket.category)
    resp = send_text(os.environ["QW_GUID"], room_id, content)
    ticket.log_notify(resp)

注意

返回非 0 时先查节点在线、Token 有效、toid 是否正确。
外部群 roomId 与内部群、用户 ID 不要混用。
短时间大量相同文案仍有风控风险，内容尽量带变量（单号、姓名）。
客户未授权营销类消息时不要自动推送。
保留发送日志，客诉时可追溯。

文档

API 文档 · 消息发送 · 官网平台

标签建议： 企业微信、外部群、消息推送、工单通知