Writing handlers

Every handler has the signature (ctx, api) and may be async. Each handler returns the { blocks, state, effects } triple:

blocks: the component tree; null means the UI doesn’t need to change
state: local state passed back to you on the next invocation
effects: operations such as writing data or sending notifications, declared so the site can validate each one and commit them in a single transaction

ctx: context

{
  "install_id": 12,
  "version": 3,
  "locale": "zh_CN",
  "config": {},
  "topic_id": 481,
  "post_id": 1902,
  "category_id": 5,
  "user": { "id": 7, "username": "ada", "avatar_url": "..." },
  "state": {}
}

Field	Description
`install_id` / `version`	Current installation and version number
`locale`	Current user’s language
`config`	Configuration provided at install time
`topic_id` / `post_id` / `category_id`	Where the mini app sits in the topic
`user`	Current user; `null` for anonymous visitors
`state`	The state returned by the previous handler invocation
`action_id` / `inputs`	`onAction` only: the action of the clicked button and the form inputs
`method` / `params`	`onMessage` only: the method called by the page and its parameters

This list is the privacy boundary — it is deliberately narrow because it is visible to every mini app author.

Blocks: render and onAction

A blocks mini app returns a component tree, which the site renders natively:

export async function render(ctx, api) {
  const count = (await api.kv.get("count")) ?? 0;
  return { blocks: view(count), state: { count }, effects: [] };
}

export async function onAction(ctx, api) {
  if (ctx.action_id !== "bump") {
    return { blocks: null, state: ctx.state, effects: [] };
  }
  const count = (ctx.state?.count ?? 0) + 1;
  return {
    blocks: view(count),
    state: { count },
    effects: [{ type: "kv.set", key: "count", value: count }],
  };
}

function view(count) {
  return {
    type: "vstack", gap: "small", children: [
      { type: "text", value: `Clicked ${count} times`, weight: "bold" },
      { type: "button", label: "Click again", action: "bump", variant: "primary" },
    ],
  };
}

Webview: webview and onMessage

A webview mini app draws its own UI (HTML + CSS + JS) and gets a real client-side loop:

export async function webview(ctx, api) {
  return { html: "...", css: "...", js: "..." };
}

export async function onMessage(ctx, api) {
  // The page reaches this via window.community.call(method, params)
  if (ctx.method !== "submit") {
    return { blocks: null, state: null, effects: [] };
  }
  // Validate, compute the score, write to the shared region
}

Making scores trustworthy: seed replay

Scores from the page are untrusted. To make the leaderboard, the server must be able to verify them: the server issues a seed, the page sends back the sequence of moves, and onMessage replays them with the same simulation logic to compute the real score. A cheater who wants on the board has to actually play the game well — that’s how the site’s snake mini app works: its scores are computed by the server replaying the moves.

The JS in the page is injected as a source string, not a closure. Any module-level constants it references must be included in the injected preamble, or you’ll get X is not defined at runtime.

Background handlers

Handler	When it fires
`onTrigger(ctx, api)`	Site events declared in `triggers`
`onSchedule(ctx, api)`	Scheduled tasks registered via `schedule.add`
`onFetch(ctx, api)`	An `http.fetch` the app declared has come back
`onInstall(ctx, api)`	The app is put to work, once per install

All four run as the mini app’s own bot account and cannot read any member’s private data. Their reads and writes address the app’s shared region, so api.kv.get in a background run reads back what a background run stored. A background ctx looks like this:

{
  "background": true, "install_id": 12, "config": {},
  "event": "post_created",
  "data": { "topic_id": 481, "post_id": 1902, "user_id": 7, "author_id": 7 },
  "job_key": "daily", "payload": {},
  "request_id": "weather", "ok": true, "status": 200, "body": "..."
}

An app with no interface, built entirely around these, is a service app — see Bots.

Permissions and data

Reads (via api, all require await; data is prefetched by the platform before the call, so the sandbox never actually queries the database):

Call	Contents	Required scope
`api.kv.get(key)` / `api.kv.list()`	The current member’s data under this installation	`kv`
`api.kv.listPublic()`	Shared region (this install)	`kv.shared`
`api.kv.app.get(key)`	What the whole app knows, across every install	`kv.app`
`api.points.balance()`	Points balance	`points`
`api.points.spends()`	This member’s purchases from this installation (last 10)	`points.spend`
`api.post.get(id)` / `api.topic.get(id)`	The post and topic this invocation is about	`post.read`
`api.post.recentByUser(id)`	That person’s recent posts, within the app’s reach	`post.read`

Writes (return effects; each is validated and committed in a single transaction):

