wechat-ilink-bot

轻量、实用的 Python SDK，用于接入 WeChat iLink Bot API。

支持扫码登录、长轮询收消息、文本/图片/视频/文件发送，以及一键 webhook 发送。

核心能力

• 收消息：长轮询 + handler
• 主动发送文本：send_text
• 主动发送图片/视频/文件：send_image / send_video / send_file
• 会话内回复文本：ctx.reply
• 会话内回复图片/视频/文件：ctx.reply_image / ctx.reply_video / ctx.reply_file
• Webhook 触发发送（当前为文本）

Read the Docs: https://wechat-ilink-bot.readthedocs.io/en/latest/

安装

PyPI 安装：

pip install wechat-ilink-bot

源码安装（开发/调试推荐）：

git clone https://github.com/hkslover/wechat-ilink-bot.git
cd wechat-ilink-bot
pip install -e .

可选依赖：

# 终端二维码打印
pip install "wechat-ilink-bot[qrcode]"

# webhook
pip install "wechat-ilink-bot[webhook]"

快速开始

1) 扫码登录并持久化账号

import asyncio

from wechat_bot import Bot


async def main() -> None:
    bot = Bot(use_current_user=False)
    result = await bot.login()
    print(f"login ok: account_id={result.account_id}, user_id={result.user_id}")
    await bot.stop()


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

2) 最小 Echo Bot

from wechat_bot import Bot, Filter

bot = Bot()


@bot.on_message(Filter.text())
async def echo(ctx):
    await ctx.reply(f"Echo: {ctx.text}")


if __name__ == "__main__":
    bot.run()

3) 主动发送（owner-default 或显式目标）

import asyncio

from wechat_bot import Bot


async def main() -> None:
    bot = Bot()

    # owner-default（不传 to）
    await bot.send_text(text="Hello from wechat-ilink-bot!")

    # 或者显式目标
    # await bot.send_text(to="o9xxx@im.wechat", text="Hello")

    await bot.stop()


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

4) 主动发送富媒体（图片 / 视频 / 文件）

import asyncio

from wechat_bot import Bot


async def main() -> None:
    bot = Bot()

    # owner-default（不传 to）
    await bot.send_image(file_path="/path/to/image.png", caption="image")
    await bot.send_video(file_path="/path/to/video.mp4", caption="video")
    await bot.send_file(file_path="/path/to/file.pdf", caption="file")

    # 显式目标（需要时）
    # await bot.send_image(to="o9xxx@im.wechat", file_path="/path/to/image.png")

    await bot.stop()


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

5) 会话内回复富媒体（ctx.reply_*）

from wechat_bot import Bot, Filter

bot = Bot()


@bot.on_message(Filter.text_startswith("/image"))
async def reply_image(ctx):
    await ctx.reply_image("/path/to/image.png", caption="image")


@bot.on_message(Filter.text_startswith("/video"))
async def reply_video(ctx):
    await ctx.reply_video("/path/to/video.mp4", caption="video")


@bot.on_message(Filter.text_startswith("/file"))
async def reply_file(ctx):
    await ctx.reply_file("/path/to/file.pdf", caption="file")


if __name__ == "__main__":
    bot.run()

Webhook 快速使用

启动：

wechat-bot webhook --api-key your-secret

请求示例：

# GET
curl "http://127.0.0.1:8787/send?text=hello&key=your-secret"

# POST
curl -X POST "http://127.0.0.1:8787/send" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Key: your-secret" \
  -d '{"text":"hello from webhook"}'

Webhook /send 当前用于发送文本。
图片/视频/文件发送请使用 Bot.send_image / Bot.send_video / Bot.send_file。

Examples

更多完整脚本请查看：

• examples/login_bot.py
• examples/echo_bot.py
• examples/command_bot.py
• examples/media_bot.py
• examples/proactive_send.py
• examples/account_switch.py
• examples/webhook_server.py

本地文档预览

pip install -r docs/requirements.txt
mkdocs serve

参与贡献

• Contributing Guide
• Security Policy
• Changelog

License

MIT