企业微信 API 开发手册（qiyeweixin-api）

用 HTTP 接口操作企业微信：发消息、管外部群、收事件回调。本手册按「常见任务」组织，照着抄就能跑，示例用 Python。

官网 https://wecomapi.com · 接口文档 https://post.wecomapi.com · 控制台 https://manager.wecomapi.com

---

目录

• 一、接入准备
• 二、调用约定
• 三、常见任务
• 四、接口速查
• 五、常见问题

一、接入准备

1. 在控制台注册、创建 Token；
2. 扫码登录企业微信账号（登录托管），记下账号的 guid（一个账号 = 一个 guid）。

二、调用约定

所有接口统一：

• 方法：POST /api/qw/doApi
• 请求头：<鉴权Token头>: <Token>
• 请求体：{"method": "<方法>", "params": {"guid": "<账号>", ...}}
• 成功：code == 0

一个 Python 封装（下面都用它）：

import requests

GATEWAY = "https://<网关地址>"
TOKEN_HEADER = "<鉴权Token头>"   # 字段名见文档
TOKEN = "<你的Token>"
GUID = "<账号实例ID>"

def call(method, **params):
    params.setdefault("guid", GUID)
    r = requests.post(f"{GATEWAY}/api/qw/doApi",
                      headers={"Content-Type": "application/json", TOKEN_HEADER: TOKEN},
                      json={"method": method, "params": params}, timeout=15)
    return r.json()

三、常见任务

给外部群发一条消息（toId 填群 ID）

call("/msg/sendText", toId="<外部群ID>", content="hello", isNoNeedRead=False)

图片 / 链接 / 小程序换方法：/msg/sendImage、/msg/sendLink、/msg/sendWeapp。

建一个外部群并拉人

res = call("/room/createRoom", memberList=["userId1", "userId2"])
room_id = res["data"]["roomId"]

改群名 / 设群公告

call("/room/modifyRoomName", roomId=room_id, name="VIP 客户群")
call("/room/modifyRoomNotice", roomId=room_id, notice="欢迎加入，有问题随时反馈")

接收消息与事件（回调）

控制台配 HTTPS 回调地址，企业微信侧会推过来。最小 Flask 示例：

from flask import Flask, request
app = Flask(__name__)
seen = set()

@app.post("/callback")
def cb():
    body = request.get_json(force=True, silent=True) or {}
    for it in body.get("data", []):
        key = it.get("seq") or it.get("msgUniqueIdentifier")
        if key in seen:          # 幂等去重
            continue
        seen.add(key)
        cmd = it.get("cmd")
        if cmd == 15000:
            print("会话消息", "群聊" if it.get("fromRoomId") else "私聊", it.get("msgType"))
        elif cmd == 15500:
            print("系统事件（群成员进出 / 群变更等）")
    return "ok"                  # 必须 3 秒内回 200

撤回一条消息

call("/msg/revokeMsg", chatId="<会话ID>", msgServerId="<消息ID>")

四、接口速查

模块	方法
消息 /msg/*	sendText / sendImage / sendVideo / sendFile / sendLink / sendWeapp / revokeMsg
外部群 /room/*	createRoom / batchGetRoomDetail / modifyRoomName / modifyRoomNotice / getRoomQrCode / inviteRoomMember / removeRoomMember / roomAddAdmin / changeRoomMaster / dismissRoom
联系人 /contact/* · 朋友圈 /sns/* · 云存储 /cloud/* · 登录 /login/*	详见在线文档

回调 cmd：11016 设备状态 · 15000 会话消息 · 15500 系统事件 · 20000 异步回执。

五、常见问题

Q：给群发消息，toId 填什么？ 填群 ID（roomId）；给个人填对方 ID。 Q：回调收不到？ 回调地址要 HTTPS、公网可达，且必须 3 秒内回 200，否则会被判超时重推。 Q：多个企业微信账号怎么管？ 一个账号一个 guid，调用时带上对应 guid 即可。 Q：图片 / 文件消息怎么发？ 先用 /cloud/* 上传拿到文件元数据，再 send。

仅用于客户服务、社群运营等正当场景；完整接口与字段以官方文档 https://post.wecomapi.com 为准。

License

MIT