# Cherry developer docs: full text

> Every Cherry developer documentation page, concatenated into one file for AI
> agents and no-JS clients. Individual pages: append `.md` to any docs URL
> (e.g. https://portal.cherry.fun/docs/quickstart.md), or see https://portal.cherry.fun/llms.txt for the index.
>
> Machine-readable API: the OpenAPI 3.1 spec for the Cherry Apps + Bot APIs is
> at https://portal.cherry.fun/openapi.json (import into Postman / codegen / agents).

---

<!-- https://portal.cherry.fun/docs -->

# Cherry developer docs

Cherry lets you add real chat to your product, and drive it from your backend. There are two integration surfaces, designed to work together:

## Chat Embed SDK

A drop-in widget that renders Cherry chat inside your web app. Install one npm package, mount it onto a `<div>`, and your users are chatting. It handles wallet auth, theming, and realtime updates for you.

- **Package:** `@cherrydotfun/chat-embed-sdk`
- **Use it for:** putting a chat room (or a list of rooms) on your site, themed to match your brand.
- [Quickstart →](https://portal.cherry.fun/docs/quickstart.md)

> **Tip:** Want to see it first? Try the [live embed demo and theme builder](https://cherry.fun/chat-embed-example/), a no-signup, no-backend playground where you can switch themes, pick a display mode, and copy a ready-to-paste integration snippet.

## Cherry API

A REST API you call from **your backend** to manage chat programmatically: create rooms on the fly, send messages, and moderate members. It has two key types, each a single opaque token from the portal: a **project key** (`cherry_sk_`) for rooms and messages your project owns, and a **bot key** (`cherry_bot_`) for a named bot that acts with its own in-room identity (including [moderating rooms it's promoted in](https://portal.cherry.fun/docs/guides/moderation-bot.md)).

- **Base URL:** `https://api.cherry.fun/api/v1/apps` (project/Apps API) · `https://api.cherry.fun/api/v1/bots` (Bot API)
- **Use it for:** creating a room per game, match, order, or community automatically, then surfacing it in an embed.
- [Cherry API authentication →](https://portal.cherry.fun/docs/api/authentication.md)

## How they fit together

The two surfaces compose into the most common pattern: your backend **creates a room** with the Cherry API, and your frontend **embeds** it with the SDK.

For example, a game spins up a room per match: the server calls the Cherry API to create the room and add the players, then the web client mounts the embed pointed at that room. The same flow works for a marketplace order, a token-gated community, or a support thread.

## Where to go next

- New here? Start with the [Quickstart](https://portal.cherry.fun/docs/quickstart.md), a public chat embed in about five minutes.
- Building the full experience? The **Chat Embed SDK** and **Cherry API** sections cover authentication, theming, dynamic rooms, and the complete reference.

> **Tip:** Building with an AI coding assistant? Point it at our [`llms.txt`](https://portal.cherry.fun/llms.txt), a single plain-text file that indexes and links every page in these docs in a format LLMs read well. Paste the URL into your assistant (or let it fetch it) and it has the whole SDK and API at hand. See [For AI agents](https://portal.cherry.fun/docs/ai/for-ai-agents.md) for that plus ready-made integration skills.

---

<!-- https://portal.cherry.fun/docs/quickstart -->

# Quickstart

Get a live, public Cherry chat embed running on your site in about five minutes, no backend required. This uses **wallet-only** auth, where visitors connect their own Solana wallet to chat in a public room.

> **Tip:** Want to see it first? Try the [live embed builder](https://cherry.fun/chat-embed-example/), a no-signup demo where you can theme the widget in real time and copy a ready-to-paste integration snippet.

## 1. Sign in with your wallet

Cherry signs you in with your Solana wallet, so there's no email or password to set up.

1. Open the [portal](https://portal.cherry.fun/login) and click **Connect Wallet**.
2. Choose your Solana wallet, then approve the signature request. This is Sign In With Solana (SIWS): the signature proves you own the wallet and starts your session. Nothing goes onchain and there's no gas.
3. You land on your dashboard, signed in.

## 2. Create a project

A project holds your embeds, bots, and API keys, so you need one before you can create an embed.

1. On the [dashboard](https://portal.cherry.fun/dashboard), click **Create Project**. On your first visit the empty state offers the same button.
2. Enter a **Name**. That's the only required field; description, notification email, and teammate invites are optional and editable later.
3. Click **Create Project**. Cherry opens the new project, where **Chat embeds** live.

## 3. Create an embed

In your project, open **Chat embeds** → **New embed** and give it a name. Then:

1. Copy the **embed ID** (your `appId`).
2. Under **Allowed origins**, add the origin you'll embed from (e.g. `http://localhost:3000` for local dev, and your production URL).
3. Make sure the embed is **enabled**.

> **Note:** The name you give an embed is also the visible title of its chat room, so pick something visitors should see. Renaming the embed later renames the live chat too; the new title reaches already-open widgets within a few minutes.

> **Warning:** An embed only loads on origins you've allow-listed, and only while it's enabled, otherwise it returns `401`. Add your dev and production origins before testing.

## 4. Install the SDK

```bash
npm install @cherrydotfun/chat-embed-sdk
```

## 5. Mount the widget

Point the embed at a public room and mount it onto a container element:

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

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

await chat.mount();
```

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

That's it: a themed chat room, live on your page.

## No build step? Use a script tag

For a plain HTML site, load the SDK from npm via jsDelivr. The bundle exposes `window.CherryEmbedSDK`:

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

<script src="https://cdn.jsdelivr.net/npm/@cherrydotfun/chat-embed-sdk@0.1.5/dist/index.global.js"></script>
<script>
  new window.CherryEmbedSDK.CherryEmbed({
    appId: 'YOUR_EMBED_ID',
    container: '#cherry-chat',
    roomId: 'YOUR_ROOM_ID',
    theme: { mode: 'dark', primaryColor: '#FF5BA8' },
  }).mount();
</script>
```

## Next steps

- **Authenticate your own users** (tie chat identity to your users' wallets via your backend) → [Chat Embed SDK › Authentication](https://portal.cherry.fun/docs/embed/authentication.md)
- **Theme it to your brand:** presets and the full theme reference → [Chat Embed SDK › Theming](https://portal.cherry.fun/docs/embed/theming.md)
- **Create rooms from your backend** and surface them in the embed → [Cherry API › Create rooms & attach to embeds](https://portal.cherry.fun/docs/api/rooms.md)

---

<!-- https://portal.cherry.fun/docs/guides/public-chat -->

# Guide: Add public chat to your app

The fastest way to ship chat: a public room any visitor can join by connecting their wallet. No backend required.

**You'll need:** an embed created in [the portal](https://portal.cherry.fun/dashboard) (in `wallet-only` mode), its `appId`, your origin allow-listed, and a public room's `roomId`.

## 1. Install

```bash
npm install @cherrydotfun/chat-embed-sdk
```

## 2. Add a container

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

## 3. Mount

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

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

await chat.mount();
```

That's a complete, themed, public chat room. Visitors connect their own wallet to post.

> **Tip:** Want to see it before you wire it up? Try the [live embed builder](https://cherry.fun/chat-embed-example/), a no-signup, no-backend demo where you can switch themes and display modes in real time and copy the matching integration snippet.

## Make it a floating widget

Drop the `container`, switch `position`, and start collapsed. The widget doesn't render its own launcher button, so wire your own control to open it (see [display modes](https://portal.cherry.fun/docs/embed/display-modes.md) for all options):

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

// collapsed starts hidden: open it from your own UI
document.querySelector('#open-chat')?.addEventListener('click', () => chat.toggle());
```

## Where next

- Tie chat identity to *your* users → [Authenticated chat](https://portal.cherry.fun/docs/guides/authenticated-chat.md).
- Theme it → [Theming](https://portal.cherry.fun/docs/embed/theming.md).

---

<!-- https://portal.cherry.fun/docs/guides/authenticated-chat -->

# Guide: Authenticated chat with your users' wallets

Tie chat identity to your users by minting short-lived tokens on your backend and having users sign a wallet challenge. This is the `app-trusted+wallet` mode, the default for production embeds.

**You'll need:** an embed in `app-trusted+wallet` mode, its `appId` and **app secret** (open your project in [the dashboard](https://portal.cherry.fun/dashboard) → Chat embeds and API keys), and a backend you control.

## 1. Mint tokens on your backend

Sign a JWT with your app secret. The user's wallet is `sub`, your app is `app_id`. Keep the secret server-side.

```ts
// POST /api/cherry-embed-token
import jwt from 'jsonwebtoken';
import { randomUUID } from 'node:crypto';

export function mintCherryToken(walletAddress: string) {
  return jwt.sign(
    { sub: walletAddress, app_id: process.env.CHERRY_APP_ID },
    process.env.CHERRY_APP_SECRET,
    { algorithm: 'HS256', expiresIn: '5m', jwtid: randomUUID() },
  );
}
```

> **Note:** A full runnable example is in the public [`chat-embed-sdk`](https://github.com/cherrydotfun/chat-embed-sdk/tree/main/example/app-trusted+wallet) repo, under `example/app-trusted+wallet` (its `server.js`).

## 2. Connect the wallet and mount

Register `signChallengeHandler` before `mount()`: the iframe calls it to verify wallet ownership.

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

const provider = window.phantom?.solana;
const { publicKey } = await provider.connect();
const walletAddress = publicKey.toString();

const { token } = await fetch('/api/cherry-embed-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ walletAddress }),
}).then((r) => r.json());

const chat = new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  container: '#cherry-chat',
  roomId: 'YOUR_ROOM_ID',
  token,
  walletAddress,
  signChallengeHandler: async (message) => {
    // message: Uint8Array. Sign the bytes as-is, don't re-encode them
    const { signature } = await provider.signMessage(message, 'utf8');
    return signature; // Uint8Array
  },
});

await chat.mount();
```

## 3. Session renewal is automatic

The embed token expires in ~5 minutes, so mint it fresh right before `mount()`; don't cache it. After the initial exchange the iframe renews its session silently via a rotating refresh token; there's nothing to refresh on a timer. To force a fresh exchange (e.g. after an account switch), mint a new token and call `chat.setToken(token)`.

## Where next

- Create rooms from your backend → [A room per game / match / order](https://portal.cherry.fun/docs/guides/room-per-entity.md).
- Full auth detail → [Embed › Authentication](https://portal.cherry.fun/docs/embed/authentication.md).

---

<!-- https://portal.cherry.fun/docs/guides/room-per-entity -->

# Guide: A room per game / match / order

Spin up a dedicated chat room for each unit of activity in your app (a game match, a marketplace order, a support ticket) and drop your users straight into it. This combines the [Cherry API](https://portal.cherry.fun/docs/api/rooms.md) (server) with the [embed SDK](https://portal.cherry.fun/docs/embed/display-modes.md) (client).

## 1. Create the room from your backend

When the activity starts (a match is made, an order is placed), call the Cherry API. Add the participants as `initialMembers` so they're active immediately.

```ts
// your server - CHERRY_API_KEY is your project key: the one opaque
// `cherry_sk_<projectId>_<secret>` token copied from the portal.
const res = await fetch('https://api.cherry.fun/api/v1/apps/groups', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHERRY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ownerWallet: hostWallet,
    title: `Match #${matchId}`,
    initialMembers: [playerA, playerB],
  }),
});

const { roomId } = await res.json();
// persist roomId alongside your match/order record
```

## 2. Greet them with the bot (optional)

See the [Messages API](https://portal.cherry.fun/docs/api/messages.md) for the full send-message endpoint.

```ts
await fetch(`https://api.cherry.fun/api/v1/apps/groups/${roomId}/messages`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CHERRY_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ content: 'Match starting - good luck! 🎮' }),
});
```

## 3. Open the room in the embed

Pass the `roomId` to a `single`-mode embed, or, if the user moves between activities, mount once in `external-controlled` mode and call `setRoom()`:

```ts
// single room
new CherryEmbed({ appId: 'YOUR_EMBED_ID', container: '#chat', roomId, mode: 'single' });

// or, switch rooms as the user navigates
chat.setRoom(roomId);
```

## 4. Clean up

When the activity ends, delete the room (it must be app-created):

```ts
await fetch(`https://api.cherry.fun/api/v1/apps/groups/${roomId}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.CHERRY_API_KEY}` },
});
```

## Where next

- [Cherry API › Create rooms & attach to embeds](https://portal.cherry.fun/docs/api/rooms.md) for the full endpoint detail.
- [Moderation bot](https://portal.cherry.fun/docs/guides/moderation-bot.md) to keep rooms healthy.

---

<!-- https://portal.cherry.fun/docs/guides/moderation-bot -->

# Guide: Build a moderation bot

Run a bot that keeps a room healthy (delete spam, mute offenders, ban repeat abusers), acting as **its own identity** in the room, not as the room owner.

This uses the **two-key** model. A bot can only moderate a room where it holds a privileged **role**, so the flow has two halves:

1. A **project key** (`cherry_sk_`) sets the room up: creates it, invites the bot's wallet, and promotes it to `moderator`.
2. The **bot key** (`cherry_bot_`) does the moderating via the `/api/v1/bots/*` endpoints.

**You'll need:**
- A **bot** in your project with a **bot key** that has the [`bots:groups:moderate` scope](https://portal.cherry.fun/docs/api/scopes.md). Note its **wallet**: from the portal's bot section, or `GET /api/v1/bots/me`.
- A **project key** with `groups:create`, `members:invite`, and `members:moderate` to set the room up.

## 1. Give the bot a moderator role (project key)

The bot's authority comes from its in-room role. Create a room your project owns (or reuse one), invite the bot's wallet, activate it, then promote it.

```ts
// CHERRY_PROJECT_KEY is your `cherry_sk_<projectId>_<secret>` token.
const OWNER = {
  Authorization: `Bearer ${process.env.CHERRY_PROJECT_KEY}`,
  'Content-Type': 'application/json',
};

// create a room the project owns
const { roomId } = await (
  await fetch('https://api.cherry.fun/api/v1/apps/groups', {
    method: 'POST',
    headers: OWNER,
    body: JSON.stringify({ ownerWallet: HOST_WALLET, title: 'General' }),
  })
).json();

// invite the bot's wallet and activate it immediately
await fetch(`https://api.cherry.fun/api/v1/apps/groups/${roomId}/members`, {
  method: 'POST',
  headers: OWNER,
  body: JSON.stringify({ wallets: [BOT_WALLET], autoAccept: true }),
});

// promote it to moderator, now the bot can moderate THIS room
await fetch(
  `https://api.cherry.fun/api/v1/apps/groups/${roomId}/members/${BOT_WALLET}/role`,
  { method: 'POST', headers: OWNER, body: JSON.stringify({ role: 'moderator' }) },
);
```

## 2. Moderate as the bot (bot key)

Now switch to the **bot key**. Every call is authorized by two independent checks: the `bots:groups:moderate` scope *and* the bot's moderator role in `roomId`.

```ts
// CHERRY_BOT_KEY is your `cherry_bot_<botId>_<secret>` token.
const BOT = {
  Authorization: `Bearer ${process.env.CHERRY_BOT_KEY}`,
  'Content-Type': 'application/json',
};

// delete a spam message
await fetch('https://api.cherry.fun/api/v1/bots/deleteGroupMessage', {
  method: 'POST',
  headers: BOT,
  body: JSON.stringify({ roomId, messageId }),
});

// mute an offender (shadow-ban: they can't post, existing messages stay)
await fetch('https://api.cherry.fun/api/v1/bots/muteGroupMember', {
  method: 'POST',
  headers: BOT,
  body: JSON.stringify({ roomId, wallet }),
});

// ban a repeat abuser and wipe their messages
await fetch('https://api.cherry.fun/api/v1/bots/banGroupMember', {
  method: 'POST',
  headers: BOT,
  body: JSON.stringify({ roomId, wallet, deleteMessages: true }),
});
```

`kickGroupMember`, `unbanGroupMember`, and `unmuteGroupMember` follow the same `{ roomId, wallet }` shape - see the [full list](https://portal.cherry.fun/docs/api/members.md).

## Watching for messages to act on

Give the bot something to react to:

- **Bot key:** long-poll `GET /api/v1/bots/getUpdates` (scope `bots:updates:poll`) or configure a webhook (`bots:webhook:manage`) to receive new messages as they arrive.
- **Project key:** poll `GET /api/v1/apps/groups/:roomId/messages` (scope `messages:read`) for room history - respect the [rate limits](https://portal.cherry.fun/docs/api/rate-limits.md) and poll at a sane interval.

## Why two keys: the layered permission model

The scope and the role are **separate gates**, and both must pass:

- The **scope** (`bots:groups:moderate`) authorizes the API *call*.
- The bot's **in-room role** (owner / admin / moderator) authorizes the *action on others*.

> **Warning:** A scope alone is not permission to act. A bot with `bots:groups:moderate` that is only a plain member, or isn't in the room, is **denied** (`403 INSUFFICIENT_ROOM_ROLE`). This is why step 1 (promote to moderator) is required.

## Rules to remember

- The bot **can't moderate the room owner**, and a moderator bot can't act on admins.
- Bots **can't set roles**: only a project key (or a human owner/admin) can promote the bot in step 1.
- **Mute the bot** to instantly disable it: a muted bot's moderation calls are rejected. A working kill-switch for a misbehaving bot.
- **Ban** with `deleteMessages: true` purges the member's messages; **mute** leaves existing messages in place.

## Where next

- [Members & moderation](https://portal.cherry.fun/docs/api/members.md), both moderation models and every endpoint.
- [Scopes](https://portal.cherry.fun/docs/api/scopes.md) · [Rate limits & errors](https://portal.cherry.fun/docs/api/rate-limits.md).

---

<!-- https://portal.cherry.fun/docs/ai/for-ai-agents -->

# For AI agents

These docs are built to be consumed by AI coding assistants. Point your agent at them and it can [scaffold a Cherry integration end to end](https://portal.cherry.fun/docs/quickstart.md).

## llms.txt

[`llms.txt`](https://portal.cherry.fun/llms.txt) is a single plain-text file that indexes and links every page in these docs, plus the key facts (package name, API base URL, token format) up front, structured the way LLMs read best. It follows the [llms.txt convention](https://llmstxt.org).

```
https://portal.cherry.fun/llms.txt
```

**How to use it:** paste that URL (or the file's contents) into your AI assistant before asking it to integrate Cherry - in Cursor, Claude, or similar, it becomes context the model can pull the right API and SDK details from. Agents that can browse can fetch it directly. It's the fastest way to give an assistant accurate, current knowledge of the whole API surface without copying pages one by one.

## Integration skills

Cherry ships ready-made **agent skills** (`SKILL.md` files for tools like Claude Code) that turn "add Cherry chat to my app" into a guided, correct integration: the right auth mode, backend token signing, theming, events, and security rules.

| Skill | Use it for | Source |
|---|---|---|
| `cherry-embed-integration` | Embedding Cherry chat with `@cherrydotfun/chat-embed-sdk` (web, React Native, Flutter) | [cherrydotfun/chat-embed-sdk](https://github.com/cherrydotfun/chat-embed-sdk/tree/main/skills) |
| `cherry-miniapp-integration` | Running an existing dApp inside Cherry with `@cherrydotfun/miniapp-sdk` | [cherrydotfun/miniapp-sdk](https://github.com/cherrydotfun/miniapp-sdk/tree/main/skills) |

If your assistant supports skills, install the one that matches your task and ask it to integrate Cherry: it will follow the same patterns documented here.

## Setup prompt

The embed editor in the [dashboard](https://portal.cherry.fun/dashboard) generates a ready-to-paste setup prompt tailored to your embed (its `appId`, auth mode, and theme). Copy it into your AI assistant to scaffold the mount code for your exact configuration.

## Tips for accurate output

- The npm package is **[`@cherrydotfun/chat-embed-sdk`](https://portal.cherry.fun/docs/embed/installation.md)**; the class is **`CherryEmbed`**.
- The [Cherry API](https://portal.cherry.fun/docs/api/authentication.md) has two surfaces: the **Apps API** at **`https://api.cherry.fun/api/v1/apps`** (auth **`Bearer cherry_sk_<projectId>_<secret>`**, a project key) and the **Bot API** at **`https://api.cherry.fun/api/v1/bots`** (auth **`Bearer cherry_bot_<botId>_<secret>`**, a bot key). Each key is **one opaque token** copied from the portal, never assembled from an app ID plus a secret. `cha_<id>_<secret>` is a deprecated legacy format.
- Bot moderation is gated by **two** layers: the `bots:groups:moderate` scope **and** the bot's in-room role (owner/admin/moderator) - see [Members & moderation](https://portal.cherry.fun/docs/api/members.md).
- Keep API keys and the **app secret** server-side: the secret signs embed tokens; API keys authenticate the Cherry API.

---

<!-- https://portal.cherry.fun/docs/embed/installation -->

# Installation

The Chat Embed SDK renders Cherry chat inside your web app. It's published on npm and works in any modern bundler (Vite, Next.js, Webpack) or straight from a `<script>` tag.

> **Tip:** Want to see it before installing? The [live embed builder](https://cherry.fun/chat-embed-example/) runs the chat in your browser with no signup or backend, and its "Show the integration snippet" button gives you copy-paste code to drop in.

## npm (recommended)

```bash
npm install @cherrydotfun/chat-embed-sdk
```

The package ships ESM, CommonJS, and TypeScript types, no `@types` package needed.

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

Other package managers work the same way:

```bash
pnpm add @cherrydotfun/chat-embed-sdk
bun add @cherrydotfun/chat-embed-sdk
yarn add @cherrydotfun/chat-embed-sdk
```

## Script tag (no build step)

For a plain HTML site, load the package from npm via jsDelivr. The global build exposes `window.CherryEmbedSDK`:

```html
<script src="https://cdn.jsdelivr.net/npm/@cherrydotfun/chat-embed-sdk@0.1.5/dist/index.global.js"></script>
<script>
  const chat = new window.CherryEmbedSDK.CherryEmbed({ /* config */ });
  chat.mount();
</script>
```

> **Tip:** Pin the version in the CDN URL (`@0.1.5`) so a future release can't change behavior under you. With npm, your lockfile already does this.

## Mobile (React Native / Flutter)

The SDK is browser-only, so it can't run directly in a mobile JS runtime. On mobile you run it inside a WebView on a small host page and bridge wallet signing to the native layer: see [React Native & Flutter](https://portal.cherry.fun/docs/embed/mobile.md).

## Requirements

- A Cherry **embed** (created in your [project's](https://portal.cherry.fun/dashboard) **Chat embeds** section), it gives you the `appId`.
- Your site's origin added to the embed's **Allowed origins**.
- A mount target: an element on your page (for inline embeds) or nothing (for floating widgets).

## Next steps

- [Configuration](https://portal.cherry.fun/docs/embed/configuration.md), every option `CherryEmbed` accepts.
- [Authentication](https://portal.cherry.fun/docs/embed/authentication.md), wallet-only vs. backend-signed tokens.

---

<!-- https://portal.cherry.fun/docs/embed/configuration -->

# Configuration

You configure the widget by passing a config object to the `CherryEmbed` constructor:

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

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

await chat.mount();
```

> **Tip:** Want to try options before writing code? The [live embed builder](https://cherry.fun/chat-embed-example/) lets you toggle display mode, theme, and colors in real time and copies out a ready-to-paste config snippet, no signup or backend required.

## Options

| Option | Type | Default | Notes |
|---|---|---|---|
| `appId` | `string` |  | **Required.** Your embed's ID, from [the portal](https://portal.cherry.fun/dashboard). |
| `container` | `string \| HTMLElement` |  | **Required for inline embeds.** CSS selector or element to mount into. Omit for floating widgets. |
| `roomId` | `string` |  | The room to open. Required in `single` mode; optional in `list` / `external-controlled`. |
| `mode` | `'single' \| 'list' \| 'external-controlled'` | `'single'` | How rooms are presented; only `single` is available today. See [Display modes](https://portal.cherry.fun/docs/embed/display-modes.md). |
| `position` | `'inline' \| 'floating-right' \| 'floating-left'` | `'inline'` | Inline mounts into `container`; floating pins the chat panel to a viewport corner. |
| `collapsed` | `boolean` | `false` | For floating widgets, start hidden; open from your own UI via `show()` / `toggle()`. |
| `token` | `string` |  | Short-lived JWT for `app-trusted` / `app-trusted+wallet` auth. See [Authentication](https://portal.cherry.fun/docs/embed/authentication.md). |
| `walletAddress` | `string` |  | The user's Solana address, for wallet-backed auth. Not needed in pure `app-trusted` mode: the token's `sub` claim carries it. |
| `signChallengeHandler` | `(message: Uint8Array) => Promise<Uint8Array>` |  | Signs the wallet challenge for wallet-backed auth. Register **before** `mount()`. Not used in pure `app-trusted` mode. |
| `theme` | `EmbedTheme` |  | Colors and typography. See [Theming](https://portal.cherry.fun/docs/embed/theming.md). |
| `layout` | `EmbedLayout` |  | Toggle UI chrome (header, avatars, input, …). See below. |
| `embedUrl` | `string` | `'https://embed.cherry.fun'` | Origin the chat iframe is served from. Only override for self-hosted deployments. |

## Layout

`layout` controls which pieces of UI the iframe renders:

```ts
const chat = new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  container: '#cherry-chat',
  layout: {
    showHeader: true,
    headerTitle: 'Support',
    showMemberCount: true,
    showAvatars: true,
    showTimestamps: true,
    showReactions: true,
    showInput: true,
    maxHeight: '600px',
  },
});
```

| Field | Type | Notes |
|---|---|---|
| `showHeader` | `boolean` | Show the room header bar. |
| `headerTitle` | `string` | Override the header title. |
| `showMemberCount` | `boolean` | Show the member count. |
| `showAvatars` | `boolean` | Show sender avatars. |
| `showTimestamps` | `boolean` | Show message timestamps. |
| `showReactions` | `boolean` | Allow message reactions. |
| `showInput` | `boolean` | Show the composer (set `false` for a read-only feed). |
| `maxHeight` | `string` | CSS max-height for the widget. |

You can change layout after mount with `chat.setLayout({ … })`.

## App-trusted (zero-signature)

Embeds set to pure `app-trusted` auth pass only `token`; there is no wallet connect on the page, so `walletAddress` and `signChallengeHandler` are omitted entirely:

```ts
// The backend derives the wallet from its own authenticated session and puts
// it in the token's `sub` claim; the page never learns or sends the address.
const { token } = await fetch('/api/cherry-embed-token', { method: 'POST' })
  .then((r) => r.json());

const chat = new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  container: '#cherry-chat',
  roomId: 'YOUR_ROOM_ID',
  token,
});

await chat.mount();
```

Because your backend's word is the only identity proof, the mode runs with server-side restrictions (a fail-closed room allowlist, message rate limits, moderation off by default). Turn it on yourself in the portal's auth-mode selector. Trust model, token contract, and the full restrictions list: [Authentication](https://portal.cherry.fun/docs/embed/authentication.md).

## Next steps

- [Authentication](https://portal.cherry.fun/docs/embed/authentication.md) · [Display modes](https://portal.cherry.fun/docs/embed/display-modes.md) · [Theming](https://portal.cherry.fun/docs/embed/theming.md) · [SDK API reference](https://portal.cherry.fun/docs/embed/api-reference.md)

---

<!-- https://portal.cherry.fun/docs/embed/authentication -->

# Authentication

Cherry chat identifies users by their Solana wallet. The SDK supports three auth modes: you pick one when you [configure the embed](https://portal.cherry.fun/docs/embed/configuration.md) in the portal, and wire the matching client code. Choose based on whether you run a backend and whether you want users to prove wallet ownership.

| Mode | Backend? | Wallet signature? | Use when |
|---|---|---|---|
| `wallet-only` | No | Yes (user signs) | No backend; users bring their own wallet. Public rooms. |
| `app-trusted+wallet` | Yes | Yes (user signs) | You run a backend and want verified wallet identity. **Most common.** |
| `app-trusted` | Yes | No | Zero-signature: your backend is the sole identity source. Self-serve: pick it in the portal's auth-mode selector. |

## wallet-only

No backend. The user connects a wallet and signs a challenge; the iframe handles the flow. Just mount:

```ts
const chat = new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  container: '#cherry-chat',
  roomId: 'YOUR_ROOM_ID',
  mode: 'single',
});

await chat.mount();
```

## app-trusted + wallet

Your backend mints a short-lived token for the connected wallet, and the user signs a challenge to prove they own it. This is the default for the public API.

### 1. Mint tokens on your backend

The token is a JWT signed with your embed's **app secret** (from the portal), with the user's wallet as `sub` and your `appId` as `app_id`. Keep the secret server-side only.

```ts
// POST /api/cherry-embed-token  - your server
import jwt from 'jsonwebtoken';
import { randomUUID } from 'node:crypto';

const token = jwt.sign(
  { sub: walletAddress, app_id: process.env.CHERRY_APP_ID },
  process.env.CHERRY_APP_SECRET,
  { algorithm: 'HS256', expiresIn: '5m', jwtid: randomUUID() },
);
```

> **Note:** A complete, runnable token server lives in the public [`chat-embed-sdk`](https://github.com/cherrydotfun/chat-embed-sdk/tree/main/example/app-trusted+wallet) repo, under `example/app-trusted+wallet` (its `server.js`).

### 2. Mount with the token + a sign handler

Fetch a token, then mount. Register `signChallengeHandler` **before** `mount()`: the iframe calls it to get the user's signature.

```ts
const provider = window.phantom?.solana;
const { publicKey } = await provider.connect();
const walletAddress = publicKey.toString();

const { token } = await fetch('/api/cherry-embed-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ walletAddress }),
}).then((r) => r.json());

const chat = new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  container: '#cherry-chat',
  roomId: 'YOUR_ROOM_ID',
  token,
  walletAddress,
  signChallengeHandler: async (message) => {
    // message: Uint8Array. Sign the bytes as-is, don't re-encode them
    const { signature } = await provider.signMessage(message, 'utf8');
    return signature; // Uint8Array
  },
});

await chat.mount();
```

### 3. Session renewal is automatic

The embed token is short-lived (~5 min) by design: mint it fresh right before `mount()`, don't cache it. After the initial exchange the iframe holds a short-lived Cherry session and silently re-establishes it from a rotating refresh token whenever the page (re)loads, so there's nothing for you to refresh on a timer. If you ever need to force a fresh exchange (e.g. the user switches accounts in your app), mint a new token and call `chat.setToken(token)`.

## app-trusted (zero-signature)

The same backend-minted token as above, but with no wallet signature at all: your backend is the sole source of identity truth, and the user never connects a wallet or signs anything on your page. This mode is self-serve: pick it in the portal's auth-mode selector when you configure the embed.

### How it works

1. Your backend authenticates the user through its own login session.
2. It mints the exact same JWT as in `app-trusted+wallet`: `sub` is the user's wallet, `app_id` is your embed ID, HS256 with the app secret, ~5 min expiry, unique `jwtid`.
3. The page fetches the token and mounts with it. No `walletAddress`, no `signChallengeHandler`, no wallet UI: the token's `sub` claim carries the identity.

```ts
// Your backend derives the wallet from ITS OWN session. Never accept a
// wallet address from the request body: with no signature to check, a
// body-supplied address would let any client impersonate any wallet.
const { token } = await fetch('/api/cherry-embed-token', { method: 'POST' })
  .then((r) => r.json());

const chat = new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  container: '#cherry-chat',
  roomId: 'YOUR_ROOM_ID',
  token,
});

await chat.mount();
```

### The trust model

In the wallet-backed modes the user proves wallet ownership with an Ed25519 signature that Cherry verifies. Here Cherry only verifies that the token was signed with your app secret; whatever `sub` your backend asserts is accepted as-is. Cherry cannot tell a real wallet owner from an impersonated one, which has two consequences:

- `sub` must come only from your authenticated session, never from client input (request body, query, headers you don't control).
- The mode runs with server-side restrictions, below.

### Server-side restrictions

- **Allowed rooms are mandatory and fail-closed.** The chat works only in the rooms allowed for your embed; any other room returns `403`.
- **Message rate limits** apply (about 20 messages per minute per user by default); exceeding them returns `429`.
- **Moderation from the embed is off by default**, governed by the embed's server-side policy.
- **Embed sessions live up to 15 minutes** and refresh automatically, so there is nothing to refresh on your side.

Treat `403` and `429` responses from these rules as policy, not as bugs in your integration or a broken token.

> **Note:** Turn this mode on yourself: open the embed in the portal and pick **App-trusted (zero-signature)** in the auth-mode selector. Make sure the rooms you need are allowed for the embed.

## Security notes

- The **app secret** signs tokens: keep it on your server, never ship it to the browser.
- Tokens are short-lived by design; mint them fresh right before `mount()`. Session renewal afterwards is automatic.
- `walletConnectRequested` fires when a user clicks "connect" in a preview state: re-arm auth by calling `setToken()` and `setWalletAddress()`. (Wallet-backed modes only; it never fires in pure `app-trusted`.)

## Next steps

- [Display modes](https://portal.cherry.fun/docs/embed/display-modes.md) · [SDK API reference](https://portal.cherry.fun/docs/embed/api-reference.md)
- Full walkthrough: [Guides › Authenticated chat](https://portal.cherry.fun/docs/guides/authenticated-chat.md)

---

<!-- https://portal.cherry.fun/docs/embed/display-modes -->

# Display modes

Two independent axes control how the widget appears: **mode** (how rooms are presented) and **position** (how it mounts on the page).

## Room modes

Set with `mode`.

### `single` (default)

Locks the embed to one room (`roomId`). No room switcher: ideal for a support widget or a single community room.

```ts
new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  container: '#cherry-chat',
  roomId: 'YOUR_ROOM_ID',
  mode: 'single',
});
```

> **Warning:** Only `single` is available today. `list` and `external-controlled` (and the `roomChanged` event) are documented ahead of runtime support; selecting them currently behaves like `single`.

### `list`

When available, `list` will render Cherry's room-list UI so the user picks among the rooms they belong to (omit `roomId`). Not wired up yet: currently behaves like `single`.

```ts
new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  container: '#cherry-chat',
  mode: 'list',
});
```

### `external-controlled`

When available, your app will drive navigation: mount once, then call `setRoom()` whenever your UI changes, e.g. the user opens a different match, order, or channel, and listen for `roomChanged`. Not wired up yet: currently behaves like `single`, and `roomChanged` does not fire.

```ts
const chat = new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  container: '#cherry-chat',
  mode: 'external-controlled',
});
await chat.mount();

// later: switch rooms from your own UI
chat.setRoom('room_abc123');

chat.on('roomChanged', ({ roomId }) => {
  console.log('active room is now', roomId);
});
```

> **Tip:** Pair `external-controlled` with the [Cherry API](https://portal.cherry.fun/docs/api/rooms.md): create a room on your backend, then call `setRoom(newRoomId)` to drop the user straight into it.

## Position

> **Tip:** Want to see the modes side by side? Toggle floating vs. inline live in the [Cherry embed builder](https://cherry.fun/chat-embed-example/), no signup or backend required.

Set with `position`.

- **`inline`** (default): mounts into your `container` element and flows with your layout.
- **`floating-right` / `floating-left`:** pins the chat panel to a viewport corner. Omit `container`. Use `collapsed: true` to start hidden (the widget doesn't render its own launcher button), and open it from your own UI via `chat.show()` / `chat.toggle()`.

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

// collapsed starts hidden: wire your own button to open it
document.querySelector('#open-chat')?.addEventListener('click', () => chat.toggle());
```

Toggle a floating widget programmatically with `chat.show()`, `chat.hide()`, and `chat.toggle()`.

## Next steps

- [Theming](https://portal.cherry.fun/docs/embed/theming.md) · [SDK API reference](https://portal.cherry.fun/docs/embed/api-reference.md)

---

<!-- https://portal.cherry.fun/docs/embed/theming -->

# Theming

The widget is fully themeable to match your brand: colors, typography, and message styling. Pass a `theme` object at mount, or update it live with `setTheme()`.

```ts
new CherryEmbed({
  appId: 'YOUR_EMBED_ID',
  container: '#cherry-chat',
  roomId: 'YOUR_ROOM_ID',
  theme: {
    mode: 'dark',
    primaryColor: '#FF5BA8',
    accentColor: '#7C5CFF',
    fontFamily: 'Inter',
    fontSize: 'md',
  },
});
```

Every field is optional: set only what you want to override; the rest fall back to sensible defaults derived from `mode` and `primaryColor`.

> **Tip:** Want to see these colors change in real time? The [live embed builder](https://cherry.fun/chat-embed-example/) lets you tweak presets, brand hue, and per-side accents with no signup, then copies a ready-to-paste integration snippet.

## Updating the theme at runtime

```ts
chat.setTheme({ primaryColor: '#22C55E' }); // merges with the current theme
chat.resetTheme();                          // clear back to defaults before applying a full new theme
```

> **Note:** When switching between full themes (e.g. a light/dark toggle), call `resetTheme()` first so stale derived colors don't leak into the new theme.

## Theme reference

`mode`, `fontSize`, and the colors below make up the `EmbedTheme` type. Colors accept any CSS color string (hex, rgb, rgba).

### Base

| Field | Type | Notes |
|---|---|---|
| `mode` | `'dark' \| 'light'` | Base variant; defaults the rest of the palette. |
| `primaryColor` | `string` | Primary brand color. |
| `accentColor` | `string` | Secondary/accent color. |
| `backgroundColor` | `string` | Widget background. |
| `surfaceColor` | `string` | Cards / surfaces. |
| `borderColor` | `string` | Borders / dividers. |

### Text

| Field | Notes |
|---|---|
| `textColor` | Primary text. |
| `textSecondaryColor` | Muted / secondary text. |
| `linkColor` | Hyperlinks. |
| `linkColorOwn` | Hyperlinks inside your own messages. |

### Message bubbles

| Field | Notes |
|---|---|
| `incomingBubbleColor` | Incoming bubble fill. |
| `incomingBubbleBorderColor` | Incoming bubble border. |
| `ownBubbleColor` | Your own bubble fill (defaults to a primary→accent gradient). |
| `ownBubbleTextColor` | Your own bubble text. |

### Header & input

| Field | Notes |
|---|---|
| `headerColor` / `headerTextColor` | Header bar background / text. |
| `inputColor` / `inputTextColor` | Composer background / text. |
| `sendButtonColor` / `sendButtonTextColor` | Send button fill / text. |

### Accents & chrome

| Field | Notes |
|---|---|
| `messageOwnAccentColor` / `messageOwnAccentSoftColor` | Reaction chips on your messages (active / passive). |
| `messageOtherAccentColor` / `messageOtherAccentSoftColor` | Reaction chips on others' messages. |
| `ownEmbedBgColor` / `otherEmbedBgColor` | Rich embed card backgrounds. |
| `messageActionsColor` / `messageActionsTextColor` | Hover message-actions menu. |
| `tooltipColor` / `tooltipTextColor` | Tooltips. |
| `emojiPickerColor` | Emoji picker surface. |
| `iconButtonColor` / `iconButtonHoverColor` | Icon buttons. |
| `avatarHoverColor` | Avatar hover ring. |
| `loaderColor` | Loading spinner. |
| `roleBadgeColor` | Role badge tint. |
| `modalOverlayColor` | Modal backdrop. |
| `dangerColor` | Destructive actions. |

### Typography

| Field | Type | Notes |
|---|---|---|
| `fontFamily` | `string` | Font name, e.g. `'Inter'`, `'Space Grotesk'`, `'system-ui'`. |
| `fontSize` | `'sm' \| 'md' \| 'lg'` | Base text size. |

> **Tip:** The interactive embed editor in the [dashboard](https://portal.cherry.fun/dashboard) previews these live and emits a ready-to-paste config, the fastest way to dial in a theme.

## Next steps

- [SDK API reference](https://portal.cherry.fun/docs/embed/api-reference.md), `setTheme`, events, and the full method surface.

---

<!-- https://portal.cherry.fun/docs/embed/moderation -->

# Moderation

Every embed ships with a built-in moderation layer you configure in the editor's **Moderation** tab (open the embed in the [dashboard](https://portal.cherry.fun/dashboard), then **Moderation**). The rules are enforced by Cherry's servers on the message send path, not in the browser, so a visitor cannot bypass them by editing client code or calling the API directly.

Moderation is off by default: a new embed allows everything. Turn on only the rules you need, then **Save** (moderation is stored with the rest of the embed's settings).

> **Note:** This is different from the read-only **Embed policy** card in the editor. The Moderation tab is your own self-serve setting. The separate Embed policy (whether embed users can perform moderation actions like kick, ban, or mute, plus rate and message-length limits) is set by Cherry and shown read-only. See [Authentication](https://portal.cherry.fun/docs/embed/authentication.md) for the policy limits.

## Minimum wallet age

Require a visitor's Solana wallet to be at least a given number of days old, measured from its first on-chain transaction, before they can post. It is a low-friction filter against throwaway wallets and freshly minted bots.

- Range: **0 to 365 days**. `0` turns the check off (the default).
- A wallet with no transactions has an age of zero, so any non-zero threshold blocks it.

## Blocked words

A list of words that silently hide a message. When a posted message contains a blocked word, it is shadow-dropped: the **sender still sees their own message**, but no one else receives it. There is no visible rejection, so a spammer gets no signal to adjust and retry.

- Matching is **case-insensitive** (words are stored lowercased and de-duplicated).
- Up to **200 words**, each **1 to 100 characters**.

## Links

Choose how links posted in the chat are handled:

| Policy | Behavior |
|---|---|
| **Allow all** (default) | Links are never touched. |
| **Allowlist** | Only links whose host is in your allowed-domains list pass; every other link is blocked. An empty allowlist blocks every link. |
| **Block all** | Every link is blocked. |

When you pick **Allowlist**, add the domains you trust:

- Enter **bare hosts** like `example.com`, lowercased, with no scheme, port, or path (`https://example.com/path` is rejected).
- Each host is a valid domain (labels of `a-z`, `0-9`, and `-`), up to 253 characters.
- Up to **100 domains**.

## Images and GIFs

Two independent toggles, both **on** by default. Turn **Images** off to block image messages, or **GIFs** off to block GIFs. They are separate switches, so you can allow one and block the other.

## Limits at a glance

| Rule | Limit |
|---|---|
| Minimum wallet age | 0 to 365 days |
| Blocked words | up to 200, each 1 to 100 characters |
| Allowlist domains | up to 100 bare hosts, each up to 253 characters |

The portal rejects values outside these bounds before saving, and the server enforces the same limits, so an out-of-range value never reaches a live embed.

## Next steps

- [Configuration](https://portal.cherry.fun/docs/embed/configuration.md) · [Authentication](https://portal.cherry.fun/docs/embed/authentication.md) · [Theming](https://portal.cherry.fun/docs/embed/theming.md)
- [SDK API reference](https://portal.cherry.fun/docs/embed/api-reference.md)

---

<!-- https://portal.cherry.fun/docs/embed/mobile -->

# React Native & Flutter

The Chat Embed SDK is browser-only: it creates an `<iframe>` via `document`, listens on `window` `message` events, and posts to `iframe.contentWindow`. A mobile JS runtime has none of those, so `CherryEmbed` cannot run directly in React Native or Dart. The supported approach on mobile: run the SDK inside a WebView on a small **host page**, and bridge wallet signing out to the native layer (Mobile Wallet Adapter on Android, a deeplink wallet on iOS).

> **Warning:** Do not point the WebView straight at `embed.cherry.fun`. The SDK's `signChallenge` bridge rejects when `window.parent === window`, so the embed must be nested in an iframe on a host page, never loaded as the top-level document.

Runnable, copy-paste examples live in the public SDK repo: [`example/react-native/`](https://github.com/cherrydotfun/chat-embed-sdk/tree/main/example/react-native) and [`example/flutter/`](https://github.com/cherrydotfun/chat-embed-sdk/tree/main/example/flutter). One shared host page serves both platforms (it auto-detects the bridge).

## Why a naive setup fails

Three separate walls, in the order people usually hit them:

1. **The SDK is DOM-only.** Importing `CherryEmbed` into React Native and calling `mount()` throws: there is no `document` or `iframe`. The SDK must live in a WebView.
2. **The embed requires a parent frame.** Loaded as the WebView's top document, the iframe-side bridge sees `window.parent === window` and never sends the `signChallenge` request, so signing never starts.
3. **There is no `window.phantom` in a mobile WebView.** On mobile the wallet lives in the native layer, so the signature must cross the WebView-to-native boundary.

## Architecture

```
Native app (wallet: MWA on Android / deeplink on iOS)
   |  inject JS  <->  message channel
   v
WebView -> host page (runs the CherryEmbed SDK, creates the iframe)
   v
iframe -> embed.cherry.fun (the chat)
```

- **Host page**: a minimal HTML page that loads the SDK bundle and calls `new CherryEmbed({ ... })`. Its `signChallengeHandler` does not sign anything itself; it forwards the challenge bytes to native and awaits the signature.
- **Native wrapper**: a WebView component that sends config down, receives sign requests, signs with the real wallet, and injects the signature back.

Both are already written for you: `CherryChatWebView.tsx` (React Native), `cherry_chat_webview.dart` (Flutter), and the shared `host.html` in the SDK repo implement the full bridge protocol.

## Bridge protocol

Native to host page (global functions on the page, called via injected JS):

| Call | Purpose |
|---|---|
| `window.__cherryReceiveConfig(json)` | Deliver config and mount / remount the chat. |
| `window.__cherrySignResult(id, signatureB64, errorOrNull)` | Resolve a pending `signChallenge`. |
| `window.__cherryCommand(method, paramsJson)` | Imperative SDK calls: `setWalletAddress`, `setToken`, `setRoom`, `setTheme`, `signOut`, `show`, `hide`. |

Host page to native (JSON messages over the platform channel):

| Message | Meaning |
|---|---|
| `{ type: 'ready' }` | Page loaded, ready for config. Native replies with `__cherryReceiveConfig`. |
| `{ type: 'sign', id, message }` | `signChallenge` fired; `message` is the base64 challenge bytes. Native signs and replies with `__cherrySignResult`. |
| `{ type: 'event', event, data }` | A forwarded SDK event (`ready`, `mounted`, `authStateChange`, `unreadCount`, `message`, `tokenExpired`, `error`, `walletConnectRequested`, `preview`, `roomChanged`). |

## Two ways to ship the host page

| | Hosted | Bundled |
|---|---|---|
| Host page lives | on your web server (`host.html`) | inside the app binary (a string) |
| WebView source | `{ uri }` / `loadRequest(url)` | `{ html }` / `loadHtmlString(html)` |
| Update the host page | redeploy web, no app release | ship an app release |
| Page origin | your https origin | none (`null`) |
| Allowed origins entry | `https://yoursite.com` | `null` (or prefer Hosted) |

Both variants still fetch the SDK bundle and the chat iframe over the network; the chat is a hosted iframe either way.

## Hosting the SDK bundle

The host page loads the SDK as a global (`window.CherryEmbedSDK`), the IIFE build (`dist/index.global.js`, ~10 KB).

- **Cherry-hosted (default):** `https://embed.cherry.fun/cherry-embed.js`. A rolling URL, same origin as the chat iframe, refreshed on each embed deploy and short-cached. Nothing to host yourself.
- **Self-hosted:** build the SDK (`npm run build`) and serve `dist/index.global.js` as `application/javascript`, next to your host page or on any CDN. Pin a hashed filename if you need a frozen version.

## Auth modes on mobile

The same [auth modes](https://portal.cherry.fun/docs/embed/authentication.md) apply, with one mobile-specific rule for the wallet-backed modes: never rely on the iframe's built-in web wallet adapter; drive signing natively through the bridge.

- **`wallet-only`**: no backend, no token. Pass `walletAddress` and wire the sign callback.
- **`app-trusted+wallet`**: your backend mints a short-lived embed token bound to the wallet; the user also signs the challenge. Pass `token` + `walletAddress` + the sign callback.
- **`app-trusted`** (zero-signature, self-serve in the portal): token only; `onSign` never fires. See the no-signing path below.

### app-trusted: the no-native-signing path

Pure `app-trusted` removes the entire wallet layer from the mobile integration. The WebView host page path still applies (the SDK is still browser-only), but everything wallet-related drops out:

- **Skip the wallet modules.** Don't copy `wallet.ts` / `wallet.dart`, and don't install the signing dependencies: no `@solana-mobile/mobile-wallet-adapter-protocol-web3js`, no `solana_mobile_client`, no deeplink wallet packages, no `<queries>` / URL-scheme platform setup. Only the WebView package is needed.
- **Skip the callbacks.** Don't pass `onSign` or `onWalletConnectRequested`; neither ever fires with a valid token.
- **Skip `walletAddress`.** The app never learns the wallet; the token's `sub` claim carries it.
- **Fetch the token from your backend** right before showing the chat and pass it in the bridge config's `token` field. The backend derives the wallet from its own authenticated session; the app sends nothing but the session credentials it already has.

```tsx
const [token, setToken] = useState<string>();

useEffect(() => {
  fetch('https://yoursite.com/api/cherry-embed-token', { method: 'POST' })
    .then((r) => r.json())
    .then(({ token }) => setToken(token));
}, []);

if (!token) return null; // mint fresh right before showing the chat

<CherryChatWebView
  source={{ html }}
  config={{ appId: 'YOUR_EMBED_ID', roomId: 'YOUR_ROOM_ID', token }}
  // No onSign, no onWalletConnectRequested: the token alone authenticates.
/>
```

`authStateChange` arrives with `true` shortly after mount (the token exchange), without any wallet round-trip. Note the mode's server-side restrictions (fail-closed room allowlist, message rate limits): a `403` or `429` there is policy, not a broken integration; see [Authentication](https://portal.cherry.fun/docs/embed/authentication.md).

## React Native

Install the WebView (plus MWA for Android signing):

```bash
npm install react-native-webview
npm install @solana-mobile/mobile-wallet-adapter-protocol-web3js @solana/web3.js
```

Copy [`CherryChatWebView.tsx`](https://github.com/cherrydotfun/chat-embed-sdk/blob/main/example/react-native/CherryChatWebView.tsx) and [`wallet.ts`](https://github.com/cherrydotfun/chat-embed-sdk/blob/main/example/react-native/wallet.ts) into your app, then render:

```tsx
import { CherryChatWebView, type CherryChatWebViewRef } from './CherryChatWebView';
import { connectWallet, signMessageWithWallet } from './wallet';

function ChatScreen() {
  const chatRef = useRef<CherryChatWebViewRef>(null);
  const [walletAddress, setWalletAddress] = useState<string>();

  return (
    <CherryChatWebView
      ref={chatRef}
      // Hosted host page; or source={{ html }} with buildCherryHostHtml()
      source={{ uri: 'https://yoursite.com/cherry-host.html' }}
      config={{
        appId: 'YOUR_EMBED_ID',
        roomId: 'YOUR_ROOM_ID',
        walletAddress, // set after the user connects
        // token: embedToken, // app-trusted+wallet only
        theme: { mode: 'dark', primaryColor: '#FF5BA8' },
      }}
      // Native signing: MWA on Android, deeplink wallet on iOS
      onSign={signMessageWithWallet}
      onWalletConnectRequested={async () => {
        const address = await connectWallet();
        setWalletAddress(address); // re-sends config, iframe starts signChallenge
      }}
      onEvent={(event, data) => {
        if (event === 'authStateChange') console.log('authenticated:', data);
      }}
    />
  );
}
```

For the bundled variant, build the page string with [`buildCherryHostHtml()`](https://github.com/cherrydotfun/chat-embed-sdk/blob/main/example/react-native/cherryHostHtml.ts) and pass `source={{ html }}`:

```tsx
const html = buildCherryHostHtml({ sdkUrl: 'https://embed.cherry.fun/cherry-embed.js' });
<CherryChatWebView source={{ html }} config={...} onSign={signMessageWithWallet} />
```

Full runnable apps: [`App.hosted.tsx`](https://github.com/cherrydotfun/chat-embed-sdk/blob/main/example/react-native/App.hosted.tsx) (app-trusted+wallet) and [`App.bundled.tsx`](https://github.com/cherrydotfun/chat-embed-sdk/blob/main/example/react-native/App.bundled.tsx) (wallet-only).

## Flutter

Same architecture, same host page, same bridge protocol; only the WebView plumbing differs:

| Concern | React Native | Flutter (`webview_flutter`) |
|---|---|---|
| Page to native | `window.ReactNativeWebView.postMessage` + `onMessage` | `JavaScriptChannel('CherryNative')` |
| Native to page | `webview.injectJavaScript(js)` | `controller.runJavaScript(js)` |
| Load hosted page | `source={{ uri }}` | `controller.loadRequest(Uri.parse(url))` |
| Load bundled page | `source={{ html }}` | `controller.loadHtmlString(html, baseUrl: ...)` |

Copy [`cherry_chat_webview.dart`](https://github.com/cherrydotfun/chat-embed-sdk/blob/main/example/flutter/lib/cherry_chat_webview.dart) and [`wallet.dart`](https://github.com/cherrydotfun/chat-embed-sdk/blob/main/example/flutter/lib/wallet.dart) into your app, then render:

```dart
CherryChatWebView(
  source: CherryChatSource.url('https://yoursite.com/cherry-host.html'),
  config: CherryChatConfig(
    appId: 'YOUR_EMBED_ID',
    roomId: 'YOUR_ROOM_ID',
    walletAddress: walletAddress, // set after the user connects
  ),
  onSign: signMessageWithWallet, // native MWA (Android) / Phantom deeplink (iOS)
  onWalletConnectRequested: connect,
  onEvent: (event, data) {
    if (event == 'authStateChange') debugPrint('authenticated: $data');
  },
)
```

Flutter-specific rules:

- **Name the `JavaScriptChannel` exactly `CherryNative`.** The shared host page tries `window.ReactNativeWebView` first, then `window.CherryNative`.
- **`JavaScriptMode.unrestricted`** is required.
- **`loadHtmlString` needs a `baseUrl`** on iOS/WKWebView so the null-origin document may load the remote SDK `<script src>`. Set it to the SDK origin (e.g. `https://embed.cherry.fun`).
- **Platform setup** (AndroidManifest `<queries>` for MWA, iOS `Info.plist` URL schemes for the deeplink wallet) is documented in the [Flutter example README](https://github.com/cherrydotfun/chat-embed-sdk/tree/main/example/flutter).

## Wiring the wallet

Implement two functions in the native layer:

- `connectWallet()`: resolves to the base58 public key.
- `signMessageWithWallet(bytes)`: resolves to the **raw 64-byte Ed25519 signature over the challenge bytes as-is**. The Cherry server verifies `ed25519.verify(signature, challengeBytes, walletPublicKey)`, so do not re-hash, prefix, or re-encode.

Android uses Mobile Wallet Adapter (`wallet.signMessages`); note MWA may return the message with the signature appended, so slice the last 64 bytes when the result is longer. iOS uses a deeplink wallet's `signMessage` (decode its base58 signature to bytes) and resolves the pending promise when the wallet redirects back into your app.

## Gotchas

- **The sign handler is registered in the host page constructor**, not after `mount()`: the first challenge can fire before a late handler attaches. The shared host page already does this.
- **60-second sign timeout.** The bridge auto-fails a `signChallenge` after 60s. Native wallet round-trips (app switch, MWA intent) fit comfortably; just don't block on your own UI longer.
- **Allowed origins.** The host page's origin must be in the embed's **Allowed origins**, else the iframe bridge drops host commands. `localhost` is always allowed for local testing; a bundled page has origin `null`.
- **Keep `domStorageEnabled` on.** The Cherry session lives in the iframe's `sessionStorage`.
- **iOS deeplinks navigate away and back.** Handle the return via your universal link handler and resolve the pending connect/sign promise there.

## Next steps

- [Authentication](https://portal.cherry.fun/docs/embed/authentication.md) · [Theming](https://portal.cherry.fun/docs/embed/theming.md) · [SDK API reference](https://portal.cherry.fun/docs/embed/api-reference.md)
- Full protocol write-up: [`docs/react-native.md`](https://github.com/cherrydotfun/chat-embed-sdk/blob/main/docs/react-native.md) in the SDK repo

---

<!-- https://portal.cherry.fun/docs/embed/api-reference -->

# SDK API reference

The complete surface of the `CherryEmbed` instance.

## Constructor

```ts
new CherryEmbed(config: CherryEmbedConfig)
```

See [Configuration](https://portal.cherry.fun/docs/embed/configuration.md) for the full config shape.

## Methods

### Lifecycle

| Method | Signature | Notes |
|---|---|---|
| `mount` | `() => Promise<void>` | Attaches the iframe and resolves when ready. Register `signChallengeHandler` first. |
| `destroy` | `() => void` | Removes the iframe and tears down listeners. |

### Rooms

| Method | Signature | Notes |
|---|---|---|
| `setRoom` | `(roomId: string) => void` | Switch the active room. Drives [`external-controlled` mode](https://portal.cherry.fun/docs/embed/display-modes.md). |

### Auth

| Method | Signature | Notes |
|---|---|---|
| `setToken` | `(token: string) => void` | Provide a fresh embed token and force a re-exchange (e.g. after an account switch). |
| `setWalletAddress` | `(address: string) => void` | Update the user's wallet address. |
| `signOut` | `() => void` | Clear the session and reload the iframe. |
| `onSignChallenge` | `(handler: SignChallengeHandler) => void` | Register the wallet sign handler (alternative to the config field). See [Authentication](https://portal.cherry.fun/docs/embed/authentication.md). |
| `offSignChallenge` | `() => void` | Remove the sign handler. |

### Theme & layout

| Method | Signature | Notes |
|---|---|---|
| `setTheme` | `(theme: Partial<EmbedTheme>) => void` | Merge theme changes. See [Theming](https://portal.cherry.fun/docs/embed/theming.md). |
| `resetTheme` | `() => void` | Reset to defaults before applying a new theme. |
| `setLayout` | `(layout: Partial<EmbedLayout>) => void` | Toggle UI chrome at runtime. |

### Visibility

| Method | Signature | Notes |
|---|---|---|
| `show` / `hide` / `toggle` | `() => void` | Show, hide, or toggle the widget (useful for floating mode). |

### Events

| Method | Signature |
|---|---|
| `on` | `(event, handler) => void` |
| `off` | `(event, handler) => void` |

### Getters

| Getter | Type | Notes |
|---|---|---|
| `isReady` | `boolean` | Iframe mounted and ready. |
| `isAuthenticated` | `boolean` | User is authenticated (not in preview). |
| `isVisible` | `boolean` | Widget currently visible. |
| `walletAddress` | `string \| undefined` | Current wallet address. |
| `currentMode` | `EmbedMode` | Active room mode. |

## Events

Subscribe with `chat.on(event, handler)`.

| Event | Payload | Fires when |
|---|---|---|
| `ready` | `void` | The widget has mounted and is ready. |
| `authStateChange` | `boolean` | Auth state flips (`true` = authenticated, `false` = preview). |
| `tokenExpired` | `void` | Reserved: not currently emitted (sessions renew silently in the iframe). |
| `walletConnectRequested` | `void` | The user asked to connect a wallet from a preview state. |
| `message` | `{ roomId: string; senderId: string; timestamp: number }` | A new message arrives. |
| `unreadCount` | `number` | The unread count changes. |
| `roomChanged` | `{ roomId: string }` | Reserved: not currently emitted (only `single` mode is available today). |
| `preview` | `{ visible: boolean; gated: boolean }` | The widget enters/leaves a gated preview state. |
| `error` | `{ code: string; message: string }` | Reserved: not currently emitted. |

```ts
chat.on('ready', () => console.log('chat ready'));
chat.on('unreadCount', (n) => updateBadge(n));
chat.on('message', ({ roomId }) => console.log('new message in', roomId));
```

## Types

The package ships full TypeScript types - import them directly:

```ts
import type {
  CherryEmbedConfig,
  EmbedTheme,
  EmbedLayout,
  EmbedMode,
} from '@cherrydotfun/chat-embed-sdk';
```

## Next steps

- Drive rooms from your backend: [Cherry API](https://portal.cherry.fun/docs/api/authentication.md).
- End-to-end: [Guides](https://portal.cherry.fun/docs/guides/public-chat.md).

---

<!-- https://portal.cherry.fun/docs/api/authentication -->

# Cherry API: Authentication

The Cherry API is a REST API you call from **your backend** to manage Cherry chat programmatically: create rooms, send messages, and moderate members.

There are **two kinds of API key**, each a single opaque token you copy from [the portal](https://portal.cherry.fun/dashboard):

| Key | Format | Surface | Base URL |
|---|---|---|---|
| **Project key** | `cherry_sk_<projectId>_<secret>` | Apps API: manage rooms, members, and messages your **project** owns | `https://api.cherry.fun/api/v1/apps` |
| **Bot key** | `cherry_bot_<botId>_<secret>` | Bot API: act as a specific **bot** (DMs, group posts, in-room moderation) | `https://api.cherry.fun/api/v1/bots` |

> **Warning:** A key is a **secret**. Make these calls from your server only, never from the browser.

## The key is one opaque token

Copy the whole string from the portal and use it verbatim. Do **not** try to assemble it from an app ID plus a secret: the `<projectId>`/`<botId>` and `<secret>` are already baked into the single token you're shown.

> **Note:** The token is shown **once**, when you create it. Store it in your server's secrets. Lost it, or need to roll a secret you think is exposed? **Both project keys and bot keys** can be rotated in place (see below): rotation issues a fresh secret for the same key and invalidates the old one immediately.

```http
Authorization: Bearer cherry_sk_<projectId>_<secret>
```

```bash
# project key → Apps API
curl https://api.cherry.fun/api/v1/apps/me \
  -H "Authorization: Bearer cherry_sk_<projectId>_<secret>"

# bot key → Bot API
curl https://api.cherry.fun/api/v1/bots/me \
  -H "Authorization: Bearer cherry_bot_<botId>_<secret>"
```

> **Note:** `cha_<id>_<secret>` is a **deprecated legacy** format. Older tokens keep working during a migration grace window and resolve to a bot identity, but issue new keys as `cherry_sk_` / `cherry_bot_` and migrate off `cha_`.

## Which key do I use?

- **Project key** (`cherry_sk_`) - the classic server flow: create rooms, invite members, send/read/delete messages, and moderate rooms **your project owns** (the call acts as the room owner). Holds Apps-API scopes like `groups:*`, `members:*`, `messages:*`.
- **Bot key** (`cherry_bot_`) - for a named bot with its own wallet and identity: send DMs, post to groups, run interactive messages, and moderate rooms **where the bot itself holds a role**. Holds `bots:*` scopes.

The two models compose - see [Members & moderation](https://portal.cherry.fun/docs/api/members.md) and the [moderation bot guide](https://portal.cherry.fun/docs/guides/moderation-bot.md).

## Verify your credentials

`GET /me` on each surface returns that key's context, a quick way to confirm auth and see your granted scopes and bot wallet.

```http
GET /api/v1/apps/me    # with a project key
GET /api/v1/bots/me    # with a bot key
```

```json
{
  "appId": "550e8400-e29b-41d4-a716-446655440000",
  "scopes": ["groups:create", "members:invite", "messages:send"],
  "botWallet": "7jx8aB2c5DeF9hGhI1jK3lMnOpQ5rStUvWxYzAbCdEf",
  "rateLimits": { "perMinute": 600, "perDay": 50000 }
}
```

## Managing keys & scopes

Create, scope, and revoke keys in the portal: **project keys** under your project's **API keys** section, **bot keys** under the bot's **Keys** section. Each key carries its own scopes: grant only what that key needs. See [Scopes](https://portal.cherry.fun/docs/api/scopes.md) for the full list and how to grant them.

**Both key types** can also be **rotated** in place: project keys from your project's **API keys** section, bot keys from the bot's **Keys** section. Rotation issues a fresh secret for the same key (its id, name and scopes are preserved) and invalidates the old secret immediately, so reach for it when a secret may be exposed. Rotating a **revoked** key reactivates it with a new secret, so you can bring a key name back without re-granting its scopes.

```http
POST /api/v1/projects/:projectId/api-keys/:keyId/rotate           # rotate a project key in place
POST /api/v1/projects/:projectId/bots/:botId/keys/:keyId/rotate   # rotate a bot key in place
```

The response returns the new token once, exactly like key creation, copy it immediately.

## Next steps

- [Create rooms & attach to embeds](https://portal.cherry.fun/docs/api/rooms.md), the core dynamic-rooms flow.
- [Scopes](https://portal.cherry.fun/docs/api/scopes.md) · [Members & moderation](https://portal.cherry.fun/docs/api/members.md) · [Rate limits & errors](https://portal.cherry.fun/docs/api/rate-limits.md) · [Endpoint reference](https://portal.cherry.fun/docs/api/reference.md)

---

<!-- https://portal.cherry.fun/docs/api/rooms -->

# Create rooms & attach to embeds

The most common server-side pattern: your backend creates a room on demand (a room per game, match, order, or community) and your frontend surfaces it in an embed. This page covers both halves.

## 1. Create a room

`POST /groups` creates a room owned by a wallet you specify, managed by your app. Requires the [`groups:create` scope](https://portal.cherry.fun/docs/api/scopes.md).

```http
POST /api/v1/apps/groups
Authorization: Bearer cherry_sk_<projectId>_<secret>
Content-Type: application/json
```

```json
{
  "ownerWallet": "7jx8aB...",
  "title": "Match #1042",
  "description": "Finals lobby",
  "initialMembers": ["walletA...", "walletB..."]
}
```

| Field | Type | Notes |
|---|---|---|
| `ownerWallet` | `string` | **Required.** Wallet that owns the room. |
| `title` | `string` | **Required.** 1–200 chars. |
| `description` | `string` | Optional, ≤1000 chars. |
| `avatarUrl` | `string` | Optional room avatar URL. |
| `initialMembers` | `string[]` | Optional wallets to invite + auto-accept on creation. |
| `settings` | `object` | Optional room settings. |
| `gatingRule` | `object` | Optional token/role gating. |
| `allowOwnerDetach` / `allowOwnerDelete` / `allowOwnerTransfer` | `boolean` | Owner capabilities (default `false`). |

Response:

```json
{ "roomId": "550e8400-e29b-41d4-a716-446655440000" }
```

The new room is tagged with your `appId` and marked app-created, so you can manage and (later) delete it.

## 2. Add members

Created the room without `initialMembers`, or need to add more? Use `POST /groups/:roomId/members` with `members:invite`. Set `autoAccept: true` to make them active immediately.

```json
{ "wallets": ["walletC...", "walletD..."], "autoAccept": true }
```

## 3. Surface it in an embed

A room your app created becomes available inside an embed once the viewer is an **active member** of it. How it's presented depends on the embed's [display mode](https://portal.cherry.fun/docs/embed/display-modes.md):

- **`single`** - pin the embed to the new room by passing its `roomId`:

  ```ts
  new CherryEmbed({ appId: 'YOUR_EMBED_ID', container: '#chat', roomId: newRoomId, mode: 'single' });
  ```

- **`external-controlled`** - mount once, then jump to the room from your UI:

  ```ts
  chat.setRoom(newRoomId);
  ```

- **`list`:** the user sees all the app rooms they belong to and picks one.

> **Tip:** End-to-end walkthrough: [Guides › A room per game / match / order](https://portal.cherry.fun/docs/guides/room-per-entity.md).

## Managing rooms

| Action | Endpoint | Scope |
|---|---|---|
| List your rooms | `GET /groups` | `groups:manage` |
| Get one room | `GET /groups/:roomId` | `groups:manage` |
| Update metadata | `PATCH /groups/:roomId` | `groups:manage` |
| Delete (app-created only) | `DELETE /groups/:roomId` | `groups:manage` |

You can only manage rooms your app created: touching another app's room returns `403 ROOM_NOT_MANAGED_BY_APP`. Deleting a room your app didn't create returns `403 CANNOT_DELETE_ASSIGNED_ROOM`.

## Next steps

- [Messages & bot actions](https://portal.cherry.fun/docs/api/messages.md) · [Members & moderation](https://portal.cherry.fun/docs/api/members.md)

---

<!-- https://portal.cherry.fun/docs/api/messages -->

# Messages & bot actions

Your app has a **bot wallet** (see it via `GET /me`). Messages you send through the [Cherry API](https://portal.cherry.fun/docs/api/authentication.md) are posted as that bot.

## Send a message

`POST /groups/:roomId/messages`: requires `messages:send`.

```http
POST /api/v1/apps/groups/:roomId/messages
Authorization: Bearer cherry_sk_<projectId>_<secret>
Content-Type: application/json
```

```json
{ "content": "Welcome to the match lobby! 🎮" }
```

| Field | Type | Notes |
|---|---|---|
| `content` | `string` | **Required.** 1–10,000 chars. |
| `messageType` | `string` | Optional custom type. |
| `metadata` | `object` | Optional custom metadata. |
| `attachments` | `array` | Optional attachments. |

Response:

```json
{ "success": true, "roomId": "room-uuid", "sender": "7jx8aB...botWallet" }
```

> **Note:** The sender is **always** your app's bot wallet. Any `senderId` in the body is ignored: the bot can't be made to impersonate a user.

## Read messages

`GET /groups/:roomId/messages`: requires `messages:read`. Newest first, cursor-paginated.

```http
GET /api/v1/apps/groups/:roomId/messages?limit=50&before=<messageId>
```

| Query | Type | Notes |
|---|---|---|
| `limit` | `integer` | Page size, default 50, max 100. |
| `before` | `string` | Cursor: message ID to page back from. |

```json
{
  "messages": [
    { "id": "msg-uuid", "content": "gg", "senderId": "7jx8aB...", "createdAt": "2026-06-24T10:00:00Z" }
  ],
  "nextCursor": "msg-uuid-or-null"
}
```

## Delete a message

`DELETE /groups/:roomId/messages/:messageId`: requires `messages:delete`. The bot can delete any message in [a room your app manages](https://portal.cherry.fun/docs/api/rooms.md).

```json
{ "success": true }
```

## Next steps

- [Members & moderation](https://portal.cherry.fun/docs/api/members.md) · [Scopes](https://portal.cherry.fun/docs/api/scopes.md)
- Build one: [Guides › Moderation bot](https://portal.cherry.fun/docs/guides/moderation-bot.md).

---

<!-- https://portal.cherry.fun/docs/api/members -->

# Members & moderation

Manage who's in a room and keep it healthy. Cherry has **two moderation models** - pick the one that matches your key:

- **Project key** (`cherry_sk_`) moderates rooms **your project owns**, acting as the room owner - `/api/v1/apps/...`, scope `members:moderate`.
- **Bot key** (`cherry_bot_`) moderates rooms where **the bot itself holds a role** (owner / admin / moderator) - `/api/v1/bots/...`, scope `bots:groups:moderate`.

## Invite (project key)

`POST /api/v1/apps/groups/:roomId/members` - bulk-invite wallets, requires `members:invite`. With `autoAccept: true` they become active immediately; otherwise they get a pending invite.

```json
{ "wallets": ["walletA...", "walletB..."], "autoAccept": false }
```

```json
{ "invited": ["walletA..."], "skipped": ["walletB..."], "accepted": [] }
```

`skipped` covers wallets already in the room or already invited.

## Project-key moderation

Rooms your project created are moderated with your **project key**. The call is made **as the room owner**, so it always has authority. Every route here needs `members:moderate`.

| Action | Endpoint | Body |
|---|---|---|
| Kick | `DELETE /api/v1/apps/groups/:roomId/members/:wallet` |  |
| Ban | `POST /api/v1/apps/groups/:roomId/members/:wallet/ban` | `{ "deleteMessages"?: boolean }` |
| Unban | `POST /api/v1/apps/groups/:roomId/members/:wallet/unban` |  |
| Mute | `POST /api/v1/apps/groups/:roomId/members/:wallet/mute` |  |
| Unmute | `POST /api/v1/apps/groups/:roomId/members/:wallet/unmute` |  |
| Set role | `POST /api/v1/apps/groups/:roomId/members/:wallet/role` | `{ "role": "admin" \| "moderator" \| "member" }` |

Notes:
- **Ban** with `deleteMessages: true` also removes that member's messages; the response includes `deletedCount`.
- **Mute** is a shadow-ban: the member can't post, but their existing messages stay. Mutes are indefinite: call **Unmute** to lift one.
- **Roles**: `owner` cannot be assigned via the API. **Set role** is a project-key power: bots cannot change roles.
- You can only act on [rooms](https://portal.cherry.fun/docs/api/rooms.md) your project manages → otherwise `403 ROOM_NOT_MANAGED_BY_APP`.

## Bot-key moderation

A **bot key** moderates from inside the room, using the bot's own in-room role, not project ownership. This lets a bot moderate any room it's been promoted in, even rooms your project doesn't own. Every route needs `bots:groups:moderate`, takes a JSON body, and posts as the bot's wallet.

| Action | Endpoint | Body |
|---|---|---|
| Ban | `POST /api/v1/bots/banGroupMember` | `{ "roomId", "wallet", "deleteMessages"?: boolean }` |
| Unban | `POST /api/v1/bots/unbanGroupMember` | `{ "roomId", "wallet" }` |
| Kick | `POST /api/v1/bots/kickGroupMember` | `{ "roomId", "wallet" }` |
| Mute | `POST /api/v1/bots/muteGroupMember` | `{ "roomId", "wallet" }` |
| Unmute | `POST /api/v1/bots/unmuteGroupMember` | `{ "roomId", "wallet" }` |
| Delete message | `POST /api/v1/bots/deleteGroupMessage` | `{ "roomId", "messageId" }` |

```http
POST /api/v1/bots/banGroupMember
Authorization: Bearer cherry_bot_<botId>_<secret>
Content-Type: application/json
```

```json
{ "roomId": "room-uuid", "wallet": "7jx8aB...", "deleteMessages": true }
```

A bot gets its authority the ordinary way: a project key (or a human owner) invites the bot's wallet into the room and promotes it - see the [moderation bot guide](https://portal.cherry.fun/docs/guides/moderation-bot.md).

## The layered permission model

Two independent checks gate every bot moderation call:

1. **The scope authorizes the API call.** Without `bots:groups:moderate`, the request is rejected before anything else (`403 INSUFFICIENT_SCOPE`).
2. **The bot's in-room role authorizes the action on others.** The bot must be an active, privileged member (owner / admin / moderator) of the target room, the *same* role model human moderators pass through.

> **Warning:** A scope is not permission to act. A bot with `bots:groups:moderate` but only a plain-member role, or one that isn't in the room at all, is **denied** (`403 INSUFFICIENT_ROOM_ROLE`).

Because in-room role is the second gate, these invariants always hold for bots:

- A bot **cannot moderate the room owner**, and a moderator bot cannot act on admins.
- A **muted** bot is denied: muting a misbehaving bot is a working kill-switch.
- Bots **cannot set member roles**: no bot can mint admins or escalate itself.
- The bot always acts as **its own wallet**; it never inherits the owner's authority.

## Next steps

- [Messages & bot actions](https://portal.cherry.fun/docs/api/messages.md) · [Scopes](https://portal.cherry.fun/docs/api/scopes.md) · [Rate limits & errors](https://portal.cherry.fun/docs/api/rate-limits.md) · [Endpoint reference](https://portal.cherry.fun/docs/api/reference.md)
- Build one: [Guides › Moderation bot](https://portal.cherry.fun/docs/guides/moderation-bot.md).

---

<!-- https://portal.cherry.fun/docs/api/scopes -->

# Scopes

Each Cherry API endpoint requires a specific scope. A key's granted scopes are listed in [`GET /me`](https://portal.cherry.fun/docs/api/authentication.md). Calling an endpoint without its scope returns `403 INSUFFICIENT_SCOPE`.

## Scopes come in two classes

Scopes are keyed to the surface they authorize, so they attach to the matching key type:

- **Project keys** (`cherry_sk_`) hold **Apps-API** scopes: `groups:*`, `members:*`, `messages:*`. They manage rooms, members, and messages the project owns.
- **Bot keys** (`cherry_bot_`) hold **`bots:*`** scopes: DMs, group posts, interactive messages, and in-room moderation as the bot.

Granting an Apps-API scope to a bot key (or vice-versa) has no effect: the scope only unlocks endpoints on its own surface.

## Apps API scopes (project keys)

| Scope | Grants | Endpoints |
|---|---|---|
| `groups:create` | Create rooms | `POST /apps/groups` |
| `groups:manage` | Read / update / delete your rooms | `GET /apps/groups`, `GET /apps/groups/:id`, `PATCH /apps/groups/:id`, `DELETE /apps/groups/:id` |
| `members:invite` | Invite members | `POST /apps/groups/:id/members` |
| `members:moderate` | Kick / ban / mute / set roles in rooms the project owns | `.../members/:wallet`, `.../ban`, `.../unban`, `.../mute`, `.../unmute`, `.../role` |
| `messages:send` | Send messages as the app bot | `POST /apps/groups/:id/messages` |
| `messages:read` | Read messages | `GET /apps/groups/:id/messages` |
| `messages:delete` | Delete messages | `DELETE /apps/groups/:id/messages/:messageId` |

## Bot API scopes (bot keys)

| Scope | Grants | Endpoints |
|---|---|---|
| `bots:dm:send` | Send DMs as the bot | `POST /bots/sendDirectMessage` |
| `bots:dm:read` | Read DM history | `GET /bots/getDirectChat` |
| `bots:groups:send` | Post messages into groups | `POST /bots/sendGroupMessage` |
| `bots:groups:moderate` | Ban / kick / mute / delete messages **as the bot**, in rooms where the bot holds a role | `POST /bots/banGroupMember`, `.../unbanGroupMember`, `.../kickGroupMember`, `.../muteGroupMember`, `.../unmuteGroupMember`, `.../deleteGroupMessage` |
| `bots:interactive` | Inline buttons & keyboards | `POST /bots/sendInteractiveMessage` |
| `bots:updates:poll` | Long-poll updates (Telegram-style) | `GET /bots/getUpdates` |
| `bots:webhook:manage` | Configure a webhook for updates | `POST /bots/setWebhook`, `.../deleteWebhook` |
| `bots:callback:answer` | Respond to inline button presses | `POST /bots/answerCallbackQuery` |
| `messages:edit` | Edit previously sent messages | `POST /bots/editMessageText`, `.../editMessageReplyMarkup` |

> **Note:** `bots:groups:moderate` lets the bot **call** the moderation endpoints. Whether a given action succeeds still depends on the bot's **role in the room** - see [Members &amp; moderation](https://portal.cherry.fun/docs/api/members.md). Signing scopes (`bots:sign:request`, `bots:tx:request`) require admin review before they take effect.

## Granting scopes to a key

Every scope above except the review-gated signing scopes is **self-serve**: you grant it yourself, no approval needed.

- **In the portal:** open the key's scope picker (project keys under your project's **API keys** section, bot keys under the bot's **Keys** section), tick the scopes, and save.
- **Programmatically** (from an authenticated portal session), `PATCH` the key with the full scope set you want it to have (this replaces, not appends):

  ```http
  PATCH /api/v1/projects/:projectId/api-keys/:keyId          # a project key
  PATCH /api/v1/projects/:projectId/bots/:botId/keys/:keyId  # a bot key
  Content-Type: application/json
  ```

  ```json
  { "scopes": ["messages:read", "messages:send", "members:moderate"] }
  ```

> **Tip:** Grant only the scopes a key needs. A read-only feed needs just `messages:read`; a moderation bot needs `bots:groups:moderate` (plus its role in the room).

## Next steps

- [Members & moderation](https://portal.cherry.fun/docs/api/members.md) · [Rate limits & errors](https://portal.cherry.fun/docs/api/rate-limits.md) · [Endpoint reference](https://portal.cherry.fun/docs/api/reference.md)

---

<!-- https://portal.cherry.fun/docs/api/rate-limits -->

# Rate limits & errors

## Rate limits

The Cherry API is rate-limited **per app**: every request authenticated with the same [app credentials](https://portal.cherry.fun/docs/api/authentication.md) shares one budget, regardless of source IP or how many keys you hold.

| Window | Default limit |
|---|---|
| Per minute | 600 requests |
| Per day | 50,000 requests |

The windows are **rolling**: at most 600 requests in any trailing 60 seconds, and 50,000 in any trailing 24 hours: there's no fixed calendar reset. Every request counts as one, reads and writes alike.

When you exceed a limit you get `429 Too Many Requests` with a `Retry-After` header (seconds) and a body telling you which window was hit:

```json
{ "error": "RATE_LIMITED", "reason": "PER_MINUTE_LIMIT_EXCEEDED", "retryAfterSec": 60 }
```

Back off and retry after `Retry-After`. Need higher limits? Contact the Cherry team.

## Errors

All errors return a JSON body with an `error` code and a human-readable `message`.

| Status | Code | Cause |
|---|---|---|
| `400` |  | Invalid request body (validation). |
| `401` |  | Missing / malformed / invalid `Authorization`, or the app isn't active. |
| `403` | `INSUFFICIENT_SCOPE` | Your app lacks the required [scope](https://portal.cherry.fun/docs/api/scopes.md). |
| `403` | `ROOM_NOT_MANAGED_BY_APP` | The room belongs to a different app. |
| `403` | `CANNOT_MODERATE_OWNER` | You tried to moderate the room owner. |
| `403` | `CANNOT_DELETE_ASSIGNED_ROOM` | You tried to delete a room your app didn't create. |
| `404` |  | Room / message / member not found. |
| `429` | `RATE_LIMITED` | Rate limit exceeded (see above). |

## Next steps

- [Endpoint reference](https://portal.cherry.fun/docs/api/reference.md)

---

<!-- https://portal.cherry.fun/docs/api/reference -->

# Endpoint reference

> **Tip:** Prefer a machine-readable spec? The full [OpenAPI 3.1 document](https://portal.cherry.fun/openapi.json) covers every endpoint on this page, including the dual `cherry_sk_` / `cherry_bot_` bearer schemes and the required scope per operation. Import it into Postman, generate a client, or hand it to an agent.

Every Cherry API endpoint at a glance. Two surfaces, each with its own key and base URL - see [Authentication](https://portal.cherry.fun/docs/api/authentication.md):

- **Apps API:** base `https://api.cherry.fun/api/v1/apps`, project key `Bearer cherry_sk_<projectId>_<secret>`.
- **Bot API:** base `https://api.cherry.fun/api/v1/bots`, bot key `Bearer cherry_bot_<botId>_<secret>`.

## Apps API: App

| Method | Path | Scope | Description |
|---|---|---|---|
| `GET` | `/apps/me` |  | Your project key's context: scopes, bot wallet, rate limits. |

## Apps API: Groups (rooms)

| Method | Path | Scope | Description |
|---|---|---|---|
| `POST` | `/apps/groups` | `groups:create` | [Create a room](https://portal.cherry.fun/docs/api/rooms.md). Returns `{ roomId }`. |
| `GET` | `/apps/groups` | `groups:manage` | List your project's rooms (cursor-paginated). |
| `GET` | `/apps/groups/:roomId` | `groups:manage` | Get one room. |
| `PATCH` | `/apps/groups/:roomId` | `groups:manage` | Update title / description / avatar / settings. |
| `DELETE` | `/apps/groups/:roomId` | `groups:manage` | Delete a project-created room. |

## Apps API: Members

| Method | Path | Scope | Description |
|---|---|---|---|
| `POST` | `/apps/groups/:roomId/members` | `members:invite` | [Bulk-invite wallets](https://portal.cherry.fun/docs/api/members.md) (`autoAccept` optional). |
| `DELETE` | `/apps/groups/:roomId/members/:wallet` | `members:moderate` | Kick a member. |
| `POST` | `/apps/groups/:roomId/members/:wallet/ban` | `members:moderate` | Ban (`deleteMessages` optional). |
| `POST` | `/apps/groups/:roomId/members/:wallet/unban` | `members:moderate` | Unban. |
| `POST` | `/apps/groups/:roomId/members/:wallet/mute` | `members:moderate` | Mute (`untilTs` optional). |
| `POST` | `/apps/groups/:roomId/members/:wallet/unmute` | `members:moderate` | Unmute. |
| `POST` | `/apps/groups/:roomId/members/:wallet/role` | `members:moderate` | Set role (`admin`/`moderator`/`member`). |

## Apps API: Messages

| Method | Path | Scope | Description |
|---|---|---|---|
| `POST` | `/apps/groups/:roomId/messages` | `messages:send` | [Send a message](https://portal.cherry.fun/docs/api/messages.md) as the app bot. |
| `GET` | `/apps/groups/:roomId/messages` | `messages:read` | List messages (newest first). |
| `DELETE` | `/apps/groups/:roomId/messages/:messageId` | `messages:delete` | Delete a message. |

## Bot API

Bot endpoints take a JSON body (no path params) and act as the bot's wallet.

| Method | Path | Scope | Description |
|---|---|---|---|
| `GET` | `/bots/me` |  | The bot's identity, wallet, and scopes. |
| `POST` | `/bots/sendDirectMessage` | `bots:dm:send` | DM a user as the bot. |
| `GET` | `/bots/getDirectChat` | `bots:dm:read` | DM history with one user. |
| `POST` | `/bots/sendGroupMessage` | `bots:groups:send` | Post a message into a group. |
| `POST` | `/bots/sendInteractiveMessage` | `bots:interactive` | Send a message with inline buttons / keyboard. |
| `POST` | `/bots/answerCallbackQuery` | `bots:callback:answer` | Respond to an inline button press. |
| `POST` | `/bots/banGroupMember` | `bots:groups:moderate` | [Ban](https://portal.cherry.fun/docs/api/members.md) (`{ roomId, wallet, deleteMessages? }`). |
| `POST` | `/bots/unbanGroupMember` | `bots:groups:moderate` | Unban (`{ roomId, wallet }`). |
| `POST` | `/bots/kickGroupMember` | `bots:groups:moderate` | Kick (`{ roomId, wallet }`). |
| `POST` | `/bots/muteGroupMember` | `bots:groups:moderate` | Mute (`{ roomId, wallet }`). |
| `POST` | `/bots/unmuteGroupMember` | `bots:groups:moderate` | Unmute (`{ roomId, wallet }`). |
| `POST` | `/bots/deleteGroupMessage` | `bots:groups:moderate` | Delete a message (`{ roomId, messageId }`). |
| `POST` | `/bots/editMessageText` | `messages:edit` | Edit a message the bot sent. |
| `POST` | `/bots/editMessageReplyMarkup` | `messages:edit` | Replace the inline keyboard on a message the bot sent. |
| `GET` | `/bots/getUpdates` | `bots:updates:poll` | Long-poll for updates (Telegram-style). |
| `POST` | `/bots/setWebhook` | `bots:webhook:manage` | Configure a webhook for updates. |
| `POST` | `/bots/deleteWebhook` | `bots:webhook:manage` | Remove the configured webhook. |

> **Note:** Bot moderation is gated by **two** layers: the `bots:groups:moderate` scope <em>and</em> the bot's in-room role (owner/admin/moderator). See [Members &amp; moderation](https://portal.cherry.fun/docs/api/members.md).

See [Scopes](https://portal.cherry.fun/docs/api/scopes.md) and [Rate limits & errors](https://portal.cherry.fun/docs/api/rate-limits.md) for the cross-cutting rules.