# Cherry developer docs > Cherry lets you add real chat to your product and drive it from your backend. Two integration surfaces: the Chat Embed SDK (`@cherrydotfun/chat-embed-sdk`, a drop-in widget) and the Cherry API (a REST API with two key types: a project key `cherry_sk__` for the Apps API at `https://api.cherry.fun/api/v1/apps`, and a bot key `cherry_bot__` for the Bot API at `https://api.cherry.fun/api/v1/bots`). They compose: your backend creates a room with the Cherry API, your frontend embeds it with the SDK. > Every link below points at the page's plain-Markdown mirror (append `.md` to any docs URL). Want all of it in one request? Fetch https://portal.cherry.fun/llms-full.txt, the entire docs set, concatenated. ## Getting started - [Introduction](https://portal.cherry.fun/docs.md): the two integration surfaces and how they fit together. - [Quickstart](https://portal.cherry.fun/docs/quickstart.md): a public chat embed in ~5 minutes, no backend. ## Chat Embed SDK - [Installation](https://portal.cherry.fun/docs/embed/installation.md): `npm install @cherrydotfun/chat-embed-sdk`, or a jsDelivr script tag. - [Configuration](https://portal.cherry.fun/docs/embed/configuration.md): full `CherryEmbedConfig` and `layout` reference. - [Authentication](https://portal.cherry.fun/docs/embed/authentication.md): wallet-only, app-trusted+wallet (backend token server), app-trusted. - [Display modes](https://portal.cherry.fun/docs/embed/display-modes.md): single / list / external-controlled; inline / floating. - [Theming](https://portal.cherry.fun/docs/embed/theming.md): the derivation engine (pass 2-4 honest brand colors as seeds, it derives the full ~60-variable palette with contrast guarantees), the extraction methodology (roles, modes, ink tokens, gradients), the 3+1 seed contract, the verify floors, and runtime `setTheme`. - [Your users' names](https://portal.cherry.fun/docs/embed/host-identity.md): render your app's own display names and avatars instead of wallet identities. `resolveUsers` / `searchUsers` from the page, or a Profile endpoint the iframe calls directly; `setUserProfiles` / `invalidateUserProfiles` to push changes; visual and per-widget only (the wallet stays the message author), and every supplied value is sanitized. - [Moderation](https://portal.cherry.fun/docs/embed/moderation.md): server-enforced per-embed rules: minimum wallet age, blocked words, link policy, image/GIF toggles. - [Unread indicators](https://portal.cherry.fun/docs/embed/unread-indicators.md): the `unreadState` event (`rooms` + `total`, unread vs. mentions), two cached getters (`getUnreadState`, `getUnreadCount`) plus the `refreshUnreadState()` re-emit command, when counters accrue (widget hidden via `hide()` / `collapsed`), the built-in `chatBubble` badge and its three `chatBubbleBadge` modes, and the badge sizing recipe for host-drawn indicators. - [React Native & Flutter](https://portal.cherry.fun/docs/embed/mobile.md): the SDK in a WebView host page + native wallet signing bridge (the SDK is browser-only and cannot run in a mobile JS runtime). - [SDK API reference](https://portal.cherry.fun/docs/embed/api-reference.md): all methods, getters, and events. ## Cherry API - [Authentication](https://portal.cherry.fun/docs/api/authentication.md): project keys (`cherry_sk_`) and bot keys (`cherry_bot_`), one opaque token each; `GET /me`. - [Create rooms & attach to embeds](https://portal.cherry.fun/docs/api/rooms.md): create a room (`POST /groups`) and surface it in an embed. - [Messages & bot actions](https://portal.cherry.fun/docs/api/messages.md): send, read, and delete messages as the app bot. - [Members & moderation](https://portal.cherry.fun/docs/api/members.md): two moderation models: project key (`members:moderate`, acts as room owner) and bot key (`bots:groups:moderate`, gated by the bot's in-room role). - [Scopes](https://portal.cherry.fun/docs/api/scopes.md): the permission required by each endpoint. - [Rate limits & errors](https://portal.cherry.fun/docs/api/rate-limits.md): per-app 600/min + 50k/day; error codes. - [Endpoint reference](https://portal.cherry.fun/docs/api/reference.md): every endpoint at a glance. - [OpenAPI spec](https://portal.cherry.fun/openapi.json): machine-readable OpenAPI 3.1 for the Apps + Bot APIs (import into Postman / codegen / agents). ## Guides - [Add public chat](https://portal.cherry.fun/docs/guides/public-chat.md): wallet-only embed, no backend. - [Theme your embed](https://portal.cherry.fun/docs/guides/theme-embed.md): set the seed colors (or have an AI agent extract them) so the chat matches your brand. - [Authenticated chat](https://portal.cherry.fun/docs/guides/authenticated-chat.md): tie chat identity to your users' wallets. - [A room per game / match / order](https://portal.cherry.fun/docs/guides/room-per-entity.md): create rooms on demand and embed them. - [Build a moderation bot](https://portal.cherry.fun/docs/guides/moderation-bot.md): watch a room and moderate via the Cherry API. ## For AI agents - [For AI agents](https://portal.cherry.fun/docs/ai/for-ai-agents.md): integration skills and the setup prompt. - Embed integration skill: https://github.com/cherrydotfun/chat-embed-sdk/tree/main/skills - Mini-app integration skill: https://github.com/cherrydotfun/miniapp-sdk/tree/main/skills ## Support - [Contact us](https://portal.cherry.fun/docs/support.md): reach the Cherry team in the public Telegram group at https://t.me/cherrydotfun; documented causes for the common 401 / 403 / 429 errors, and what to include in a report. ## Key facts (read before generating code) - npm package: `@cherrydotfun/chat-embed-sdk` (current 0.1.7); class `CherryEmbed`. Mount with `new CherryEmbed({ appId, container, roomId, mode, position, collapsed, chatBubble, chatBubbleBadge, theme, token, walletAddress, signChallengeHandler, resolveUsers, searchUsers, userProfiles, identityToken }).mount()`. Omit `container` for floating widgets: they mount to `document.body` and a stray selector throws. `chatBubble` (the SDK's own launcher button) and `chatBubbleBadge` (`'dot'` default / `'count'` / `'off'`) are floating-only and ship in 0.1.7; on 0.1.6 both keys are ignored, so a floating widget pinned to 0.1.6 needs your own button wired to `chat.toggle()`. The host-identity options (`resolveUsers` / `searchUsers` / `userProfiles` / `identityToken`, plus `setUserProfiles()` / `invalidateUserProfiles()` / `setIdentityToken()`) also ship in 0.1.7 and need the embed's "Who your users appear as" switch; the Profile endpoint transport needs no SDK support at all. - The iframe is served from `https://embed.cherry.fun` (the SDK default `embedUrl`); host pages never set an API base. If you send a Content-Security-Policy, allow `frame-src https://embed.cherry.fun`. - app-trusted+wallet token: an HS256 JWT `jwt.sign({ sub: walletAddress, app_id: }, APP_SECRET, { algorithm: 'HS256', expiresIn: '5m', jwtid: })`. Claims are exactly `sub` and `app_id` (NOT `appId` / `walletAddress`). `APP_SECRET` is the per-embed app secret: server-side only; never ship it to the browser. - Mobile (React Native / Flutter): the SDK cannot run in a mobile JS runtime (it is DOM-only). Run it in a WebView on a small host page (never load `embed.cherry.fun` as the WebView's top document; the bridge rejects when `window.parent === window`) and bridge wallet signing to the native layer. Guide: https://portal.cherry.fun/docs/embed/mobile.md - Cherry API keys are each ONE opaque token copied from the portal (never assembled from an app ID + secret). Project key `Authorization: Bearer cherry_sk__` → Apps API `https://api.cherry.fun/api/v1/apps` (scopes: groups:*/members:*/messages:*). Bot key `Authorization: Bearer cherry_bot__` → Bot API `https://api.cherry.fun/api/v1/bots` (scopes: bots:*). `cha__` is a deprecated legacy format. Bot moderation needs BOTH the `bots:groups:moderate` scope AND the bot's in-room role (owner/admin/moderator).