# 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)