pywgb

Wecom(A.K.A. WeChat Work) Group Bot python API.

Homepage

Github

ChowRex/pywgb: Wecom(A.K.A Wechat Work) Group Bot python API.

Pypi

pywgb · PyPI

How to use

Limitation

⚠️ Warning: Request rate is limited.

Each bot CANNOT send more than 20 messages/minute. See here.

Pre-conditions

1. Create a Wecom Group Bot.

2. Copy the webhook URL or just the key. It MUST contains an UUID (8-4-4-4-12), like:

   • Webhook: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=UUID
   • Key: UUID

3. Install this package:

   # Normally use this if you won't send voice message
   pip install -U pywgb
   # You can install full version by this
   pip install -U "pywgb[all]"

Send messages

Create a instance of SmartBot

from pywgb import SmartBot

KEY = "PASTE_YOUR_KEY_OR_WEBHOOKURL_HERE"
bot = SmartBot(KEY)

Basic usage

Text

msg = "This is a test Text message."
bot.send(msg)

# If you want to send message and mention someone at the same time, refer this.
kwargs = {
  "mentioned_list": [
    # If you know the userid
    "userid",
    # Use below for ALL people
    "@all",
  ],
  "mentioned_mobile_list": [
    # If you know the phone number
    "13800001111",
    # Use below for ALL people
    "@all",
  ]
}
msg = "Alert, this is an important message."
bot.send(msg, **kwargs)

Markdown

Supported Markdown syntax:

• Title (1-6 levels)

• Bold

• Link

• Inner line code

• Single level reference

• [Unique feature] Coloured(green/gray/orange) text.

col = [bot.markdown_feature.green, bot.markdown_feature.gray, bot.markdown_feature.orange]
markdown = ''.join(col[idx % 3](ltr) for idx, ltr in enumerate("colorful"))
markdown = f"""
# L1 title
## L2 title
### L3 title
#### L4 title
##### L5 title
###### L6 title

Author: **Rex** (bold font)

Link: [Go Bing](https://bing.com)

Inner line `code`

> This is a test reference

This is a {markdown} Markdown message
"""
bot.send(markdown)

Markdown_v2

Compare missing features in version v1:

• NOT support for coloured text.

Additional syntax support from v1:

• Italics
• Multi-level list (unordered/ordered)
• Multi-level reference (1-3 levels)
• Picture
• Split line
• Separate code block
• Table

_table = [
    ["Name", "Gender", "Title"],
    ["Julia", "Female", "Accounting"],
    ["Jess", "Female", "Reception"],
    ["Tom", "Male", "Manager"],
    ["Grance", "Male", "Testing"],
    ["Rex", "Male", "DevOps"],
]
markdown_v2 = f"""
# Here are the enhancements compared to v1

*Italics*

- Unordered List 1
- Unordered List 2
  - Unordered List 2.1
  - Unordered List 2.2
1. Ordered List 1
2. Ordered List 2

> L1 reference
>> L2 reference
>>> L3 reference

![Picture](https://res.mail.qq.com/node/ww/wwopenmng/images/independent/doc/test_pic_msg1.png)

A split line will appear below

---

```
There is a test code block.
```

Here is a empty string when the table is less than 2 rows.

{bot.markdown_feature.list2table(_table[:1])}

Here is a test table.

{bot.markdown_feature.list2table(_table)}

"""
bot.send(markdown_v2)

News

articles = [
    {
        "title": "This is a test news",
        "description": "You can add description here",
        "url": "www.tencent.com",
        # Here is the link of picture
        "picurl": "https://www.tencent.com/img/index/tencent_logo.png"
    },
]
bot.send(articles=articles)

Image

image = "Path/To/Your/Image.png" or "Path/To/Your/Image.jpg"
bot.send(file_path=image)

Voice

📢 You must install FULL version to avoid warning prompt.

voice = "Path/To/Your/Voice.amr"  # BE ADVISED: ONLY support amr file
bot.send(file_path=voice)

File

file = "Path/To/Your/File.suffix"
bot.send(file_path=file)

Advanced usage

Upload temporary media (Materials only available in 3 days)

file = "Path/To/Your/File.suffix"
media_id = bot.upload(file)
print(media_id)

TextTemplateCard

kwargs = {
    "main_title": {
        "title": "Test message",
        "desc": "This is a test template text card message"
    },
    "emphasis_content": {
        "title": "100",
        "desc": "No meaning"
    },
    "quote_area": {
        "type": 1,
        "url": "https://work.weixin.qq.com/?from=openApi",
        "title": "Title reference",
        "quote_text": "Hello\nWorld!"
    },
    "sub_title_text": "This is sub-title",
    "horizontal_content_list": [{
        "keyname": "Author",
        "value": "Rex"
    }, {
        "keyname": "Google",
        "value": "Click to go",
        "type": 1,
        "url": "https://google.com"
    }],
    "jump_list": [{
        "type": 1,
        "url": "https://bing.com",
        "title": "Bing"
    }],
    "card_action": {
        "type": 1,
        "url": "https://work.weixin.qq.com/?from=openApi",
    }
}
bot.send(**kwargs)

