Mini-apps#

A mini-app is an ordinary web page you host, opened inside a Mafold conversation. It gets a signed identity for the current user, a realtime document shared with everyone in the chat, and panel chrome — through a single global, window.Mafold.

If you've built a Telegram Mini App, the shape will feel familiar: you own the URL and the code; Mafold provides the host, the identity handshake, and the capabilities.

The mental model#

Embedded vs standalone#

The same build runs in two modes, and the SDK abstracts the difference:

Mafold.embedded tells you which mode you're in. You rarely need to branch on it — auth() and room.* do the right thing automatically; only chat-only features (sendMessage, reading the thread) require the embedded host.

Add the SDK#

Two ways to include it — same Mafold object either way.

<!-- 1) Versioned script tag (immutable-cached) -->
<script src="https://mafold.com/js/mafold-webapp@0.3.0.js"></script>

// 2) npm — ships TypeScript types
import Mafold from "@mafold/webapp";

Minimal app#

Mafold.ready();                              // tell the host the UI is up

const user = Mafold.initDataUnsafe?.user;    // display-only identity (unverified)
document.querySelector("#hi").textContent = `Hi, ${user?.display_name}`;

await Mafold.room.open();                     // the conversation-shared document
Mafold.room.onUpdate((doc) => render(doc));   // re-render on any participant's change
await Mafold.room.increment("taps");          // everyone sees it, live

That's a complete multiplayer app: every person who opens it in the same chat shares the taps counter, and each tap broadcasts to all of them.

Next steps#

• SDK reference — every Mafold.* method.
• Authentication — verify initData on your backend.
• Publishing — register, get your secret, and host.