pywecom-webhook 2.0.0

企业微信机器人 Webhook API 的 Python SDK，支持发送文本、Markdown、图片、图文、文件、语音等消息类型，同时提供同步和异步两种调用方式。

pywecom-webhook

企业微信机器人 Webhook API 的 Python SDK，支持发送文本、Markdown、图片、图文、文件、语音等消息类型，同时提供同步和异步两种调用方式。

功能特性

• ✅ 支持多种消息类型：文本、Markdown、MarkdownV2、图片、图文、文件、语音、模板卡片
• ✅ 基于 Pydantic 2.0 实现数据模型验证，确保数据格式正确性
• ✅ 支持 @ 指定用户或 @all 功能
• ✅ 支持文件上传（upload_media）获取 media_id
• ✅ 提供同步发送器（Sender）和异步发送器（AsyncSender）
• ✅ 异步发送器支持 async with 上下文管理器语法
• ✅ 基于 httpx 实现，支持同步/异步 HTTP 请求

安装

使用 pip 安装

pip install pywecom-webhook

从源码安装

git clone https://gitee.com/guolei19850528/pywecom_webhook.git
cd pywecom-webhook
pip install .

快速开始

同步发送消息

from pywecom_webhook import Sender, TextContent

# 创建 Sender 实例
sender = Sender(key="your_webhook_key")

# 发送文本消息
result = sender.send_text(TextContent(content="Hello, World!"))
print(result)

异步发送消息

import asyncio
from pywecom_webhook import AsyncSender, TextContent

async def main():
    # 使用 async with 语法
    async with AsyncSender(key="your_webhook_key") as sender:
        result = await sender.send_text(TextContent(content="Hello, Async World!"))
        print(result)

asyncio.run(main())

发送带 @ 的消息

from pywecom_webhook import Sender, TextContent

# 创建 Sender 实例，设置默认 @ 用户列表
sender = Sender(
    key="your_webhook_key",
    mentioned_list=["user1", "user2"],           # 默认 @ 用户 ID 列表
    mentioned_mobile_list=["13800000000"]        # 默认 @ 手机号列表
)

# 发送带 @ 的文本消息
result = sender.send_text(
    TextContent(
        content="重要通知：系统即将维护",
        mentioned_list=["@all"],                  # @ 所有人
        mentioned_mobile_list=["13900000000"]     # @ 指定手机号用户
    )
)

消息类型示例

1. 文本消息

from pywecom_webhook import TextContent

content = TextContent(
    content="这是一条普通文本消息",
    mentioned_list=["user_id_1", "user_id_2"],
    mentioned_mobile_list=["13800000000"]
)
sender.send_text(content)

# 异步方式
await async_sender.send_text(content)

2. Markdown 消息

from pywecom_webhook import MarkdownContent

content = MarkdownContent(
    content="""## 标题

**加粗文本**

*斜体文本*

> 引用文本

[链接](https://example.com)
"""
)
sender.send_markdown(content)

3. MarkdownV2 消息

from pywecom_webhook import MarkdownV2Content

content = MarkdownV2Content(
    content="<font color=\"red\">红色文本</font>\n\n<b>加粗文本</b>"
)
sender.send_markdown_v2(content)

4. 图片消息

import base64
import hashlib
from pywecom_webhook import ImageContent

with open("image.png", "rb") as f:
    image_data = f.read()

content = ImageContent(
    base64=base64.b64encode(image_data).decode("utf-8"),
    md5=hashlib.md5(image_data).hexdigest()
)
sender.send_image(content)

5. 图文消息

from pywecom_webhook import NewsArticleContent

articles = [
    NewsArticleContent(
        title="文章标题",
        description="文章描述",
        url="https://example.com",
        pic_url="https://example.com/image.jpg"
    )
]
sender.send_news(articles)

6. 文件消息

from pywecom_webhook import FileContent

# 先上传文件获取 media_id
media_id = sender.upload_media(
    file_type="file",
    files={"file": ("test.txt", open("test.txt", "rb"), "text/plain")}
)

# 发送文件消息
content = FileContent(media_id=media_id)
sender.send_file(content)

# 异步方式
media_id = await async_sender.upload_media(
    file_type="file",
    files={"file": ("test.txt", open("test.txt", "rb"), "text/plain")}
)
await async_sender.send_file(FileContent(media_id=media_id))

7. 语音消息

from pywecom_webhook import VoiceContent

# 先上传语音文件获取 media_id
media_id = sender.upload_media(
    file_type="voice",
    files={"file": ("voice.amr", open("voice.amr", "rb"), "audio/amr")}
)

# 发送语音消息
content = VoiceContent(media_id=media_id)
sender.send_voice(content)

8. 模板卡片消息

template_card = {
    "msgtype": "template_card",
    "template_card": {
        "card_type": "text_notice",
        "source": {
            "icon_url": "https://example.com/icon.png",
            "desc": "通知来源"
        },
        "main_title": {
            "title": "系统维护通知",
            "desc": "预计维护时间：2024-01-01 00:00-02:00"
        },
        "card_action": {
            "type": 1,
            "url": "https://example.com/maintenance"
        }
    }
}
sender.send_template_card(template_card)

API 文档

Sender 类（同步）

class Sender(
    base_url: str = "https://qyapi.weixin.qq.com/cgi-bin/webhook",
    key: str = None,
    mentioned_list: list = None,
    mentioned_mobile_list: list = None,
    client_kwargs: dict = None
)

AsyncSender 类（异步）

class AsyncSender(
    base_url: str = "https://qyapi.weixin.qq.com/cgi-bin/webhook",
    key: str = None,
    mentioned_list: list = None,
    mentioned_mobile_list: list = None,
    client_kwargs: dict = None
)

参数说明：

参数	类型	说明
base_url	str	Webhook 接口地址，默认为官方地址
key	str	群机器人的 Webhook key
mentioned_list	list	默认 @ 用户 ID 列表
mentioned_mobile_list	list	默认 @ 用户手机号列表
client_kwargs	dict	传递给 httpx.Client / httpx.AsyncClient 的额外参数
is_async	bool	是否异步调用，默认值为 False

发送方法

同步方法	异步方法	说明
send_text(content)	async send_text(content)	发送文本消息
send_markdown(content)	async send_markdown(content)	发送 Markdown 消息
send_markdown_v2(content)	async send_markdown_v2(content)	发送 MarkdownV2 消息
send_image(content)	async send_image(content)	发送图片消息
send_news(content)	async send_news(content)	发送图文消息
send_file(content)	async send_file(content)	发送文件消息
send_voice(content)	async send_voice(content)	发送语音消息
send_template_card(content)	async send_template_card(content)	发送模板卡片消息
upload_media(file_type, **kwargs)	async upload_media(file_type, **kwargs)	上传媒体文件
send(**kwargs)	async send(**kwargs)	直接发送消息（底层方法）

工具函数

image_to_base64_and_md5

将图片文件转换为 Base64 编码和 MD5 校验值，方便发送图片消息。

from pywecom_webhook.utils import image_to_base64_and_md5

base64_str, md5_str = image_to_base64_and_md5("image.png")

企业微信官方文档

参考企业微信官方文档：群机器人配置说明

许可证

MIT License

作者

郭磊 [e-mail]