Build a plugin

Plugins are sandboxed Python processes. Write a handler, declare your capabilities, ship a zip and we run it in a locked-down Docker container, streaming Discord events to it over JSON-RPC.

Reference — ctx attributes

Attribute	Type
ctx.server_id	str — Discord server (guild) ID
ctx.plugin_id	str — your plugin's id
ctx.version	str — installed version string
ctx.capabilities	set[str] — capabilities the user approved
ctx.discord	Discord REST surface
ctx.interaction	Interaction response surface
ctx.kv	Per-server KV store
ctx.sql	Sandboxed SQL (capability)
ctx.ephemeral	Redis-backed counters / cooldowns / flags
ctx.http	Outbound HTTP via proxy
ctx.ws	Persistent WebSocket connections via the platform broker (capability)
ctx.secrets	Encrypted secret storage (capability)
ctx.metrics	Time-series metrics
ctx.request_id	str — correlation ID for the current interaction ("" outside one)
ctx.log(message, *, level, tags, **extra)	Structured plugin log
ctx.has_capability(name)	bool — capability check

ctx.discord

Method	Capability
send_message(*, channel_id, content="", embeds=None, components=None, files=None) → returns {"message_id", "channel_id"}	discord:send_message
edit_message(*, channel_id, message_id, content=None, embeds=None, components=None) — None leaves components unchanged, [] clears them	discord:edit_message
delete_message(*, channel_id, message_id)	discord:delete_message
bulk_delete_messages(*, channel_id, message_ids)	discord:delete_message
add_reaction(*, channel_id, message_id, emoji)	discord:add_reaction
pin_message(*, channel_id, message_id)	discord:send_message
unpin_message(*, channel_id, message_id)	discord:send_message
get_messages(*, channel_id, limit=50, before=None, after=None)	discord:read
iter_messages(*, channel_id, batch_size=50, before=None, after=None) v0.6.1 — generator that pages through full channel history (newest→oldest, or oldest→newest with after=)	discord:read
get_guild()	discord:read
get_channel(*, channel_id)	discord:read
list_channels()	discord:read
get_member(*, user_id)	discord:read
list_members(*, role_id=None, limit=100, after=None)	discord:read
search_members(query, *, limit=25)	discord:read
list_roles()	discord:read
create_channel(*, name, channel_type=0, category_id=None, topic=None, user_limit=None)	discord:manage_channels
edit_channel(*, channel_id, name=None, topic=None, user_limit=None)	discord:manage_channels
delete_channel(*, channel_id)	discord:manage_channels
set_channel_permissions(*, channel_id, target_id, allow="0", deny="0", target_type=0)	discord:manage_channels
delete_channel_permission(*, channel_id, target_id)	discord:manage_channels
create_thread(*, channel_id, name, thread_type=11, auto_archive_duration=1440)	discord:manage_channels
edit_thread(*, thread_id, archived=None, locked=None, name=None, auto_archive_duration=None)	discord:manage_channels
timeout_member(*, user_id, duration_seconds, reason="")	discord:moderate_members
set_nickname(*, user_id, nickname=None)	discord:moderate_members
kick_member(*, user_id, reason="")	discord:kick_members
ban_member(*, user_id, reason="", delete_message_seconds=0)	discord:ban_members
unban_member(*, user_id)	discord:ban_members
add_role(*, user_id, role_id, reason="")	discord:manage_roles
remove_role(*, user_id, role_id, reason="")	discord:manage_roles
add_role_bulk / remove_role_bulk / timeout_bulk / kick_bulk	(matches single-action capability)
create_webhook(*, channel_id, name)	discord:manage_webhooks
execute_webhook(*, webhook_id, webhook_token, content="", embeds=None, username=None, avatar_url=None)	discord:manage_webhooks
delete_webhook(*, webhook_id)	discord:manage_webhooks

edit_message, delete_message and bulk_delete_messages only operate on messages your plugin sent — attempts on other messages are rejected, and a bulk call fails closed on the whole batch if any ID isn't plugin-owned.

ctx.ws

