# Chapter 15: Read receipts

> Ana sends Ben “What time do we leave on Saturday?”. Has he read it? She posts the meeting point in the hiking group. Of the 500 members, who has read it?

IM Systems in Depth · https://im.liko.page/en/read-receipts/

Ana sends Ben “What time do we leave on Saturday?”. Half an hour later there is no reply, and she wants to know: has he not seen it, or has he seen it and not answered?

She also posts the meeting point in the hiking group. Of the 500 members, how many have read it?

This is a **read receipt**: the sender sees whether others have read her message. [Chapter 14](/en/unread/) kept track of how far Ana herself has read; this chapter turns it round and tells her how far others have read. What has to be decided: **where receipts come from, and whether they are pushed to the sender or wait for her to fetch them.**

## 1. First, what does the product need?

| Product | What the sender sees |
|---|---|
| Social app, one-to-one | “Read” under my message; can be turned off in privacy settings |
| Social app, group | Nothing; or “read by N”, and tapping it shows who |
| Workplace chat | Who has and has not read each message, kept, with a way to nudge them (chapter 39) |
| Customer service | The agent sees whether the customer has read it (chapter 43) |
| Voice messages | “Played” for that one message, nothing to do with the read position |

A one-to-one chat is simple: there is one reader. A group is harder: many readers, and few people who care to look. The trunk is a social app with groups of up to 500. It chooses: “Read” in one-to-one chats; in a group, opening a message shows “read by N” and the list of names.

## 2. Work it out from the read position

