---
title: Conversations
description: Chats and mail threads between people, with unread counts, archive and bin, requests from people you don't know yet, and mail to whoever is away.
section: Plugins
order: 31
---

# Conversations

Chats and mail threads between people, with unread counts, archive and bin, requests from people you don't know yet, and mail to whoever is away.

The `conversations` plugin is one thing under both a chat and an inbox: some people, their messages, and how far each of them has read. To add it:

```sh title="Terminal"
sluurp plugin add conversations
```

Features include:

- Chats (`channel`) and mail threads (`thread`), with any number of people
- An unread count per conversation, kept as how far each person has read
- Archive, bin and restore, each person for themselves
- Requests: a conversation someone else started stays apart until it is answered or accepted
- A short mail to people who were away when a message came, with a link back

## Who sees what

Being in a conversation is the permission: people read the conversations they are in, and to everybody else a conversation does not exist. There is nothing to set up in the admin.

For the mails to people who are away, set up mail under **Mail** in the admin. Without it, nobody is mailed.

## The inbox

Import the plugin once, in your app's code:

```ts title="app.ts"
import "plugin:conversations";

const { items, unread } = await sluurp.conversations.mine({ kind: "thread" });
```

`mine()` lists the person's conversations, newest first, each with its `unread` count, its `latest` message and its `members`. Pass `archived: true` or `binned: true` for those folders. A conversation someone else started and that was never answered nor accepted has `request: true`.

## Start, write and read

```ts title="app.ts"
const thread = await sluurp.conversations.start({ kind: "thread", subject: "Field trip", members: [parent.id] });
const conversation = sluurp.conversation(thread.id);

await conversation.say("The trip is on the 3rd.");
const messages = await conversation.messages({ limit: 50 });
await conversation.read();
```

`messages()` returns the latest messages; pass `before` to page back. `read()` marks everything as read. `read({ through, rewind: true })` moves the mark back, so a conversation can be marked unread.

Each person can also `archive()` a conversation, `bin()` it, `accept()` a request, `add()` or `remove()` people, and take back their own message with `unsay()` (and `restore()` it).

## Live

A conversation has a live room, its `topic`, which only its people may join:

```ts title="app.ts"
const socket = sluurp.socket();
socket.join(conversation.topic);

socket.on("message", ({ message }) => show(message)); // new, or changed: taken back or put back
socket.on("presence", ({ members }) => setHere(members)); // who has the conversation open
socket.on("emit", ({ event, from, data }) => {
  if (event === "read") setReadTo(from, data.through); // how far someone has read
});
```

Messages are sent through `say()` and arrive to everyone in the room, so a phone and a desktop see the same thing. What the people in a room send each other directly also comes as `emit`, and nothing of it is stored. A typing notice, for example:

```ts title="app.ts"
socket.emit(conversation.topic, "typing");
```
