跳转至

Bot API

Bot 是 SDK 的核心入口，负责登录、轮询、handler 注册和主动发送。

常用主动发送方法：

  • send_text
  • send_image
  • send_video
  • send_file

wechat_bot.bot.Bot

High-level bot interface.

Usage::

bot = Bot(token="your_token")

@bot.on_message(Filter.text())
async def echo(ctx):
    await ctx.reply(ctx.text)

bot.run()

参数：

名称 类型 描述 默认
token str | None

Bot token from QR login. If None you must call :meth:login before :meth:run.

 None
base_url str

iLink API base URL.

 DEFAULT_BASE_URL
cdn_base_url str

CDN base URL for media operations.

 DEFAULT_CDN_BASE_URL
account_id str | None

Bot account ID. Auto-detected from storage if omitted.

 None
state_dir str | None

Directory for persistent state files.

 None
user_id str | None

Current bot user ID (usually auto-populated by login state).

 None
use_current_user bool

If True and no explicit token/account is given, auto-load the latest account from current_user.json.

 True

account_id: str property

Current active bot account ID.

owner_user_id: str | None property

Owner user ID inferred from login/session state, if available.

add_handler(handler: MessageHandler) -> None

Register a :class:MessageHandler manually.

Handlers are sorted by priority and dispatch stops at first match.

list_accounts() -> list[str]

List local account IDs that have stored credentials.

login(**kwargs: Any) -> LoginResult async

Perform QR code login.

All keyword arguments are forwarded to :func:login_with_qr. After a successful login the token and account ID are persisted so subsequent Bot() instances can auto-load them.

on_message(filters: Filter | None = None, priority: int = 0) -> Callable[[HandlerCallback], HandlerCallback]

Decorator to register a message handler.

参数：

名称 类型 描述 默认
filters Filter | None

Optional :class:Filter to restrict which messages trigger this handler.

 None
priority int

Lower values run first. Default 0.

 0
Notes

Only the first matching handler (by ascending priority) is invoked for each inbound message.

resolve_recipient(to: str | None = None) -> str

Resolve final recipient user ID.

Resolution order: 1. Explicit to (if provided) 2. Owner user ID inferred from persisted login state

run() -> None

Blocking convenience method: start polling and run until interrupted.

Handles SIGINT / SIGTERM for graceful shutdown.

run_async() -> None async

Async convenience method: start polling and run until interrupted.

Handles SIGINT / SIGTERM for graceful shutdown. Use this in existing asyncio applications.

send_file(to: str | None = None, file_path: str | None = None, caption: str = '') -> None async

Upload and send a file attachment.

send_image(to: str | None = None, file_path: str | None = None, caption: str = '') -> None async

Upload and send an image.

send_text(to: str | None = None, text: str | None = None) -> None async

Send a text message.

参数：

名称 类型 描述 默认
to str | None

Optional target user ID. If omitted, owner user ID is used.

 None
text str | None

Message text.

 None

send_video(to: str | None = None, file_path: str | None = None, caption: str = '') -> None async

Upload and send a video.

start() -> None async

Start the long-poll loop in the background.

Use :meth:stop to shut it down gracefully.

stop() -> None async

Stop the polling loop and close the HTTP client.

use_account(account_id: str) -> None

Switch to a locally stored account.

引发：

类型 描述
RuntimeError

If the account has no stored credentials or polling is currently running.