The first idea is one receipt per message: each time Ben’s phone shows a message it reports “read this one”, and the server passes it on to the sender. [OpenIM’s group read receipts](https://docs.openim.io/sdk/ios/message/managing-read-status/send-group-read-receipts) work this way: the phone reports a list of message IDs, the server records who read which, and passes it on to the rest of the group.

In the hiking group, 1,000 messages a day, all read by 500 people, means recording and passing on **500,000** “who read which” entries.

Chapter 14 already keeps one **read position** per person per conversation (read_seq, the read cursor). It says “I have read everything up to this seq” (the seq is each message’s number within the conversation). One position covers every message before it: the open protocol XMPP’s [displayed markers](https://xmpp.org/extensions/xep-0333.html) carry “a semantic of all messages up to this point”, and Matrix’s [`m.read`](https://spec.matrix.org/latest/client-server-api/#receipts) is for “indicating that the user has read up to a given event”.

So receipts need nothing kept of their own; they come from the read position:

- **Has someone read a message?** Their read position ≥ the message’s seq.
- **How many have read it?** The number of people whose read position ≥ the message’s seq.

Say five people’s read positions are [9, 7, 7, 3, 12]: message 7 has been read by 4 of them. All the hiking group has to store is 500 numbers.

What is left is getting them to the sender. One-to-one chats and groups answer that differently.

## 3. One-to-one: push, and reliably

In Ana and Ben’s chat, “What time do we leave on Saturday?” is message 58. Ben reads it, and chapter 14’s read transaction moves his read position to 58. This chapter adds a to-do row in the same transaction (chapter 11’s way: write it down first, a background job does it later), and the to-do updates **Ana’s** conversation record (one row per person per conversation):

```sql
UPDATE conversation_records
   SET peer_read_seq = GREATEST(peer_read_seq, 58), version = <Ana’s next record version>
 WHERE user_id = :ana AND conversation_id = :ben_chat;
```

- **It travels with conversation sync.** It bumps Ana’s record version, so each of her devices gets it at its next sync; online devices also get a push. A lost push does no harm: sync fills it in.
- **It only moves up.** A late or repeated to-do changes nothing, just like chapter 14’s read position.
- **Why a to-do, and not the same read transaction?** Taking a record version (chapter 11) locks that person’s row in the users table. Ben’s read transaction bumps his own record version, so it locks Ben’s row first and then wants Ana’s; if Ana is reading Ben’s messages at the same moment, her read transaction has locked Ana’s row and wants Ben’s. Each waits for the other to let go, and neither ever does: a deadlock. Locking in user-ID order avoids it, but then every read locks two people. A to-do locks one person at a time, and the reader does not wait.

Once Ana’s phone has `peer_read_seq = 58`, every message she sent with a seq up to that shows “Read”.

Telegram’s one-to-one chats also push a position: [`updateReadHistoryOutbox`](https://core.telegram.org/constructor/updateReadHistoryOutbox) carries the “Maximum ID of read outgoing messages”, along with a `pts`. The `pts` is Telegram’s per-account update number: a new message, a deleted message, the other side reading, all move it up. The phone remembers where it is, and when it sees a gap it fetches what is missing, the same idea as chapter 11’s record version. Because the update carries a `pts`, a lost “read” can be recovered.

## 4. Groups: don’t push, count when opened

Could a group work like a one-to-one chat: push every member’s read position to every other member, so each phone shows “read by N” live?

Do the sums for the hiking group: 500 people, each looking at the group 20 times a day, is 10,000 changes of read position. Each pushed to the other 499 is about **5,000,000 pushes a day**, 10 times the group’s message pushes (500,000 a day).

Yet the only person who wants to know is the sender, and she looks only now and then. So groups push nothing, and **count when she opens that message** (call that message’s seq s):

- **How many have read it:** an index on (conversation, read position) over the conversation records lets the server count a range: how many rows in this group have a read position ≥ s, leaving Ana out. At most 500 rows.
- **Who:** the same range, returning the user IDs.
- **Only those in the group when the message was sent.** Someone who joined later has a read position that starts at their join (chapter 14), above s, yet they never saw s. Chapter 12 gives each person a membership range (min_seq to max_seq) for each stretch they were in the group; filter on whose range s falls in.

Telegram fetches too: [`messages.getMessageReadParticipants`](https://core.telegram.org/method/messages.getMessageReadParticipants) returns who has read a message. It exists only in groups with no more than `chat_read_mark_size_threshold` members (100 by default), and receipts are kept only for `chat_read_mark_expire_period` (7 days by default), “to protect user privacy”, the documentation says ([client configuration](https://core.telegram.org/api/config)).

The trunk’s groups have at most 500 members, and read positions are stored for unread counts anyway, so counting them costs no extra storage. Any limit on group size or time here is a privacy choice, not a cost one.

### A tick under group messages?

Some products show a status under group messages too. Both of these come from the read positions, leaving Ana out:

- **Someone has read it:** the highest of the others’ read positions ≥ s. For the five above, the highest is 12, so everything up to 12 is “someone has read it”.
- **Everyone has read it:** the lowest among those in the group ≥ s. The lowest is 3, so only messages up to 3 are “everyone has read it”.

Telegram’s supergroups push an [`updateReadChannelOutbox`](https://core.telegram.org/constructor/updateReadChannelOutbox): “Position up to which all outgoing messages are read”. It carries no `pts`, so it is not in the sequence that can be recovered; the chat list has a separate `read_outbox_max_id` ([dialog](https://core.telegram.org/constructor/dialog)), which arrives the next time the chat list is fetched.

The trunk suggests no tick under group messages, only “read by N” when one is opened. If you do want one, work it out once from the two rules above when the chat is opened, and push nothing.

## 5. What one position cannot say

- **When it was read.** A read position is a place, not a time. To show “Read at 10:42”, you have to keep a time per person per message. Telegram returns a time with each reader ([`readParticipantDate`](https://core.telegram.org/constructor/readParticipantDate)).
- **Messages read by jumping.** In chapter 14, Ana taps @ and jumps straight to 4,900 while her read position stays at 4,800. She did see message 4,900, yet the person who @mentioned her sees no “Read”: that part is wrong. The 99 messages she skipped are not claimed as read either: that part is right.
- **Whether a voice message was played.** That is a per-message state, nothing to do with the read position. Telegram tells the sender “listened” with a separate [`messages.readMessageContents`](https://core.telegram.org/method/messages.readMessageContents).

## 6. Turning read receipts off

Ben turns off read receipts in his privacy settings. His read position still has to be stored: chapter 14’s unread count needs it. Turning receipts off means:

- his read position is not copied onto Ana’s record;
- when Ana asks “who has read it”, he is not counted.

The open protocol Matrix has this ready-made: [`m.read.private`](https://spec.matrix.org/latest/client-server-api/#receipts) keeps the read position but does not send it to anyone.

The trunk suggests making it mutual: whoever turns receipts off doesn’t see others’ either. Telegram’s read times work this way: if you hide your read time from others, you can’t look up when others read yours (`YOUR_PRIVACY_RESTRICTED` from [`messages.getOutboxReadDate`](https://core.telegram.org/method/messages.getOutboxReadDate)).

## 7. The numbers

- **Storage:** one receipt per message in the hiking group is 500,000 a day; with positions, the whole group is 500 numbers, about 6 KB.
- **One-to-one:** each change of read position adds a to-do, which changes two of Ana’s rows (the users row for the version number, and the conversation record). The read position moves at most once per message received (chapter 14), so even if every read were in a one-to-one chat, the v2 peak (139 messages a second, each reaching 6.67 people on average) is only 927 a second, changing 1,853 rows, about 9.3% of what one storage node can write; counting the to-do row itself (written once, deleted once), it is 3,707 rows, 18.5%.
- **Groups:** one open reads an index range of at most 500 entries, about 6 KB.

## 8. The cost

- **One more write per read in one-to-one chats.** Each change of read position updates the other person’s record, and their devices sync once more.
- **One more index for groups.** The (conversation, read position) index on conversation records changes with every read.
- **Group receipts are not live.** The count is taken when the message is opened; to watch it go up, you open it again.
- **No times, and nothing about messages read by jumping.** What workplace chat wants (who hasn’t read it, and when each person did) needs per-message state (chapter 39).

## 9. Other answers

- **One receipt per message.** OpenIM’s group receipts, and workplace apps that want “who read it and when”. Exact; the cost is one receipt for every message times every reader.
- **Push every read to the whole group.** “Read by N” goes up live. Fine for a group of a dozen or so; about 5,000,000 pushes a day for a group of 500.
- **Telegram.** One-to-one chats push the position with a `pts`, reliably; supergroups push the position with no `pts`; “who has read it” is fetched when opened, only in groups of up to 100 and within 7 days.
- **No read receipts in groups.** Many social apps do this for big groups, and store nothing.

## 10. This chapter’s decision

**Decision card**

- Problem: The sender wants to know whether others have read her message. One receipt per message is 500,000 a day for the hiking group; pushing every read to the whole group is about 5,000,000 pushes a day.
- Choice: Receipts come from chapter 14’s read position, with nothing kept of their own. One-to-one: when the other person’s read position changes, a to-do writes it into the sender’s conversation record (only moving up, bumping the record version), and conversation sync delivers it reliably. Groups: nothing pushed; when the sender opens a message, the (conversation, read position) index gives how many have read it and who, counting only those in the group when it was sent.
- Cost: One more write per read in one-to-one chats; one more index in groups that changes with every read; group receipts are as of the moment of opening; no read times, nothing about messages read by jumping.
- Revisit when: Every device needs the other person’s read position (chapter 16); per-message read state (chapter 39); the agent seeing whether the customer has read it (chapter 43).
- Other answers: One receipt per message (OpenIM group receipts, workplace chat); push every read to the whole group (small groups); Telegram (reliable push in one-to-one chats, a push without pts in supergroups, who has read it fetched on open, 100 members, 7 days); no receipts in groups.

Read receipts reach each of Ana’s devices with the conversation records. But what does each device receive? How does a message she sent from her phone show up on her laptop? How far back does a new tablet pull on its first login? Next: many devices.
