@cherrydotfun/chat-embed-sdk

Embed Cherry Chat rooms into any website: a lightweight iframe widget with wallet-based auth, full theming, and real-time messaging. Works with any bundler or straight from a <script> tag.

Live demo

Try it: cherry.fun/chat-embed-example — theme presets, display modes (inline / floating / collapsible / resizable), and a live theme editor, all embedded into a real Cherry chat room. Its "Show the integration snippet" button gives you copy-paste code.

Full documentation lives at portal.cherry.fun/docs.

Install

npm install @cherrydotfun/chat-embed-sdk

Or, for a plain HTML site, load the package from npm via jsDelivr (the bundle exposes window.CherryEmbedSDK):

<script src="https://cdn.jsdelivr.net/npm/@cherrydotfun/[email protected]/dist/index.global.js"></script>

Before you start

You need a Cherry embed, created self-serve at portal.cherry.fun:

1. Sign in with your Solana wallet (SIWS — no email/password, nothing goes onchain).
2. Create a Project, then open Chat embeds → New embed.
3. Copy the embed ID (your appId), add your site's origin under Allowed origins, and make sure the embed is enabled.

An embed only loads on allow-listed origins while enabled — add http://localhost:3000 (or your dev origin) before testing locally.

Quickstart (no backend)

The default wallet-only mode needs nothing but an appId and a public room. The iframe owns the entire wallet flow: visitors click "Connect wallet", sign a challenge, and chat — no token endpoint, no host wallet integration.

import { CherryEmbed } from '@cherrydotfun/chat-embed-sdk';

const chat = new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  container: '#cherry-chat',
  roomId: 'YOUR_ROOM_ID',
  theme: { mode: 'dark', primaryColor: '#FF5BA8' },
});

await chat.mount();

<div id="cherry-chat" style="height: 600px"></div>

Prefer a floating panel instead of an inline one? Omit container and set a position:

const chat = new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  roomId: 'YOUR_ROOM_ID',
  position: 'floating-right',
});
await chat.mount();

Pass collapsed: true to start hidden — the widget has no built-in launcher button, so wire your own control to chat.toggle() / chat.show().

Authenticating your own users

If you run a backend and want chat identity tied to your users, use app-trusted + wallet auth: your backend signs a short-lived embedToken (HMAC, using the app secret from your embed's settings), and the user confirms wallet ownership with one signature. See Authentication for the full flow, and example/app-trusted+wallet/ for a complete runnable token server.

const chat = new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  container: '#cherry-chat',
  token,          // minted by your backend
  walletAddress,  // the user's connected wallet
  signChallengeHandler: async (message) => {
    // message: Uint8Array — sign it with the user's wallet, return Uint8Array
    return await wallet.signMessage(message);
  },
});
await chat.mount();

Documentation

The portal docs are the source of truth for the SDK surface:

• Installation
• Configuration — every option CherryEmbed accepts
• Authentication — wallet-only vs. backend-signed tokens
• Display modes — inline, floating, collapsed
• Theming — presets and the full theme reference
• API reference — methods, events, types
• Guides — public chat, authenticated chat, room-per-entity

Mobile (React Native / Flutter)

The SDK is browser-only (document/iframe/window.postMessage), so it can't run directly in a mobile runtime. Run it inside a WebView (react-native-webview or webview_flutter) on a small host page, and bridge wallet signing to the native layer (Mobile Wallet Adapter on Android / deeplink on iOS) — there's no window.phantom in a mobile WebView. Don't point the WebView straight at embed.cherry.fun: the bridge rejects when window.parent === window, so the embed must be nested in an iframe on a host page. One host page serves both platforms (it auto-detects the bridge).

Full guide: docs/react-native.md. Runnable code (hosted + bundled host page): example/react-native/ · example/flutter/.

Examples

• example/wallet-only/ — static host, no backend; the live demo above runs this app
• example/app-trusted+wallet/ — Express token server + host-page wallet signing
• example/app-trusted/ — Express token server only, zero signature, no wallet. authMode: app-trusted is self-serve: pick it in your embed's auth mode at portal.cherry.fun.
• example/react-native/ — React Native WebView integration with native wallet signing
• example/flutter/ — Flutter WebView integration (MWA + Phantom deeplink)

Development

npm install
npm run build      # tsup → dist/ (ESM, CJS, IIFE global build)
npm test           # vitest
npm run typecheck  # tsc --noEmit

Support

• Documentation: https://portal.cherry.fun/docs
• GitHub issues: https://github.com/cherrydotfun/chat-embed-sdk/issues
• Cherry team: reach out via portal.cherry.fun

License

MIT — see LICENSE.