Effect	Required scope
`kv.set` / `kv.delete`	`kv`
`kv.shared.set` / `kv.shared.delete`	`kv.shared`
`ui.toast` / `ui.navigate`	`ui`
`points.award`	`points`
`points.spend`	`points.spend` (privileged)
`rt.publish`	`realtime`
`schedule.add` / `schedule.cancel`	`schedule`
`kv.app.set` / `kv.app.delete`	`kv.app`
`notify.user`	`notify`
`http.fetch`	`http`
`post.create` / `post.reply`	`post.write`
`flag.create`	`flag.create`
`post.delete` / `post.recover`	`moderate.post`
`topic.close` / `topic.tag`	`moderate.topic`
`post.pin` / `post.unpin`	`moderate.topic`
`post.lock` / `post.unlock`	`moderate.topic`

Four things to remember:

Only handlers can write to the shared region. A member’s kv.set always lands in their own namespace, which is what makes leaderboards trustworthy.
Broadcasts are just signals. A client that receives rt.publish re-runs a permission-checked render; the broadcast payload itself is never treated as state.
api.post.get answers only for the post this invocation is about, and null for any other id. Prefetching is what stops an app installed in one corner reading across the site.
kv.app cannot be enumerated. It answers only for the people this invocation is about, because on a real site the area is a lookup table with tens of thousands of rows — handing it over whole would put that list in memory on every post anybody writes.

context is granted implicitly — no need to request it. post.write, moderate.post, moderate.topic, webview and points.spend are privileged: only an admin grants them (points.spend also has a site setting that has to be on). The rules for posting and acting on content are in Bots.

Points: an account between the installer and the member, not money the platform hands out

points.award is not minted from nothing. It’s a transfer: points come out of the balance of whoever installed the app and go to the member. If the installer’s balance can’t cover the batch, the whole thing is refused (E_POINTS_FUNDS); if the site has no points system, refused the same way (E_POINTS_UNAVAILABLE). The one exception is an install an admin has explicitly marked “platform-funded” — only there does the site mint the points outright. Whoever is paying, the same three ceilings still apply: per-award, per-app-per-day, per-member-per-day. In a call a member triggered, that member is who gets paid. A background run (onTrigger and friends) acts as the bot, so the effect names the recipient with user_id — and it may only be the person the event is about, ctx.data.user_id, such as the inviter in member_invited; anyone else is refused (E_POINTS_DENIED). That is the whole recipe for “X points per person brought in”: a bot installed on the node listens for member_invited and sends points.award to data.inviter_id, funded by the node owner who installed it. The other direction exists too: selling something. points.spend (a privileged scope, granted separately at review) doesn’t charge anyone — it asks:

{ type: "points.spend", request_id: "skin-gold", amount: 30, label: "Golden skin" }

All it does is make the site itself — not your UI — open a confirmation naming the amount, what it’s for, and who gets paid. Only when the member taps “Pay” there do any points move, from their balance to the installer’s (or straight to nothing, on a platform-funded install). Your onSpend(ctx, api) is then called, with ctx.spend carrying { request_id, amount, status: "paid" } — that’s where you deliver the goods (a kv.set, say). If the member taps “No thanks” or lets it expire (5 minutes), nothing happens.

You cannot draw this confirmation or click through it. Whatever your buttons say, what the member actually confirms comes from the site’s own record, not your interface. One invocation can only ask one question at a time — a new ask replaces an unanswered one — and both a per-purchase and a per-member-per-day spending cap apply.

A crashed onSpend doesn’t undo the payment — reconcile with api.points.spends() and deliver anything paid for but never granted; make delivery logic idempotent on request_id, since a retry must not deliver twice. A webview app hears the same outcome through community.onSpend = fn. Once an admin marks an install “platform-funded” from the app’s admin page, that install’s points.award is minted by the site and its points.spend simply retires the points — neither passes through anyone’s balance. This is mainly for official, site-run mini apps that shouldn’t be charging whoever installed them.

Saying it in the reader’s language

ctx.locale is the forum’s own language. post.locale, on a post you read, is that member’s. Which to use follows from who reads what you write:

What	Whose language
A post everybody in the topic reads	`ctx.locale`
A reply to one person — a greeting, a reminder	`post.locale`, then `ctx.locale`
A flag	`ctx.locale` — moderators read it
A prompt sent to a model	neither; keep it in one language

Fallback runs exact, then the same language written for anywhere else, then English. An app that wrote zh_CN should not leave a zh_TW reader with English — Simplified is much closer to what they read than that.

API Integration

Mini App Development

ctx: context

Blocks: render and onAction

Webview: webview and onMessage

Making scores trustworthy: seed replay

Background handlers

Permissions and data

Points: an account between the installer and the member, not money the platform hands out

Saying it in the reader’s language

​ctx: context

​Blocks: render and onAction

​Webview: webview and onMessage

​Making scores trustworthy: seed replay

​Background handlers

​Permissions and data

​Points: an account between the installer and the member, not money the platform hands out

​Saying it in the reader’s language

ctx: context

Blocks: render and onAction

Webview: webview and onMessage

Making scores trustworthy: seed replay

Background handlers

Permissions and data

Points: an account between the installer and the member, not money the platform hands out

Saying it in the reader’s language