Skip to main content
plugin/scripts/middleware.py is the SDK for regular Python plugins. Use it to create Sender, read the current context, reply to messages, store data, wait for input, handle payments, download user-uploaded files, handle HTTP routes, push proactively, and manage runtime scheduled tasks.
New plugins should prefer from middleware import Sender, getSenderID. Do not hard-code credentials, ports, or autClaw internal service addresses.

​
Quick start

#[author: your-name]
#[runtime: [email protected]]
#[title: Echo]
#[rule: echo (.+)]
from middleware import Sender, getSenderID

sender = Sender(getSenderID())
text = sender.param(1)
sender.reply(text or "Please enter text")
Python SDK methods are synchronous. Failures raise Exception; catch exceptions in flows that send network requests, media, or files, and reply with an actionable message.

​
Browse by task

Context and base types

Import style, senderID, response wrappers, SendReceipt, MediaItem, and download return bodies.

Sender message capabilities

Read users and chats, match parameters, reply with text/media, recall, and use replyMixed(...).

Wait for input and payment

listen(...), input(...), waitPay(exitcode, timeout, amount=None), and amount-matching details.

Events, media, and files

getMediaItems(), fileDownload(...), downloadAdapterFile(...), and getGroupMemberList(...).

Storage and routes

Default storage, named buckets, and HTTP router request and response aliases.

Proactive push

Targets, account selection, and return values for push(...) / pushImage(...) / pushMixed(...).

Tools, Cron, and group management

import_module(...), system utilities, Cron, group invite/mute/announcement.

Python signatures

Navigation-indexed .pyi-style signatures for IDEs and AI retrieval through MCP.

​
Common imports

from middleware import (
    Sender,
    Cron,
    getSenderID,
    bucketGet,
    bucketSet,
    fileDownload,
    downloadAdapterFile,
    getGroupMemberList,
    import_module,
    push,
    pushImage,
    pushMixed,
)

sender = Sender(getSenderID())
Common rules:
  • Use Sender to handle the current message, route request, or event.
  • Use top-level functions for global operations, such as bucketGet(...), pushImage(...), and fileDownload(...).
  • Business timeout parameters for listen(...), input(...), and waitPay(...) use milliseconds.
  • Serialize objects with json.dumps(...) before saving them with set(...) / bucketSet(...).
#[author: your-name]
#[runtime: [email protected]]
#[title: Safe template]
#[rule: demo (.+)]
from middleware import Sender, getSenderID

sender = Sender(getSenderID())

try:
    value = sender.param(1)
    if not value:
        sender.reply("Please enter text, for example: demo hello")
    else:
        sender.reply(f"Received: {value}")
except Exception as error:
    print(error)
    sender.reply("Processing failed. Try again later or contact an administrator.")

​
Actual differences from JavaScript middleware

This table is checked against the current plugin/scripts/middleware.py and plugin/scripts/middleware.js:
DifferenceJavaScriptPython
Call styleMost methods return Promise and need await.Methods return synchronously and raise Exception on failure.
Import styleconst { Sender } = require('./middleware.js')from middleware import Sender
Default storage deletedel(key)delete(key); del_ is also available. Avoid the Python keyword del.
Dependency ensureimportModule(module, versionOrOptions?, manager?)import_module(module, package="", version="", manager=""); the current SDK also keeps importModule.
Router aliasessender.getRouter() / getMethod() / getRouterData() are available.The same aliases are available; prefer getRouterPath(), getRouterMethod(), and getRouterBody() in new docs.
getRouterData()Returns a JSON string.Returns a JSON string; use getRouterBody() when you need an object.
Cron constructornew Cron()Cron() or the legacy-compatible Cron(cronID=None).
Cron methodsgetCron(...), delCron(...).Also supports getCronByID(...) and deleteCron(...).
Python-only aliasesNone.download_adapter_file(...), get_group_member_list(...).
All Python child pages are included in docs.json navigation. Mintlify indexes navigation pages for MCP search by default, so AI tools can retrieve these split reference pages.

Python plugin context and base types

Import middleware.py, create Sender, and understand common return values in Python plugins.

Python Sender message capabilities

Use Python Sender to read user and chat information, reply with text, Markdown, media, and mixed messages, and recall messages.

Python wait for input and payment

Use listen, input, and waitPay in Python plugins to wait for user input, capture media, and handle payment amount matching.

Python events, media, and files

Read event data, get media items, download user-uploaded files, and get group member lists in Python plugins.

Python plugin storage and routes

Use default storage, named buckets, and HTTP router request and response helpers in Python plugins.

Python plugin proactive push

Use Python push, pushImage, and pushMixed to proactively send text, media, and mixed messages, and choose the sending account.

Python tools, Cron, and groups

Use import_module, system utilities, Cron scheduled tasks, and group management methods in Python plugins.

Python middleware.py signatures

Use .pyi-style signatures to quickly retrieve public middleware.py functions, Sender methods, and Cron methods.
Last modified on June 3, 2026