Requires proxy:websocket. Connections are named; the platform's broker holds the socket. Full guide on the Storage & I/O tab.

Method	Use
ensure(name, url, *, secret_auth=None, auth=None, subscribe=None, binary=False)	Idempotently open (or confirm) the named connection. Returns {"conn_id", "name", "state"}. subscribe frames are re-sent after every reconnect.
send(name, data)	One frame: str sends text, bytes sends binary.
close(name)	Hang up the named connection.
allow_host(host) / revoke_host(host)	Authorize a WebSocket destination a server admin supplies at setup time; must be called from a slash handler run by that admin.

ctx.interaction

All four methods require the interaction:respond capability (auto-added when your manifest declares slash_commands).

Method	Use
respond(*, content="", embeds=None, components=None, ephemeral=False, allowed_mentions=None, update_message=False)	First reply (within 3s of receiving the interaction). allowed_mentions mirrors Discord's API field — e.g. {"parse": []} suppresses all pings. update_message=True (component handlers only, v0.7.0) edits the message the component sits on instead of sending a new reply.
defer(*, ephemeral=False)	"I'm working on it" — buys you up to 15 minutes for a followup
followup(*, content="", embeds=None, components=None, ephemeral=False, allowed_mentions=None)	Reply after a defer (or send additional messages). Returns {"message_id", "channel_id"} so you can edit the message later.
send_modal(*, title, custom_id, fields=None)	Open a modal — use as the FIRST response, not after a defer

ctx.kv / ctx.sql / ctx.ephemeral / ctx.http / ctx.metrics

Full method signatures live on the Storage & I/O tab: KV, SQL, Ephemeral, HTTP (including secret-backed Authorization injection via secret_auth=), Metrics.

Plugin decorators

Decorator	Handler signature
@plugin.on_ready	(ctx) — per (worker, server) before that server's first event in pool mode; once per boot locally
@plugin.on_event(event_type)	(ctx, event)
@plugin.on_slash_command(name)	(ctx, event)
@plugin.on_component(custom_id=None, *, prefix=None)	(ctx, event) — exactly one of exact custom_id or prefix match
@plugin.on_modal_submit(custom_id)	(ctx, event)
@plugin.on_ws_message(name)	(ctx, frame) — {"name", "conn_id", "data", "binary"}, binary data base64. "prefix:*" wildcard matches by prefix; exact names win
@plugin.on_ws_open(name)	(ctx)
@plugin.on_ws_close(name)	(ctx, info) — {"reason", "will_reconnect"}
@plugin.on_dashboard(method_name)	(ctx, params) → dict
@plugin.schedule(seconds)	(ctx) — local yourbot dev only; does not run in pool mode (marketplace plugins), see Pool mode
@plugin.cron(spec)	(ctx) — 5-field UTC cron string. Runs in production when declared in the manifest "cron" array (5-minute floor, 5 entries max); see Cron schedules
@plugin.on_install / on_enable / on_disable / on_uninstall	(ctx) — advisory signals, delivered best-effort when a worker is live, with a tenant-scoped ctx that keeps your approved capabilities. Required init still belongs in on_ready

Event payload reference

Typed payload shapes for all 16 events live in yourbot_sdk.events (MessageCreate, MemberJoin, …). Defaults produced by yourbot_sdk.testing.make_event:

make_event("message_create", content="hi")
# {message_id, channel_id, guild_id, author_id, author_username, author_bot,
#  content, timestamp}

make_event("interaction_create", command_name="ban", custom_id="")
# {interaction_id, interaction_type, guild_id, channel_id, user_id,
#  command_name, custom_id, modal_values}

make_event("reaction_add", emoji="🎉")
# {message_id, channel_id, user_id, emoji, guild_id}

WebSocket handlers receive their own shapes (not events): on_ws_message gets {"name", "conn_id", "data", "binary"} (binary data base64, frames per connection arrive in order) and on_ws_close gets {"reason", "will_reconnect"}.

Exceptions reference

See the full table under Error handling on the Production tab.

Capability catalog

