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