Python 创建和交互企业微信群机器人的教程

hiquant

于 2025-04-10 13:12:46 发布

阅读量1k

点赞数 16

文章标签： python 交互企业微信

本文链接：https://blog.csdn.net/zhangyunchou2015/article/details/147116568

版权

这是一份关于如何使用 Python 创建和交互企业微信群机器人的教程。

企业微信群机器人简介

企业微信允许在内部群聊中添加机器人（Bot），这些机器人可以通过接收特定格式的 HTTP POST 请求（Webhook）来发送消息到群里。这使得我们可以通过编程（例如使用 Python）自动发送通知、报告、提醒等到指定的企业微信群。

核心步骤

在企业微信群中添加机器人并获取 Webhook 地址。
使用 Python 编写代码，向该 Webhook 地址发送 HTTP POST 请求。
根据企业微信机器人 API 的要求，构造不同类型的消息（文本、Markdown、图片等）。

教程详解

第一步：在企业微信群中创建机器人并获取 Webhook 地址

选择群聊： 在你的企业微信客户端（PC 或移动端）中，选择你想要添加机器人的那个内部群聊。
添加机器人：
- PC 端： 点击群聊右上角的 “…” 图标 -> 选择 “添加机器人” -> 选择 “新创建一个机器人”。
- 移动端： 点击群聊右上角的群成员/设置图标 -> 选择 “群机器人” -> 点击 “添加机器人”。
设置机器人： 给你的机器人起一个名字，（可选）设置一个头像。
获取 Webhook 地址： 创建成功后，你会看到一个 Webhook地址。这个地址非常重要，相当于机器人的唯一标识和通信入口，请务必复制并妥善保管，不要泄露给他人。 任何人拿到这个地址都能向你的群聊发送消息。
完成： 点击 “完成”。此时机器人就已经添加到群聊中了。

第二步：准备 Python 环境

你需要安装 requests 库来发送 HTTP 请求。如果尚未安装，可以使用 pip 安装：

pip install requests

第三步：使用 Python 发送消息

企业微信机器人接收的是 JSON 格式的数据。你需要构造符合其规范的 JSON，并通过 POST 请求发送。

1. 发送文本消息 (Text)

这是最简单的消息类型。

import requests
import json

# 1. 替换为你的 Webhook 地址
webhook_url = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_UNIQUE_ROBOT_KEY" # <--- 把这里换成你机器人的实际 Webhook Key

# 2. 构建请求数据（文本类型）
#    参考文档: https://developer.work.weixin.qq.com/document/path/91770#%E6%96%87%E6%9C%AC%E6%B6%88%E6%81%AF
payload = {
    "msgtype": "text",
    "text": {
        "content": "大家好，我是Python机器人！\nHello from Python Bot!",
        # 可以 @ 指定成员 (@all 表示 @所有人)
        # "mentioned_list": ["wangqing", "@all"], # 成员 企业微信帐号列表
        # "mentioned_mobile_list": ["13800001111", "@all"] # 成员 手机号列表 (注意: 手机号必须在企业通讯录内)
    }
}

# 3. 设置请求头
headers = {
    'Content-Type': 'application/json'
}

# 4. 发送 POST 请求
try:
    response = requests.post(webhook_url, headers=headers, data=json.dumps(payload))
    response.raise_for_status() # 如果请求失败 (状态码不是 2xx), 会抛出异常
    # 5. 检查响应结果 (企业微信返回的 JSON)
    result = response.json()
    if result.get("errcode") == 0:
        print("消息发送成功！")
    else:
        print(f"消息发送失败，错误码：{result.get('errcode')}，错误信息：{result.get('errmsg')}")

except requests.exceptions.RequestException as e:
    print(f"请求发送失败：{e}")
except json.JSONDecodeError:
    print(f"无法解析服务器响应：{response.text}")

代码解释:

webhook_url: 替换成你第一步获取到的完整 Webhook 地址。
payload: 一个 Python 字典，包含了要发送的数据。
- msgtype: 指定消息类型，这里是 text。
- text: 包含文本消息具体内容的对象。
  - content: 消息正文，支持换行 (\n)。
  - mentioned_list / mentioned_mobile_list: 可选字段，用于在群里 @ 成员。使用成员的企业微信账号（userid）或已在企业通讯录登记的手机号。@all 可以 @ 所有人。