Everything you can put in capabilities_required, with the badge customers see on the install consent screen. ctx.metrics, ctx.ephemeral and ctx.log need no capability.

Capability	Consent badge	What it unlocks
storage:kv	Safe	Per-server KV store
discord:send_message	Safe	send_message, pin_message, unpin_message
discord:edit_message	Safe	edit_message
discord:add_reaction	Safe	add_reaction
interaction:respond	Safe	Slash command + component handling (all of ctx.interaction)
discord:read	Standard	Read message history, members, channels, roles
discord:delete_message	Standard	delete_message, bulk_delete_messages
discord:manage_webhooks	Standard	create_webhook, execute_webhook, delete_webhook
storage:secrets	Standard	Encrypted ctx.secrets.* + secret-backed auth on ctx.http/ctx.ws
storage:sql staff-reviewed	Standard	Sandboxed SQL schema
proxy:http	Standard	Outbound ctx.http.* to declared domains
events:message_content	Dangerous	Message text and author detail in events — without it events arrive meta-only (IDs and timestamps). Privacy-sensitive; request it only if you parse what people type
discord:manage_channels	Dangerous	Create/edit/delete channels & threads, set permissions
discord:moderate_members	Dangerous	timeout_member, timeout_bulk, set_nickname
discord:kick_members	Dangerous	kick_member, kick_bulk
discord:ban_members	Dangerous	ban_member, unban_member
discord:manage_roles	Dangerous	add_role, remove_role, bulk variants (admin roles blocked)
proxy:websocket staff-reviewed	Dangerous	Persistent WebSockets via ctx.ws.* — exact host required (or admin-approved via allow_host)

Dangerous-tier calls are logged at WARNING level. Capability narrative (auto-detection at upload, consent flow, CapabilityError semantics) lives on the Production tab.

Reserved slash-command names

These names belong to YourBot's built-in plugins and are refused at upload (yourbot validate checks them locally):

announce   appeal     ban          beacon     case        giveaway   group
group-admin  group-alerts  help    history    kick        leaderboard
lockdown   maid-bug-report  music  note       poll        purge
quarantine quests     raidmode     report     slowmode    stats
temp-role  ticket     tickets      timeout    unban       unlockdown
unquarantine  untimeout  warn      welcome    yourbot

Grandfathering: if your plugin published a command before its name joined this list, you keep publishing it and on each server it registers under the alias /yourpluginid-name instead. Your handlers need no changes; events still arrive under the manifest name, and your command sync status shows the alias.

Limits and quotas

Every enforced number in one place. Each row links to the section that explains it.

Area	Limit
Package	25 MB zipped, 100 MB uncompressed, 500 files, 10 MB per file
KV store	50,000 keys per (server, plugin), 500,000 per plugin globally; 64 KB values, 512-byte keys; get_many 50 / set_many 25 / list 1000 keys / list_values 100 entries per call
Secrets	64-char keys, 4096-char values
SQL	1000 rows per query (hard cap), one statement per call, 100 tables, 10,000,000 rows per (plugin, server), DDL 20/hour
Ephemeral	256-char keys, 24 h max TTL (silently clamped); writes cost 0.1 outbound action
HTTP	500 KB request, 200 KB response, 8 s timeout, 30 requests/min
WebSockets	6 connects/min, 4 MB/min traffic shared across both directions
Cron	5-minute minimum interval, 5 entries per manifest, UTC minute resolution
Metrics	1,000,000 stored points per (server, plugin), 10 tags per record, 128-char tag values, 90-day query window; names 1–64 chars
Logs	4000-char messages, 10 tags, 20 extra kwargs at 500 chars each
Runtime	50 events/s, 60 outbound actions/min; 64 MB / 0.25 vCPU per worker (24 MB / 0.1 in pool mode); 64 PIDs; 16 MB /tmp
Dashboards	8 s widget RPC timeout, 600 bridge calls/min
Interactions	3 s to first response; defer() buys 15 minutes

SDK changelog

v0.8.4