NewsTemplateCard

kwargs = {
    "source": {
        "icon_url":
            "https://wework.qpic.cn/wwpic/252813_jOfDHtcISzuodLa_1629280209/0",
        "desc":
            "This is for testing",
        "desc_color":
            0
    },
    "main_title": {
        "title": "Test message",
        "desc": "This is a test template news card message"
    },
    "card_image": {
        "url":
            "https://wework.qpic.cn/wwpic/354393_4zpkKXd7SrGMvfg_1629280616/0",
        "aspect_ratio":
            2.25
    },
    "image_text_area": {
        "type":
            1,
        "url":
            "https://work.weixin.qq.com",
        "title":
            "Welcom to use pywgb",
        "desc":
            "This is a test message",
        "image_url":
            "https://wework.qpic.cn/wwpic/354393_4zpkKXd7SrGMvfg_1629280616/0"
    },
    "quote_area": {
        "type": 1,
        "url": "https://work.weixin.qq.com/?from=openApi",
        "title": "Title reference",
        "quote_text": "Hello\nWorld!"
    },
    "vertical_content_list": [{
        "title": "Hi, there",
        "desc": "Welcome to use"
    }],
    "horizontal_content_list": [{
        "keyname": "Author",
        "value": "Rex"
    }, {
        "keyname": "Google",
        "value": "Click to go",
        "type": 1,
        "url": "https://google.com"
    }],
    "jump_list": [{
        "type": 1,
        "url": "https://bing.com",
        "title": "Bing"
    }],
    "card_action": {
        "type": 1,
        "url": "https://work.weixin.qq.com/?from=openApi",
    }
}
bot.send(**kwargs)

Use the specified bot

You can refer below to use specify kind of bot.

from pywgb.bot import TextBot, MarkdownBot, MarkdownBotV2
from pywgb.bot import ImageBot, NewsBot, FileBot
from pywgb.bot import VoiceBot, TextCardBot, NewsCardBot

KEY = "PASTE_YOUR_KEY_OR_WEBHOOKURL_HERE"

bot_type = TextBot
bot = bot_type(Key)
bot.send("Some thing here")

This might be useful when you want to send voiceor image as a file (SmartBot won't send image or voice as file).

from pywgb.bot import FileBot

KEY = "PASTE_YOUR_KEY_OR_WEBHOOKURL_HERE"

voice = "Path/To/Your/Voice.amr"
image = "Path/To/Your/Image.png" or "Path/To/Your/Image.jpg"

bot = FileBot(KEY)
bot.send(file_path=voice)
bot.send(file_path=image)

Official Docs

Only Chinese doc: 群机器人配置说明 - 文档 - 企业微信开发者中心

Roadmap

• v0.0.1: 🎉 Initial project. Offering send Text and Markdown type message.

• v0.0.2: 🖼️ Add Image type message support;

  • Add overheat detect function and unified exception handling

• v0.0.3: 📰 Add News type message support;

  • Move bots into a new module: bot

• v0.0.4: 📂 Add File type message support;

  • Refactor bot module

• v0.0.5: 🗣️ Add Voice type message support.

  • Refactor deco module
  • Add verify_file decorator
  • Introverted parameters check errors
  • Add more content into README.md

• v0.0.6: 🩹 Add Voice and File type size check.

• v0.0.7: 🗒️ Add TextCard type message support.

• v0.0.8: 🗃️ Add NewsCard type message support.

• v0.0.9: ♻️ Refactor code.

• v0.1.0: 🔧 Fix color bug when use markdown type

• v0.1.1: ⏺️ Refactor all code logic again, I don't like mess and complex.

• v0.1.2: 💪 Add a SmartBot class

  • Add a SmartBot class
  • Enhanced markdown bot class
  • Add a txt file for SmartBot testing File type
  • Add empty message verify for Text and Markdown
  • Add a new markdown test unit
  • Fully test SmartBot class

• v1.0.0: 👍 First FULL capacity stable version release.Fix bugs and so on.

• v1.0.1: 🐛 Fix some bugs and fulfill coverage.

• v1.0.2: 🆕 Add Markdown_v2 type support.

• v1.0.3: 🐛 Fix Markdown_v2 attribute markdown_feature to class method.

• v1.0.4: 📝 Add content into README.md