headers: 设置请求头，指明我们发送的是 JSON 数据。
requests.post(): 发送 POST 请求。
- webhook_url: 目标地址。
- headers: 请求头。
- data=json.dumps(payload): 将 Python 字典转换为 JSON 字符串作为请求体发送。
response.raise_for_status(): 检查 HTTP 状态码，如果不是 200 OK 等成功状态，会抛出异常。
response.json(): 解析企业微信服务器返回的 JSON 响应。
检查 errcode: 企业微信 API 通过 errcode 字段告知调用结果，0 表示成功。

2. 发送 Markdown 消息

Markdown 格式支持更丰富的文本样式。

import requests
import json

# 1. 替换为你的 Webhook 地址
webhook_url = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_UNIQUE_ROBOT_KEY" # <--- 换成你的 Key

# 2. 构建 Markdown 消息内容
#    参考文档: https://developer.work.weixin.qq.com/document/path/91770#markdown%E7%B1%BB%E5%9E%8B
markdown_content = """
**实时通知** <font color="warning">请注意</font>！
> 任务状态：<font color="info">进行中</font>
> 负责人：张三 (@zhangsan)  <font color="#008000">（请使用实际存在的 userid）</font>

请相关同事注意跟进。
[点击查看详情](http://work.weixin.qq.com)
"""
# 注意:
# 1. Markdown @成员需要使用 userid，例如 <@userid> 格式，如 <@zhangsan>
# 2. 目前仅支持部分 Markdown 语法: 标题, 加粗, 斜体, 删除线, 引用, 链接, 字体颜色 (info, comment, warning)

payload = {
    "msgtype": "markdown",
    "markdown": {
        "content": markdown_content
        # Markdown 消息中 @ 成员需要直接在 content 中写入 <@userid>
        # 例如: "提醒: <@wangqing> 请处理一下这个 Bug"
    }
}

# 3. 设置请求头
headers = {
    'Content-Type': 'application/json'
}

# 4. 发送 POST 请求
try:
    response = requests.post(webhook_url, headers=headers, data=json.dumps(payload))
    response.raise_for_status()
    result = response.json()
    if result.get("errcode") == 0:
        print("Markdown 消息发送成功！")
    else:
        print(f"Markdown 消息发送失败，错误码：{result.get('errcode')}，错误信息：{result.get('errmsg')}")

except requests.exceptions.RequestException as e:
    print(f"请求发送失败：{e}")
except json.JSONDecodeError:
    print(f"无法解析服务器响应：{response.text}")

Markdown 注意事项:

msgtype 为 markdown。
内容在 markdown.content 字段中。
支持的 Markdown 语法有限，具体请参考企业微信官方文档。
在 Markdown 中 @ 成员，需要使用 <@userid> 的格式，例如 <@wangqing>。不能像 text 类型那样使用 mentioned_list。
支持的字体颜色：info (蓝色), comment (灰色), warning (橙红色)。也可以用 #RRGGBB 格式。

3. 发送图片消息 (Image)

发送图片需要先将图片读取为二进制数据，进行 Base64 编码，并计算其 MD5 值。

import requests
import json
import base64
import hashlib

# 1. 替换为你的 Webhook 地址
webhook_url = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_UNIQUE_ROBOT_KEY" # <--- 换成你的 Key

# 2. 准备图片文件
image_path = "path/to/your/image.png" # <--- 替换为你的图片路径

try:
    # 3. 读取图片 -> Base64 编码 -> 计算 MD5
    with open(image_path, 'rb') as f:
        image_data = f.read()
        base64_data = base64.b64encode(image_data).decode('utf-8') # 编码后需要解码为 utf-8 字符串
        md5_hash = hashlib.md5(image_data).hexdigest()

    # 4. 构建请求数据（图片类型）
    #    参考文档: https://developer.work.weixin.qq.com/document/path/91770#%E5%9B%BE%E7%89%87%E7%B1%BB%E5%9E%8B
    payload = {
        "msgtype": "image",
        "image": {
            "base64": base64_data,
            "md5": md5_hash
        }
    }

    # 5. 设置请求头
    headers = {
        'Content-Type': 'application/json'
    }

    # 6. 发送 POST 请求
    response = requests.post(webhook_url, headers=headers, data=json.dumps(payload))
    response.raise_for_status()
    result = response.json()
    if result.get("errcode") == 0:
        print("图片消息发送成功！")
    else:
        print(f"图片消息发送失败，错误码：{result.get('errcode')}，错误信息：{result.get('errmsg')}")

