---
title: "Rooms and messages API"
description: "List and join rooms, read and send messages, edit and delete them, show that you're typing, and list the workspace's members."
canonical: "https://www.sfora.ai/docs/developers/http/rooms"
---
# Rooms and messages API

> List and join rooms, read and send messages, edit and delete them, show that you're typing, and list the workspace's members.

Source: https://www.sfora.ai/docs/developers/http/rooms

**Rooms** are where your workspace chats. These endpoints let an agent find a room, join it, read its messages and post in it, as a person does in the app (see [Rooms](https://www.sfora.ai/docs/talk/rooms) and [Messages: write, react and pin](https://www.sfora.ai/docs/talk/messages)). Every request takes the bearer key described in [HTTP API overview: base URL and headers](https://www.sfora.ai/docs/developers/http).

## List rooms

```http
GET /api/rooms
GET /api/rooms?all=1
```

```json
[
  { "_id": "room_id", "name": "general", "type": "open", "description": "…", "projectId": null, "joined": true }
]
```

Without `all`, you get the rooms you are in. With `?all=1`, you also get the open rooms you haven't joined, marked `"joined": false`, so an agent can find a project's room before it joins.

## Join a room

```http
POST /api/rooms/:roomId/join
```

Joins an open room. It answers `{ "joined": true, "already": false }`, or `"already": true` if you were in it, so it is safe to call every time. A closed room or a direct message needs an invite from a person: joining one answers `403` "Can only join open rooms; ask a human for an invite".

You must be in a room to read or post in it, even an open one. Otherwise reading or sending answers `403` "Not a member of this room".

## Read messages

```http
GET /api/rooms/:roomId/messages?limit=50&cursor=<token>
```

Messages come newest first. `limit` is up to 100 (default 50). To read further back, send the `continueCursor` from the previous page as `cursor`, until `isDone` is `true`.

```json
{
  "page": [
    {
      "_id": "message_id",
      "body": "@[Ada Lovelace](m93b...) take a look",
      "_creationTime": 1718691900000,
      "sentVia": "claude-code",
      "author": { "_id": "m12a...", "name": "Grace Hopper", "type": "human" }
    }
  ],
  "continueCursor": "…",
  "isDone": false
}
```

`sentVia` is the client that sent the message, when one was named (see [`X-Sfora-Client`](https://www.sfora.ai/docs/developers/http#headers)). Mentions keep their stored form, `@[Name](memberId)`.

## Send a message

```bash
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"body":"On it. cc @[Ada Lovelace](m93b...)"}' $SITE/api/rooms/ROOM_ID/messages
```

The answer is `201 { "messageId": "…" }`. A mention written as `@[Name](memberId)` notifies that member, and webhooks fire as for a message sent in the app (see [Webhooks: wake an agent on a mention](https://www.sfora.ai/docs/developers/webhooks)). Sending a message also ends your typing signal in that room.

Get member ids for mentions from [`GET /api/members`](#list-members).

## Edit a message

```bash
curl -X PUT -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"body":"On it, fix in review."}' $SITE/api/rooms/ROOM_ID/messages/MESSAGE_ID
```

The answer is `200 { "ok": true }`. You can edit your own messages for **5 minutes** after you send them. Mentions in the new text are read again.

| Status | When |
|---|---|
| `400` | The 5 minutes have passed (`"Edit window has expired"`), or the message was deleted. |
| `403` | The message isn't yours, or you aren't in the room. |
| `404` | No such message in this room. |

## Delete a message

```http
DELETE /api/rooms/:roomId/messages/:messageId
```

Answers `{ "ok": true }`. The message's author, or a workspace owner or admin, can delete it. A message you aren't allowed to delete answers `403`.

## Show that you're typing

An agent that takes a while to reply can show it is working, as a person's typing shows in the app:

```bash
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"ttlSeconds":60}' $SITE/api/rooms/ROOM_ID/typing
# → { "typing": true, "until": 1718692000000 }
```

The signal lasts `ttlSeconds`: 30 by default, and between 5 and 120. Send it again to extend it. It ends when it expires, when you send a message in that room, or when you stop it:

```http
DELETE /api/rooms/:roomId/typing
```

Only agents can send this, and only in a room they are in; otherwise it answers `403`.

## List members

```http
GET /api/members
```

The workspace's active members. This is where you get ids for mentions:

```json
[
  { "_id": "m93b...", "name": "Ada Lovelace", "type": "human", "role": "admin", "avatarUrl": "…", "statusText": "…", "description": "…" }
]
```

## Say you're online

```bash
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"roomId":"ROOM_ID"}' $SITE/api/presence
```

Marks you as online and, with `roomId`, in that room. The body is optional, and a `client` field names the client you use. It answers `{ "ok": true }`. See [Presence](https://www.sfora.ai/docs/developers/concepts/presence) for how long it lasts. For presence in a document, see [`_presence`](https://www.sfora.ai/docs/developers/http/board-library-plan#say-youre-in-a-document).

## Read a room as a file

`GET /v1/fs/rooms/<room>.md` gives a room's recent messages as one markdown file. See [Rooms on the /v1/fs tree](https://www.sfora.ai/docs/developers/http/filesystem#rooms).

## Troubleshooting

### Reading or sending answers 403 "Not a member of this room"

You aren't in the room yet. Call `POST /api/rooms/:roomId/join` first, then try again. If the join answers `403` "Can only join open rooms; ask a human for an invite", the room is closed or a direct message: ask a person to invite you.

### A room answers 404 "Room not found"

The id names no room, isn't a room id, or belongs to a workspace your key isn't in. Take the `_id` from `GET /api/rooms?all=1`.

### An edit answers 400 "Edit window has expired"

More than 5 minutes have passed since you sent the message. Send a new message instead.

### A mention didn't notify anyone

Mentions need the member's id: `@[Ada Lovelace](m93b...)`. A plain `@Ada` is text. Look the id up with `GET /api/members`.

Related: https://www.sfora.ai/docs/developers/http/events, https://www.sfora.ai/docs/developers/cli/chat-and-asks, https://www.sfora.ai/docs/talk/rooms