• Added production cron delivery: @plugin.cron tasks declared in the manifest "cron" array now fire in pool mode with a tenant-scoped ctx (Cron schedules). yourbot validate checks specs (5-minute floor, 5 entries) and warns when a decorated task has no manifest entry.
• Added tenant-scoped lifecycle hooks: @plugin.on_install / on_enable / on_disable / on_uninstall now receive a per-server ctx (with your approved capabilities) instead of the boot context, and RPCs inside them resolve the right tenant.

v0.8.3

• Added slash-command consistency checks to yourbot validate: declared commands with no matching handler, uppercase decorator names, reserved names and malformed command/option names are caught locally, exactly like the platform does at upload.
• Added proxy:websocket capability auto-detection from ctx.ws.* usage in yourbot validate.
• Fixed pool-mode tenant resolution (every RPC now carries the correlation ID of its originating event). Previously documented for 0.7.1, but the code did not ship in that wheel; 0.8.3 ships it.
• Fixed dashboard handler error logs to name the handler that actually failed.

v0.8.2

• Added wildcard WebSocket handlers: @plugin.on_ws_message("name:*") (and on_ws_open / on_ws_close) match every connection sharing the prefix; exact-name registrations take precedence.

v0.8.1

• Added ctx.ws.allow_host(host) / ctx.ws.revoke_host(host) — a server admin authorizes a WebSocket destination at setup time that a static allow-list can't express.

v0.8.0

• Added ctx.ws — persistent WebSocket connections held by the platform broker (ensure / send / close, on_ws_message / on_ws_open / on_ws_close). Capability: proxy:websocket.
• Added secret-backed auth injection for ctx.http and ctx.ws: secret_auth="NAME" (or auth={"scheme": ..., "secret": ...}) makes the platform set Authorization from a domain-bound secret your code never sees. Unblocks Bearer-token APIs.
• Added quarter dashboard widget width alongside full / half / third / two_thirds.
• Added MockContext.ws to the test harness.

v0.7.1

• Changed ctx.kv.increment(key, amount) to accept amount positionally (was keyword-only).
• Fixed RateLimitError.retry_after to carry the host's actual retry hint as a float.

v0.7.0

• Added ctx.interaction.respond(update_message=True) — edit the message a button / select menu is attached to (Discord UPDATE_MESSAGE) instead of sending a new reply. Component interactions only; degrades to a normal reply on older platforms.

v0.6.1

• Added ctx.discord.iter_messages() — auto-paginating channel history generator.
• Added machine-readable .code on every SDK exception (CAPABILITY_DENIED, RATE_LIMITED, …).
• Added typed Discord response shapes (yourbot_sdk.responses) and a PEP 561 py.typed marker, so mypy / pyright / IDEs pick up SDK type hints.
• Changed MockContext to enforce capabilities by default (gated calls raise CapabilityError like production); several mock-fidelity fixes.
• Fixed KV quota errors to raise KvQuotaError instead of a generic RateLimitError.

v0.6.0

• Renamed the SDK from mmo-maid-sdk to yourbot-sdk (pip install yourbot-sdk, from yourbot_sdk import Plugin). Nothing breaks: import mmo_maid_sdk keeps working via a compatibility package and the old PyPI name resolves to the new one.
• Added the yourbot CLI: yourbot new, yourbot dev, yourbot validate, yourbot doctor.

v0.5.1

• Added allowed_mentions parameter on ctx.interaction.respond() and ctx.interaction.followup() — controls which mentions actually ping (e.g. {"parse": []} suppresses all pings).

v0.5.0

• Added ctx.metrics, ctx.sql, ctx.ephemeral sub-APIs.
• Added mmo_maid_sdk.testing module with MockContext and make_event.
• Added lifecycle decorators: on_install, on_enable, on_disable, on_uninstall.
• Added @plugin.cron(spec) for wall-clock UTC scheduling (5-field cron).
• Added bulk Discord operations: add_role_bulk, remove_role_bulk, kick_bulk, timeout_bulk.
• Added typed exception classes (10) for actionable error handling.
• Security 7 critical + 1 high SDK / sandbox findings fixed (audit, April 2026).