Python API Reference

Direct Python API for programmatic access to WeCom Bot functionality.

Installation

pip install wecom-bot-mcp-server

Quick Start

import asyncio
from wecom_bot_mcp_server import send_message

async def main():
    await send_message("Hello from Python!", msg_type="text")

asyncio.run(main())

Message Functions

send_message

Send text or markdown messages.

async def send_message(
    content: str,
    msg_type: str = "text",
    mentioned_list: list[str] | None = None,
    mentioned_mobile_list: list[str] | None = None,
    bot_id: str | None = None,
) -> dict

Parameters:

Parameter	Type	Default	Description
content	str	-	Message content
msg_type	str	"text"	"text" or "markdown"
mentioned_list	list	None	User IDs to @mention
mentioned_mobile_list	list	None	Phone numbers to @mention
bot_id	str	None	Target bot (uses default if None)

Examples:

# Simple text message
await send_message("Hello World!")

# Markdown message
await send_message(
    content="**Bold** and *italic*",
    msg_type="markdown"
)

# With @mentions
await send_message(
    content="Please review this",
    msg_type="text",
    mentioned_list=["user1", "user2"]
)

# Mention by phone
await send_message(
    content="Urgent!",
    msg_type="text",
    mentioned_mobile_list=["13800138000"]
)

# Mention all
await send_message(
    content="Team announcement",
    msg_type="text",
    mentioned_list=["@all"]
)

# Send to specific bot
await send_message(
    content="Build failed!",
    msg_type="markdown",
    bot_id="ci"
)

send_wecom_file

Send files to WeCom.

async def send_wecom_file(
    file_path: str,
    bot_id: str | None = None,
) -> dict

Parameters:

Parameter	Type	Default	Description
file_path	str	-	Path to the file
bot_id	str	None	Target bot

Examples:

# Send a file
await send_wecom_file("/path/to/report.pdf")

# Send to specific bot
await send_wecom_file("/path/to/build.log", bot_id="ci")

send_wecom_image

Send images to WeCom.

async def send_wecom_image(
    image_path: str,
    bot_id: str | None = None,
) -> dict

Parameters:

Parameter	Type	Default	Description
image_path	str	-	Local path or URL
bot_id	str	None	Target bot

Examples:

# Send local image
await send_wecom_image("/path/to/chart.png")

# Send from URL
await send_wecom_image("https://example.com/image.png")

# Send to specific bot
await send_wecom_image("/path/to/screenshot.png", bot_id="alert")

Bot Management

get_bot_registry

Get the global bot registry instance.

from wecom_bot_mcp_server.bot_config import get_bot_registry

registry = get_bot_registry()

Methods:

# Get a bot by ID
bot = registry.get("alert")  # Returns BotConfig
bot = registry.get()  # Returns default bot

# Get webhook URL
url = registry.get_webhook_url("alert")
url = registry.get_webhook_url()  # Default bot URL

# List all bots
bots = registry.list_bots()  # Returns list of dicts

# Check if bot exists
exists = registry.has_bot("alert")  # Returns bool

# Check for multiple bots
multiple = registry.has_multiple_bots()  # Returns bool

# Get bot count
count = registry.get_bot_count()  # Returns int

# Reload configuration
registry.reload()  # Re-reads environment variables

list_available_bots

List all configured bots.

from wecom_bot_mcp_server.bot_config import list_available_bots

bots = list_available_bots()
# Returns: [{"id": "default", "name": "Default", "description": "...", "has_webhook": True}, ...]

BotConfig

Data class for bot configuration.

from wecom_bot_mcp_server.bot_config import BotConfig

@dataclass
class BotConfig:
    name: str           # Human-readable name
    webhook_url: str    # Webhook URL
    description: str    # Optional description
    metadata: dict      # Optional metadata

Error Handling

from wecom_bot_mcp_server.errors import WeComError, ErrorCode

try:
    await send_message("Hello", bot_id="nonexistent")
except WeComError as e:
    print(f"Error: {e.message}")
    print(f"Code: {e.error_code}")

Error Codes:

class ErrorCode:
    VALIDATION_ERROR = "VALIDATION_ERROR"
    NETWORK_ERROR = "NETWORK_ERROR"
    API_ERROR = "API_ERROR"
    FILE_NOT_FOUND = "FILE_NOT_FOUND"
    FILE_TOO_LARGE = "FILE_TOO_LARGE"

Complete Example

import asyncio
import os
from wecom_bot_mcp_server import send_message, send_wecom_file, send_wecom_image
from wecom_bot_mcp_server.bot_config import get_bot_registry, list_available_bots
from wecom_bot_mcp_server.errors import WeComError

# Set environment variables
os.environ["WECOM_WEBHOOK_URL"] = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
os.environ["WECOM_BOT_ALERT_URL"] = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=alert"

async def main():
    # List available bots
    bots = list_available_bots()
    print(f"Available bots: {[b['id'] for b in bots]}")

    # Send messages
    try:
        # Text message to default bot
        await send_message("Daily report ready", msg_type="text")

        # Markdown to CI bot
        await send_message(
            content="## Build Status\n- **Result**: Success\n- **Duration**: 5m 30s",
            msg_type="markdown",
            bot_id="ci"
        )

        # Alert with @mention
        await send_message(
            content="Server CPU > 90%!",
            msg_type="text",
            mentioned_list=["admin"],
            bot_id="alert"
        )

        # Send file
        await send_wecom_file("/path/to/report.pdf")

        # Send image
        await send_wecom_image("/path/to/chart.png", bot_id="alert")

    except WeComError as e:
        print(f"Failed: {e.message}")

if __name__ == "__main__":
    asyncio.run(main())

Type Hints

The library is fully typed. For IDE support:

from wecom_bot_mcp_server import send_message
from wecom_bot_mcp_server.bot_config import BotConfig, BotRegistry

# Your IDE will provide full autocomplete and type checking