WeComMessager

企业微信自建应用消息发送。支持文本、Markdown、Unicode 表情、静态图片表情、图片、语音、视频和文件；支持不同企业或收件人的多个实例；VPN 开启或关闭时自动尝试可用网络路径。

安装

• 需要 Python 3.9 或更新版本。Windows 和其他系统都可使用；物理网卡备用路径仅在 Windows 上生效。
• 准备企业 ID、自建应用的 Secret 与 AgentID，以及接收人的 UserID。这里要填企业微信成员的 UserID，不是显示昵称。
• 接收人应在应用可见范围内。如果应用设置了企业可信 IP，发送请求使用的出口 IP 也必须在允许范围内。

python -m pip install wecom-messager

快速开始

from WeComMessager import WeComMessenger

with WeComMessenger(
    corp_id="企业 ID",
    corp_secret="自建应用 Secret",
    agent_id=123456,
    user_id="接收人的 UserID",
) as messenger:
    messenger.send_text("任务完成")
    messenger.send_markdown("**任务完成**")
    messenger.send_text("发给另一位成员", to_user="另一位成员的 UserID")

user_id 是默认收件人；to_user 只覆盖本次发送。with 结束时会关闭网络连接。如未使用 with，需调用 messenger.close()。

初始化参数

WeComMessenger(corp_id, corp_secret, agent_id, user_id, *, proxy_url=None, timeout=10)

初始化参数不符合要求时会抛出 ValueError。允许corp_id、corp_secret、agent_id 和 user_id 在不同实例中分别存在。

消息类型与方法

WeComMessenger 实例的方法。成功时返回 True；所有方法都可用 to_user="其他UserID" 指定本次收件人。

path 可以是路径字符串或 pathlib.Path。相对路径以运行程序时的工作目录为准。send_video 的 title 最多 128 个 UTF-8 字节，description 最多 512 个 UTF-8 字节，均可省略。语音时长由企业微信接口判断，超过限制时可能返回错误码 45007。

send_sticker 发送的是静态图片；动态 GIF 可用 send_file("sticker.gif") 作为附件发送。send_emoji 使用文本消息发送 Unicode 表情。

with WeComMessenger("企业 ID", "应用 Secret", 123456, "UserA") as messenger:
    messenger.send_image("C:/private/photo.png")
    messenger.send_voice("C:/private/voice.amr")
    messenger.send_video("C:/private/video.mp4", title="会议录像", description="今日会议")
    messenger.send_file("C:/private/report.pdf", to_user="UserB")

多个实例与单次发送

同一程序可创建两个以上实例，分别对应不同企业、应用或默认接收人：

from WeComMessager import WeComMessenger

with WeComMessenger("企业 A 的 ID", "应用 A 的 Secret", 100001, "UserA") as sender_a:
    with WeComMessenger("企业 B 的 ID", "应用 B 的 Secret", 100002, "UserB") as sender_b:
        sender_a.send_text("给 A 的消息")
        sender_b.send_text("给 B 的消息")

只发送一条文本时，可使用模块级便捷函数：

from WeComMessager import send_text

send_text(
    "任务完成",
    corp_id="企业 ID",
    corp_secret="应用 Secret",
    agent_id=123456,
    user_id="接收人的 UserID",
)

便捷函数还接受可选的 proxy_url，但没有 timeout 或 to_user 参数；需要这些参数时请创建实例。

命令行

命令行从 UTF-8 JSON 文件读取连接参数：

{
    "corp_id": "YOUR_CORP_ID",
    "corp_secret": "YOUR_APP_SECRET",
    "agent_id": 123456,
    "user_id": "YOUR_USER_ID"
}

可选字段为 proxy_url 和 timeout

WeComMessager --config "C:/private/secret.json" "你好"
WeComMessager --config "C:/private/secret.json" --kind markdown "**任务完成**"
WeComMessager --config "C:/private/secret.json" --to-user "UserB" "发给另一位成员"
WeComMessager --config "C:/private/secret.json" --kind image "C:/private/photo.png"
WeComMessager --config "C:/private/secret.json" --kind voice "C:/private/voice.amr"
WeComMessager --config "C:/private/secret.json" --kind video --title "会议录像" --description "今日会议" "C:/private/video.mp4"
WeComMessager --config "C:/private/secret.json" --kind file "C:/private/report.pdf"

或使用

python -m WeComMessager --config "C:/private/secret.json" "你好"

Unicode 表情作为普通文本发送；静态表情图用 --kind image，动态 GIF 附件用 --kind file。退出码 0 表示成功，1 表示发送失败，2 表示配置或参数错误。在 CMD 中执行命令后，可用 echo %ERRORLEVEL% 查看退出码。

错误处理与网络

参数、文件格式或大小不符合要求时抛出 ValueError；接口拒绝或网络发送失败时抛出 WeComError：

from WeComMessager import WeComError, WeComMessenger

try:
    with WeComMessenger("企业 ID", "应用 Secret", 123456, "UserA") as messenger:
        messenger.send_text("任务完成")
except ValueError as exc:
    print(f"参数错误：{exc}")
except WeComError as exc:
    print(f"发送失败：{exc}")
    print(f"企业微信错误码：{exc.code}")  # 网络错误等情况可能为 None
    if exc.delivery_unknown:
        print("送达结果不确定；先向收件人核实，再决定是否重发")
    if exc.partial_delivery:
        print("部分收件人可能已收到；先核对收件情况")

出现 60020 时，请核对企业微信后台的可信 IP 设置。

WeComError.delivery_unknown=True 表示请求是否送达无法确认；程序不会自动重发，以免产生重复消息。partial_delivery=True 表示企业微信报告部分接收人未收到，其他人可能已经收到，也应先核对再重发。

发送时会尝试可用的直连、系统代理及 Windows 上的物理网卡路径；设置 proxy_url 后先尝试指定代理。VPN 开启或关闭都使用同一套接口，但如果 VPN 阻断所有出口，或可用出口都不符合企业可信 IP 设置，仍可能发送失败。

Refenences

• 企业微信发送应用消息
• 企业微信临时素材

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

You are free to use, modify, and distribute this project, including for commercial purposes, provided that:

• You retain the copyright and license notices.
• You distribute modified versions under the same license.
• You make the corresponding source code available as required by the AGPL-3.0, including when modified software is used to provide a network service.

See the LICENSE file for details.

Copyright (c) 2026 Wang Nan