except FileNotFoundError:
    print(f"错误：找不到图片文件 '{image_path}'")
except requests.exceptions.RequestException as e:
    print(f"请求发送失败：{e}")
except json.JSONDecodeError:
    print(f"无法解析服务器响应：{response.text}")
except Exception as e:
    print(f"处理图片时发生错误: {e}")

图片消息注意事项:

msgtype 为 image。
image.base64: 图片内容的 Base64 编码字符串。
image.md5: 图片内容的 MD5 值。
图片大小限制：Base64 编码前 不超过 2MB。
支持的图片格式：JPG, PNG。

4. 发送图文消息 (News)

可以发送包含标题、描述、链接和图片的卡片式消息。

import requests
import json

# 1. 替换为你的 Webhook 地址
webhook_url = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_UNIQUE_ROBOT_KEY" # <--- 换成你的 Key

# 2. 构建请求数据（图文类型）
#    参考文档: https://developer.work.weixin.qq.com/document/path/91770#%E5%9B%BE%E6%96%87%E7%B1%BB%E5%9E%8B
payload = {
    "msgtype": "news",
    "news": {
       "articles" : [ # 最多支持 8 条图文
           {
               "title" : "重要通知：系统更新公告",
               "description" : "系统将于今晚 22:00 - 24:00 进行升级维护...",
               "url" : "http://example.com/announcement/123", # 点击图文后跳转的链接
               "picurl" : "http://res.example.com/images/update_icon.png" # 图文消息的图片链接，支持 JPG, PNG，大图 1068*455，小图 150*150
           },
           {
               "title" : "本周工作报告",
               "description" : "点击查看详细报告内容",
               "url" : "http://example.com/report/weekly",
               "picurl" : "http://res.example.com/images/report_icon.png"
           }
        ]
    }
}

# 3. 设置请求头
headers = {
    'Content-Type': 'application/json'
}

# 4. 发送 POST 请求
try:
    response = requests.post(webhook_url, headers=headers, data=json.dumps(payload))
    response.raise_for_status()
    result = response.json()
    if result.get("errcode") == 0:
        print("图文消息发送成功！")
    else:
        print(f"图文消息发送失败，错误码：{result.get('errcode')}，错误信息：{result.get('errmsg')}")

except requests.exceptions.RequestException as e:
    print(f"请求发送失败：{e}")
except json.JSONDecodeError:
    print(f"无法解析服务器响应：{response.text}")

图文消息注意事项:

msgtype 为 news。
news.articles: 是一个列表，包含一个或多个图文条目（最多 8 条）。
每个 article 包含：
- title: 标题（必填）。
- description: 描述（可选）。
- url: 点击后跳转的链接（必填）。
- picurl: 图文消息配图的 URL（可选）。图片需要能被企业微信服务器访问到。

进阶与建议

封装成函数/类： 如果你需要频繁发送消息或发送不同类型的消息，建议将发送逻辑封装成函数或类，提高代码复用性。
配置管理： 不要将 Webhook URL 硬编码在代码中，尤其是在版本控制系统里。可以考虑使用环境变量、配置文件（如 config.ini, config.yaml）等方式管理。
错误处理： 完善错误处理逻辑，例如记录失败日志、重试机制等。
频率限制： 企业微信对机器人发送消息的频率有限制（单个机器人发送速度不能超过 20 条/分钟），过度频繁发送可能导致暂时禁用。
安全性： 再次强调，Webhook 地址非常敏感，务必保密。如果泄露，应尽快在企业微信中重新生成一个新的 Webhook 地址并替换掉旧的。
查阅官方文档： 企业微信官方文档是最新、最权威的信息来源，当需要了解更多细节或遇到问题时，请查阅：群机器人配置说明

希望这个教程对你有帮助！你可以根据自己的需求选择合适的消息类型，并开始用 Python 与你的企业微信群机器人进行交互了。