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