---
audience: developer
summary: Send, edit, redact, react. The atomic actions in a room.
title: Messages and reactions API
path: reference/api/messages-and-reactions
status: published
---

# Messages and reactions API

6 endpoints. See
[Send a message via the API](/docs/scaiwave/tutorials/developer/send-a-message-via-api)
for the prose-driven version.

## Messages

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/rooms/{room_id}/messages` | List messages with pagination by `stream_position`. |
| `POST` | `/v1/rooms/{room_id}/send` | Create a new event. |
| `POST` | `/v1/rooms/{room_id}/events/{event_id}/edit` | Edit an existing event (sender only, default 24h window). |
| `POST` | `/v1/rooms/{room_id}/events/{event_id}/redact` | Redact (own, or `power_level ≥ 50`). |

### GET /v1/rooms/{room_id}/messages

Query params:

- `limit` (default 50, max 200).
- `from` — stream position to start from.
- `direction` — `back` (older) or `forward` (newer); default `back`.

Response:

```json
{
  "data": [
    {
      "id": "evt-…",
      "room_id": "room-…",
      "sender_id": "5e4d…",
      "event_type": "swp.room.message",
      "content": { "msgtype": "swp.text", "body": "Hello" },
      "stream_position": 12345,
      "origin_ts": 1778939467,
      "created_at": "2026-05-17T11:00:00Z",
      "edited_at": null,
      "redacted_at": null
    }
  ],
  "meta": { "has_more": true, "next_cursor": "12300" }
}
```

### POST /v1/rooms/{room_id}/send

Body fields:

- `content` (object, required).
- `event_uuid` (string, optional; for idempotency).
- `as_participant_id` (string, optional; bot-send-on-behalf, requires `power_level ≥ 100`).

See [Send a message via the API](/docs/scaiwave/tutorials/developer/send-a-message-via-api)
for content shapes.

### POST /v1/rooms/{room_id}/events/{event_id}/edit

```json
{ "content": { "msgtype": "swp.text", "body": "Corrected" } }
```

Edits expire 24h after creation by default. The original `content`
is preserved in `event.original_content`.

### POST /v1/rooms/{room_id}/events/{event_id}/redact

```json
{ "reason": "Posted in the wrong room" }
```

Body of the event is wiped; metadata + event id remain. Cannot be
undone.

## Reactions

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/v1/rooms/{room_id}/events/{event_id}/reaction` | Add a reaction. |
| `DELETE` | `/v1/rooms/{room_id}/events/{event_id}/reaction` | Remove your reaction. |

Body for POST:

```json
{ "emoji": "🚀" }
```

Each `(event, sender, emoji)` is a unique reaction — re-posting the
same emoji from the same sender is a no-op.

## Errors

- `SW_EVENT_NOT_FOUND` — event id doesn't exist.
- `SW_EVENT_TOO_OLD_TO_EDIT` — edit past the window.
- `SW_REDACT_FORBIDDEN` — not yours and you lack power level.
- `SW_RATE_LIMIT_EXCEEDED` — over the tenant's send rate.
- `SW_CONTENT_TOO_LARGE` — content exceeds 64 KB.