Apron Chat Protocol

Adds the command request, which sends an instruction to the server. It takes the same params as a new message (§3.5). Only its effect is different:

• body.text is the command line as the user typed it, slash included. The server parses it.
• If composer text starts with /, clients send it as a command. If it starts with //, clients send it as a message that starts with /.
• A command is never logged, broadcast, or saved. It has no message_id. A command with message_id or deleted is invalid_params.
• mentions, reply_to, embeds, and ext are arguments. Mentioned users are not notified, and ext is not kept.
• The result is {}, or {"embeds": [...]} with write URLs for new upload embeds (§4.8.3). A failure is an ordinary error, and the client shows its message.
• The server replies as needed with system notices (Appendix A.1). It sends ~private to the sender, ~room to the room, and ~server to everyone.
• Effects arrive as the frames they cause, such as room_update.
• Commands are for what a server provides beyond this spec, such as /ban with the server's own moderation rules.
• Which commands exist, their arguments, and who may use them are server policy.
• Suggested convention: commands list and remove the sign-in methods of an account (§3.2).
• Servers that support commands SHOULD provide /help. It replies with a ~private notice. The notice lists the commands that the sender can use, with their arguments and what they do.
• Clients MAY handle a command themselves when it matches a request, such as /nick as me or /join as room_join. They send the other commands as command.

// -> remove a user from the room; mentions refer to the target
{
  "method": "command", "id": "c30", "params": {
    "room_id": "general",
    "body": {"text": "/kick @guest_1234 spamming", "mentions": ["guest_1234"]}
  }
}
// <- to guest_1234's connections; the room's other members get the membership alone
{
  "method": "room_update", "params": {
    "left": [{"room_id": "general"}],
    "memberships": [
      {"log_id": "1724803900001", "room_id": "general", "members": [{"user": {"user_id": "guest_1234", "name": "Guest"}, "joined": false}]}
    ]
  }
}
// <- to the room's remaining members: the notice
{
  "method": "message", "params": {
    "message_id": "1724803900002", "log_id": "1724803900002", "room_id": "general",
    "from": {"user_id": "~room", "name": "General"},
    "body": {"text": "@guest_1234 was removed by @alice: spamming"}
  }
}
// <- then the result
{"id": "c30", "result": {}}

// -> answer an agent's permission prompt by replying to it
{
  "method": "command", "id": "c31", "params": {
    "room_id": "agent", "reply_to": {"message_id": "1724803900000"},
    "body": {"text": "/approve"}
  }
}
// <- or, from a user without the right
{"id": "c31", "error": {"code": -32001, "message": "Only the session owner can approve"}}

// -> list the available commands
{"method": "command", "id": "c32", "params": {"room_id": "general", "body": {"text": "/help"}}}
// <- to the sender only
{
  "method": "message", "params": {
    "room_id": "general",
    "from": {"user_id": "~private", "name": "Only you"},
    "body": {
      "text": "- `/kick @user [reason]`: remove someone from this room\n- `/avatar` with an image: set your avatar",
      "format": "markdown"
    }
  }
}
// <-
{"id": "c32", "result": {}}

// -> set an avatar from an upload (§4.8.6)
{
  "method": "command", "id": "c33", "params": {
    "body": {"text": "/avatar", "embeds": [{"kind": "upload", "title": "me.png"}]}
  }
}
// <-
{
  "id": "c33", "result": {
    "embeds": [{"embed_id": "embed_1300", "kind": "upload", "write_url": "https://chat.example/w/9c1e…"}]
  }
}

Lets users find, join, and create rooms and threads. It adds the requests room_list, room_join, room_leave, and room_set, and the notification room_update. Visibility and membership are server policy.

A room record describes one room, as room_list, room_update, and history carry it:

{
  "room_id": "general", "log_id": "1724800000000", "title": "General",
  "description": "Ops chatter: deploys, alerts, *incidents*.",
  "latest_log_id": "1724803200042", "history_log_id": "1724800000000"
}

In the "set by" column, server fields are read-only (§2.3), and room_set replaces client fields (§4.2.4). delivery fields describe the room as this client sees it. They are not logged. Clients always use the latest value, even if log_id did not change. A frame that omits a delivery field does not change it.

A room record is complete (§2.3). A server or client field that it omits is cleared.

description is the summary of the room, such as its purpose or the state of its conversation. Users who can edit the room can change it with room_set. It is CommonMark (§3.5.2).

A thread is a room with a parent_room_id. A client that ignores this field shows threads as ordinary rooms. A client that uses it groups threads under their parent, and MAY collapse or hide them. Servers set title on threads.

4.2.1 Listing#

room_list returns the rooms that match its filters, as room records (above). The result has up to two arrays. joined holds the rooms that the user joined. not_joined holds the visible rooms that the user did not join. Listing never joins a room.

// -> my rooms, threads included, with their members
{"method": "room_list", "id": "c20", "params": {"filter": "joined", "members": true}}
// <-
{
  "id": "c20", "result": {
    "joined": [
      {
        "room_id": "general", "log_id": "1724800000000", "title": "General",
        "latest_log_id": "1724803500000", "history_log_id": "1724800000000",
        "members": [{"user_id": "alice"}, {"user_id": "bob"}, {"user_id": "carol"}]
      },
      {
        "room_id": "1724803312001", "log_id": "1724803312001",
        "parent_room_id": "general", "title": "Deploy", "description": "Why the 4pm deploy failed",
        "latest_log_id": "1724803400000", "history_log_id": "1724803312001",
        "members": [{"user_id": "alice"}, {"user_id": "bob"}]
      }
    ],
    "users": [
      {"user_id": "alice", "name": "Alice", "avatar": "https://..."},
      {"user_id": "bob", "name": "Bob"},
      {"user_id": "carol", "name": "Carol"}
    ]
  }
}
// -> reconnecting: my rooms that changed since a position, and those I left
{"method": "room_list", "id": "c21", "params": {"filter": "joined", "latest_log_id": "1724803450000"}}
// <-
{
  "id": "c21", "result": {
    "joined": [{"room_id": "general", "latest_log_id": "1724803500000", ...}],
    "left": [{"room_id": "1724803399000"}]
  }
}
// -> general's threads I have not joined
{"method": "room_list", "id": "c22", "params": {"parent_room_id": "general", "filter": "not_joined"}}
// -> one room, with its members
{"method": "room_list", "id": "c23", "params": {"room_id": "1724803312001", "members": true}}

Every filter is optional:

• filter: "joined" lists only joined, "not_joined" only not_joined, and "all", the default, both. An array the filter asks for is present even when empty, and the other is omitted.
• parent_room_id lists only the threads of that room. Without it, joined holds joined rooms at all depths, threads included, and not_joined holds only top-level rooms.
• room_id lists only that room, in the array that matches its membership. It overrides parent_room_id. Servers SHOULD support this filter.
• members: true adds each room's members and the result's users (below); without it, a result carries neither.
• user_id, with members: true, lists only that user in members and users. A server MAY ignore this filter.
• latest_log_id lists only the rooms whose latest_log_id is greater. A server MAY ignore this filter. Its result is then a full listing without left.
  • A server that applies this filter includes left, also when it is empty.
  • When the result has joined, left lists the rooms that the user left since then, as [{room_id}] like room_update (§4.2.3).
  • Rooms that were deleted or became invisible since then SHOULD also be in left.

A result lists the matching rooms, with the most recently active first. joined lists every match. For not_joined, servers MAY list only the most recently active rooms. Servers list a private room only to its members (§4.2.4).

With members: true, each room in joined and not_joined carries members. This lists every user who joined the room, as current user objects (§3.3) that MAY carry only user_id. The result SHOULD carry users, the complete current objects of the users in members, each one time.

In a large room, a server MAY truncate members, for example to the most recently active users. It then SHOULD include member_count, the number of users who joined.

4.2.2 Membership#

room_join and room_leave take a room_id. They return {}.

A server MAY also accept a user_id, to add or remove another user. A server that does not support user_id replies unsupported. The change is an ordinary join or leave by that user.

// -> Alice adds Bob to her private room
{"method": "room_join", "id": "c3", "params": {"room_id": "1724803950000", "user_id": "bob"}}

A join subscribes every connection of the user to the deliveries of the room (§3.4). Users join a thread like any room.

Every membership change is a logged record in the room. This includes the creation of a room with room_set, and changes that the server makes. A membership record carries members, with one entry for each user. Each entry has the user as a recorded object (§3.3.1), and joined. room_update delivers membership records in memberships (§4.2.3):

// ->
{"method": "room_join", "id": "c24", "params": {"room_id": "1724803399000"}}
// <- to the room's other members
{
  "method": "room_update", "params": {
    "memberships": [
      {"log_id": "1724803450100", "room_id": "1724803399000", "members": [{"user": {"user_id": "ada", "name": "Ada"}, "joined": true}]}
    ]
  }
}
// <- to the joining user's connections: the room with its members, and the membership
{
  "method": "room_update", "params": {
    "joined": [{"room_id": "1724803399000", ..., "members": [{"user_id": "ada"}, {"user_id": "bob"}]}],
    "memberships": [
      {"log_id": "1724803450100", "room_id": "1724803399000", "members": [{"user": {"user_id": "ada", "name": "Ada"}, "joined": true}]}
    ],
    "users": [{"user_id": "ada", "name": "Ada"}, {"user_id": "bob", "name": "Bob"}]
  }
}
// <-
{"id": "c24", "result": {}}

// ->
{"method": "room_leave", "id": "c25", "params": {"room_id": "1724803312001"}}
// <- to the leaving user's connections; the room's other members get the membership alone
{
  "method": "room_update", "params": {
    "left": [{"room_id": "1724803312001"}],
    "memberships": [
      {"log_id": "1724803450200", "room_id": "1724803312001", "members": [{"user": {"user_id": "ada", "name": "Ada"}, "joined": false}]}
    ]
  }
}
{"id": "c25", "result": {}}

• The key of a membership is (room_id, user.user_id). The record with the greatest log_id wins (§2.3). Live records carry one entry. Compacted history records MAY carry more (§4.3.4), and each entry replaces the membership of that user.
• The server delivers a membership record to everyone who is a member of the room before or after the change. The record advances the latest_log_id of the room.
• Clients start the member list of a room from its members in room_list or in room_update joined. They update it from the memberships that they receive, live and in history.
• A server MAY keep some memberships outside the log, such as for temporary guests. It then sends no membership records for them, and ignores latest_log_id in room_list (§4.2.1).
• Joins and leaves are membership records, not user notifications (§3.3).
• Posting in a room does not require a join (§3.5.1). The server MAY join the poster. A poster who did not join does not receive the broadcast.

4.2.3 Updates#

room_update tells the connections of the user what changed. It never carries the full list:

• joined: the room records of rooms that the user joined after signing in, by any means. Each has its members, as in room_list (§4.2.1). users MAY come with them.
• left: [{room_id}] for each room that the user is no longer in, for any reason.
• memberships: membership records (§4.2.2), to the members of the room.
• updated: room records that are new or changed, when the membership of the user did not change. These are edits to a joined room, and new or edited threads of a joined room.
  • The changes to the record of a thread go to the members of the parent, also if they did not join the thread. This does not apply to a private thread.
  • Messages in a thread do not cause updated. So the latest_log_id of a thread in updated is from its last record change.

// <- after the join above
{"method": "room_update", "params": {"joined": [{"room_id": "1724803399000", "parent_room_id": "general", "title": "Incident", ...}]}}
// <- after the leave above
{"method": "room_update", "params": {"left": [{"room_id": "1724803312001"}]}}
// <- a joined room was renamed
{"method": "room_update", "params": {"updated": [{"room_id": "general", "log_id": "1724803600000", "title": "General (ops)", ...}]}}

4.2.4 Creating and editing#

room_set without room_id creates a room, and joins the creator to it. room_set with room_id replaces the client fields of that room (§4.2). Both forms return {"room_id": "..."}.

// -> start a thread in general
{
  "method": "room_set", "id": "c26", "params": {
    "parent_room_id": "general", "title": "Deploy",
    "description": "Why the 4pm deploy failed"
  }
}
// <- to the creator: the room with its members, and the creator's membership
{
  "method": "room_update", "params": {
    "joined": [
      {
        "room_id": "1724803312001", "log_id": "1724803312001",
        "parent_room_id": "general", "title": "Deploy",
        "description": "Why the 4pm deploy failed",
        "latest_log_id": "1724803312002", "history_log_id": "1724803312001",
        "members": [{"user_id": "ada"}]
      }
    ],
    "memberships": [
      {"log_id": "1724803312002", "room_id": "1724803312001", "members": [{"user": {"user_id": "ada", "name": "Ada"}, "joined": true}]}
    ]
  }
}
// <- then the result
{"id": "c26", "result": {"room_id": "1724803312001"}}

// -> later, a summarizer bot rewrites the description, resubmitting the title
{
  "method": "room_set", "id": "s9", "params": {
    "room_id": "1724803312001", "title": "Deploy",
    "description": "Root cause: **expired cert** on the build runner. Fix is rolling out."
  }
}
// <- to the thread's members and to general's members
{
  "method": "room_update", "params": {
    "updated": [
      {
        "room_id": "1724803312001", "log_id": "1724803900000", "prev_log_id": "1724803312001",
        "parent_room_id": "general", "title": "Deploy",
        "description": "Root cause: **expired cert** on the build runner. Fix is rolling out.",
        "latest_log_id": "1724803900000", "history_log_id": "1724803312001"
      }
    ]
  }
}
{"id": "s9", "result": {"room_id": "1724803312001"}}

• Fields that end in _id are fixed at creation.
• A server MAY also fix private. An edit that omits private keeps its value.
• ext merges (§4.12). Other omitted fields are cleared.
• parent_room_id MUST refer to an existing visible room.
• private: true makes the room visible only to its members. A thread that is created without private takes the value of its parent. Members add other users by joining them (§4.2.2), if the server supports it.
• A server includes private: true only on a room that it keeps private. A server without private rooms MUST reject a creation with private: true as unsupported.
• A client that asks for a private room checks for private: true in the room_update joined record before it posts in the room. If the value is missing, the client tells the user, and does not use the room.
• Suggested convention: members of a room may edit it.

Live delivery covers only the time that a client is connected. history fills the gaps. It pages through the log, so that a client can show older messages and recover what it missed while it was away.

Adds the history request, a stateless query for a window of the log. With room_id, it queries that room's log (§4.3.1). Without room_id, it queries the log of every room whose deliveries the connection receives (§3.4), as one log. Servers SHOULD support this. A server that does not support it replies unsupported. The result splits the records by kind:

• rooms: room records (§4.2).
• messages: message snapshots (§3.5).
• reactions: reaction sets (§4.7).
• memberships: memberships (§4.2.2).

// ->
{
  "method": "history", "id": "c9", "params": {
    "room_id": "general",
    "after": "1724803200000", "before": "1724806800000", "limit": 200
  }
}
// <-
{
  "id": "c9", "result": {
    "rooms": [],
    "messages": [
      {
        "message_id": "1724803200042", "log_id": "1724803200042", "room_id": "general",
        "from": {...}, "body": {...}
      }
    ],
    "reactions": [
      {
        "log_id": "1724803312011", "message_id": "1724803200042", "room_id": "general",
        "reactions": [{"from": {"user_id": "carol", "name": "Carol"}, "emojis": ["👍"]}]
      }
    ],
    "memberships": [
      {
        "log_id": "1724803300000", "room_id": "general",
        "members": [{"user": {"user_id": "dave", "name": "Dave"}, "joined": true}]
      }
    ],
    "first_log_id": "1724803200042", "last_log_id": "1724803312011", "more": true,
    "latest_log_id": "1724806800000", "history_log_id": "1724800000000"
  }
}

4.3.1 A room's log#

A record about a message, such as a snapshot or a reaction set, is in each room that the message is in just before or just after the record. Room records and memberships are in their own room. The earlier history of a moved message stays in the source room, and prev_room_id points there.

A record can point to the previous record for its key:

• Room records and message snapshots MAY carry prev_log_id, the log_id of the previous record for the same key. Other records do not.
• To get that record, a client sends history with after and before both set to that log_id.
• After a move (§4.4), a message snapshot whose previous record is in another room also carries prev_room_id. That is the room to ask.

4.3.2 Bounds and order#

• after and before are inclusive log_id bounds. Either one MAY be omitted.
• The server limits the bounds to the available history. Then it selects a contiguous slice of the changes in the log, of any kind.
• limit is a positive count of changes, applied before compaction. Servers MAY supply a default.
• With after, the slice starts at the oldest change within the bounds and runs forward. Without after, it ends at the newest and runs back.
• first_log_id and last_log_id are the first and last log_ids of the slice before compaction. The result has both or neither.
• more shows that more changes match in the selected direction. An empty slice returns more: false and neither bound.
• rooms, messages, reactions, and memberships MAY each be omitted when empty. Clients treat a missing array as empty. Each array is in ascending log_id order.
• To continue forward, use after = last_log_id + 1. To continue backward, use before = first_log_id - 1. Calculate these as numbers, and encode them as strings. Never calculate a continuation from compacted records.

4.3.3 Availability and retention#

• With this capability, room records in room_list and room_update MUST carry log_id, latest_log_id, and history_log_id (§4.2).
• Room records in a history result are logged records. Clients ignore their delivery fields.
• Every result includes latest_log_id and history_log_id. The server reads them at the same time as the page. They describe the log, not the page.
• Retention can advance between requests, so clients check each response before they apply it.
• If the server rejects a request for lack of resources, it returns an error, not an empty result.

Over time, servers compact or discard old history:

• Servers SHOULD compact old history at rest, and not discard it. Compaction keeps the latest record for each key (§4.3.4).
• Compacted history is still available. It does not move history_log_id.
• A server that discards the start of the log advances history_log_id.
• The effective lower bound is history_log_id. If history_log_id is null, it is latest_log_id + 1. The effective lower bound MUST NOT decrease.
• Without room_id, the effective lower bound is that of the server's log.
• Before a server discards a part that holds memberships, it appends one membership record. This record lists every current member, with joined: true only.

4.3.4 Compaction#

After the server selects the slice, it MAY compact it:

• It MAY keep only the last room record and the last snapshot of each message in the slice.
• It MAY fold the reaction sets of each message into one record. That record carries the last set of each user in the slice, at the greatest folded log_id.
• It MAY fold the memberships of each room into one record in the same way. That record carries the last membership of each user.
• It keeps empty sets and leaves.
• Kept records keep their original log_ids and contents. They never include changes after the slice.
• A compacted page and an uncompacted page give the same final state.

4.3.5 Replay and recovery#

Replay follows §2.3. A client can apply a record without earlier state. The order across the arrays does not matter.

Recovery, for each room:

1. When live delivery starts, after authentication or after a join, buffer the live records for the room.
2. Get the latest_log_id of the room from its room record (§4.2.1) or from a history page. Call it H. Keep only the buffered records above H.
3. With a checkpoint C, page forward from after: C + 1 with before: H until more: false. Without one, start at after: history_log_id, or load the newest page with before: H and older pages on demand.
4. Apply the buffered records. The checkpoint is now H.

If the effective lower bound of a response is past the next position that the client needs, the client clears the state of the room. It then starts again from that bound. Clients recover each room that they show independently. A thread loads when the user opens it.

A message is a record, so an edit is only a new snapshot of it at a later log position. The same mechanism moves and deletes messages.

Lets a message request with an existing message_id save that message:

• A save replaces every client field (§3.5) with the submitted state, except ext, which merges (§4.12). It removes omitted fields, and replaces objects and arrays whole.
• null does not mean deletion.
• Clients MUST send again every client field that they want to keep, except ext.
• The server keeps message_id, from, and the other server fields.
• Saves apply in server order, and the later save wins.
• A save mentions only the users that it adds to mentions (§3.5.5). Users that were already in the list are not mentioned again.

// -> edit
{
  "method": "message", "id": "c12", "params": {
    "message_id": "1724803200042", "room_id": "general",
    "body": {"text": "hello world", "format": "plain"}
  }
}
// <- snapshot with a new log_id
{
  "method": "message", "params": {
    "message_id": "1724803200042", "log_id": "1724803312007", "room_id": "general",
    "prev_log_id": "1724803200042",
    "from": {"user_id": "alice", "name": "Alice"},
    "body": {"text": "hello world", "format": "plain"}
  }
}
// <-
{"id": "c12", "result": {"message_id": "1724803200042"}}

A save with a different room_id moves the message. The destination MUST exist, and the caller MUST be able to see it. The server delivers the snapshot to both rooms (§4.3.1). Clients move the message, and do not treat it as deleted. The snapshot carries prev_room_id, the source room. If the message has reactions, the server then logs one reactions record (§4.7) in the destination, with every set that is not empty.

// -> move Bob's reply into thread room 1724803312001
{
  "method": "message", "id": "c15", "params": {
    "message_id": "1724803200043", "room_id": "1724803312001",
    "reply_to": {"message_id": "1724803200042"},
    "body": {"text": "Hello back!"}
  }
}
// <- to both rooms
{
  "method": "message", "params": {
    "message_id": "1724803200043", "log_id": "1724803312020", "room_id": "1724803312001",
    "prev_log_id": "1724803200043", "prev_room_id": "general",
    "from": {"user_id": "bob", "name": "Bob"},
    "reply_to": {"message_id": "1724803200042"},
    "body": {"text": "Hello back!"}
  }
}

Delete is a save with deleted: true. body is then optional, and the server MUST omit body and ext from the tombstone. deleted: true on creation is invalid_params.

// ->
{
  "method": "message", "id": "c14", "params": {
    "message_id": "1724803200043", "room_id": "1724803312001", "deleted": true
  }
}
// <-
{
  "method": "message", "params": {
    "message_id": "1724803200043", "log_id": "1724803312050", "room_id": "1724803312001",
    "from": {"user_id": "bob", "name": "Bob"},
    "deleted": true
  }
}

Clients show tombstones, and hide their reactions.

Earlier snapshots of a deleted message still hold its content. A server MAY redact them: it rewrites them, and embedded copies of them (§3.5.4), into tombstones at their original log_ids. Redaction is the only permitted rewrite of a logged record.

Presence and notification control share a capability, because both answer one question: is now a good time to reach this user? A status tells others whether the user is around. Idle reports and mutes tell the server when to hold back notifications.

Lets users choose a status with me (§3.3.2). Clients use the status request to report idle connections, and to set the mutes of the user.

// <- the server frame accepts dnd and invisible
{
  "method": "server", "params": {
    "apron": 9, "capabilities": ["status"], "auth": ["token"],
    "status": ["dnd", "invisible"]
  }
}
// -> do not disturb
{"method": "me", "id": "c40", "params": {"status": "dnd"}}
// <-
{"id": "c40", "result": {"you": {"user_id": "alice", "name": "Alice", "status": "dnd"}}}
// <- to others who share a room
{"method": "user", "params": {"new": {"user_id": "alice", "status": "dnd"}}}

4.5.1 Values#

A user's status has three views:

• The chosen status is the value that the user sets with me.
• The presence is the server's view of the user's connections. It is online if a connection is attended (§4.5.3), idle if no connection is attended, and offline if the user has no connections.
• The shown status is what others see. The server derives it from the chosen status and the presence:

• A chosen "" is no status. Users choose it to opt out. Servers set it when they do not accept a value.
• A chosen dnd silences the notifications of the user, as mute does.
• server.status (§3.1) lists the optional values that the server accepts as a chosen status. Only servers with capability status send it. Servers always accept online and "", and do not list them.
• Clients offer only the listed optional values.
• A server without idle treats the presence of a connected user as online.

4.5.2 Delivery#

• status is only in current user objects (§3.3.1). A change is a user notification. Servers MAY delay it.
• you carries the chosen status. Every other user object carries the shown status.
• Others see only the shown status. They never see the chosen status or the presence.
• Clients take the user's own chosen status only from you. Another object about the user, even a complete one, does not replace it.
• Complete user objects carry status also when it is offline or "".
• A user without a status has no known status.
• Clients show an unknown status value as unknown, with the value.

// <- Alice's last connection closed
{"method": "user", "params": {"new": {"user_id": "alice", "status": "offline", "seen": "1724803600000"}}}

• seen is the time when the shown status last became offline, in the format of a log_id (§2.1).
• seen changes only when the shown status changes to offline (otherwise it would show when a user with a chosen invisible connects).
• A user object MAY carry seen only when it carries a shown offline.
• A server that sends seen includes it in:
  • each complete user object with a shown offline, such as in room_list users.
  • each user notification that changes the shown status to offline.
• Clients show seen only while the shown status is offline.

4.5.3 The status request#

// -> nobody has attended this connection for the last five minutes
{"method": "status", "id": "c41", "params": {"idle": 300}}
// <-
{"id": "c41", "result": {}}
// <- to others who share a room, if Alice's presence becomes idle
{"method": "user", "params": {"new": {"user_id": "alice", "status": "idle"}}}
// -> mute #random until unmuted, and everything for an hour
{"method": "status", "id": "c42", "params": {"room_id": "random", "mute": true}}
{"method": "status", "id": "c43", "params": {"mute": 3600}}
// <- to each of Alice's connections
{"method": "status", "params": {"room_id": "random", "mute": true}}
{"method": "status", "params": {"mute": 3600}}
// <-
{"id": "c42", "result": {}}
{"id": "c43", "result": {}}
// -> too many changes
{"method": "status", "id": "c44", "params": {"mute": false}}
// <-
{"id": "c44", "error": {"code": -32002, "message": "Too Many Requests", "data": {"retry_after": 5}}}
// <- after a later sign-in, the mutes in effect
{"method": "status", "params": {"room_id": "random", "mute": true}}
{"method": "status", "params": {"mute": 1800}}

• Clients send status as a request. The server replies {} when it applies the change.
• If there is an error, such as retry_after or invalid_params, nothing changes.
• A status from the server is a notification.
• Absent fields do not change.

idle reports whether somebody attends the sending connection:

• It is false when somebody attends that connection. Otherwise it is the number of seconds since attention stopped, a non-negative integer.
• A connection starts as attended. It keeps nothing from earlier connections. Its client sends idle when nobody attends it, and idle: false when somebody attends it again.
• Clients MAY wait before they send idle, such as a few minutes without input. They then SHOULD send the seconds since the last input. They do not wait on a connection that starts unattended.
• Servers MAY treat the connection as idle from the time that idle reports, such as to wake the user for mentions since then (§4.9.4).
• Servers never send idle.

mute silences the notifications of the user:

• It is true, false, or a positive integer number of seconds. Without room_id, it applies everywhere. With room_id, it applies only in that room and its threads. A status request with room_id and no mute is invalid_params.
• mute is private. Others never see it.
• Servers without timed mutes treat seconds as true.
• Servers send each change to the mutes of the user to all connections of the user, as status. When a mute ends or is cleared, they send mute: false.
• Clients apply a status that they receive as their own setting.

4.5.4 Sign-in#

At each sign-in (§3.2.2), clients drop the statuses and mutes that they kept, and apply the ones that arrive. After the auth result, the server sends:

• One user notification for each user who shares a room with them, with the shown status in new, unless it is offline or "". Servers MAY limit these to the users that they would list in members (§4.2.1).
• One status notification for each mute in effect, with the seconds left or true.

Adds the activity notification. A client sends it when its activity changes. Activity is typing, and how far the user has read in a room. Each field that is present updates that state. Absent fields do not change it. Activity is not logged. Servers MAY ignore typing and read_message_id.

// -> start typing
{"method": "activity", "params": {"room_id": "general", "typing": 8}}
// -> stop typing
{"method": "activity", "params": {"room_id": "general", "typing": 0}}
// -> advance the read cursor
{"method": "activity", "params": {"room_id": "general", "read_message_id": "1724803312050"}}
// <- (broadcast)
{
  "method": "activity", "params": {
    "room_id": "general", "from": {"user_id": "alice"},
    "typing": 8, "read_message_id": "1724803312050"
  }
}

• typing (seconds): show the user as typing for up to this time, or until a new message from the user arrives. 0 stops it.
• read_message_id: the user read the room up to and including this message. Clients only move it forward. Servers MAY ignore a cursor that moves back.
• Server policy decides the delivery, such as to the room, or only to the user's own connections.
• Servers MAY keep the latest read_message_id of each user in each room. They then send it to the connections of the user after those connections list the room (§4.2.1).

Lets a client set its own complete set of emoji on one message. The server logs the change with a log_id, and broadcasts it to the room of the message. The result is {}.

// ->
{"method": "reactions", "id": "c17", "params": {"message_id": "1724803200043", "emojis": ["👍"]}}
// <- (broadcast)
{
  "method": "reactions", "params": {
    "log_id": "1724803312011", "message_id": "1724803200043", "room_id": "1724803312001",
    "reactions": [{"from": {"user_id": "carol", "name": "Carol"}, "emojis": ["👍"]}]
  }
}
// <-
{"id": "c17", "result": {}}

• The request refers only to the message. The logged record carries the room of the message at that time (§4.3.1).
• The reactions array of the notification holds one element for each user. Its from is a recorded user object (§3.3.1). Live broadcasts carry one element. Compacted history records (§4.3.4) MAY carry more. Each element replaces the set of that user on that message.
• Clients keep state for each (message_id, user_id), and calculate the totals. They accept reactions for messages that they have not loaded.
• emojis entries are strings. Duplicates collapse, and the order does not matter. One emoji sequence in each entry is the interoperable baseline.
• Servers MAY limit the number of distinct emoji on each message or from each user.
• The server MAY log nothing for a request that does not change the state.

Messages can carry more than text: files, live output, previews of links, or interactive content. Each embed has a kind that selects how to render it, and every client has a fallback for kinds that it does not know. Avatars are here because they use the same uploads.

class Embed {
  kind: string;                 // "upload", "stream", "iframe", "html", or another

  embed_id?: string;            // set by servers with any embed:* capability (§4.8.2)
  title?: string;
  url?: string;                 // where a click goes; the server's own for upload and stream
  og?: object;                  // OpenGraph description (§4.8.1)

  // "iframe" kind
  height?: number;              // suggested height

  // "html" kind
  html?: string;

  // "stream" kind (§4.8.5)
  format?: string = "plain";
  text?: string;                // the kept text, once the stream ends
}

body.embeds holds rich content in display order. kind selects the renderer. Clients render an unknown kind from og, or else as the fallback card (§3.5.2).

{"embed_id": "embed_1240", "kind": "upload", "title": "report.pdf", "url": "https://chat.example/f/Qm7xk2…"}
{"embed_id": "embed_1241", "kind": "iframe", "url": "https://backend:8443/term/abc", "height": 300}
{"embed_id": "embed_1242", "kind": "html", "html": "<table>…</table>"}

• iframe: render with sandbox="allow-scripts", and never with allow-same-origin too (together, they let the embed remove its own sandbox). Allow no top navigation and no popups. Use a restrictive Permissions-Policy. Clamp the dimensions, because height is only a suggestion. Load lazily, and limit the number of live iframes at one time.
• html: sanitize it with an allowlist sanitizer, such as DOMPurify, before insertion. Do this for every source.
• upload is §4.8.4, and stream is §4.8.5.

4.8.1 OpenGraph metadata (og)#

Any embed MAY carry og, an OpenGraph description of its content as JSON. Property names drop the og: prefix. Structured properties are nested: og:image:width becomes image.width.

"og": {
  "title": "before.png",
  "image": {"url": "https://chat.example/f/Zr8Tq1…/thumb", "type": "image/webp", "width": 320, "height": 180, "alt": "Dashboard before the fix"}
}

• Clients use the og properties title, description, site_name, and image, video, and audio (each with url, type, width, height, alt). They ignore other properties.
• og.image is a preview to show. og.video and og.audio are what a player loads. The url of the embed is where a click goes.
• Servers SHOULD set og in the broadcast. They MAY keep, replace, or drop an og that a client sent.
• Servers SHOULD host or proxy the media that og refers to, and set its dimensions. Clients SHOULD NOT load og media from other origins.

4.8.2 Embed identity#

Servers that advertise any embed:* capability assign an opaque embed_id to each embed. Other servers MAY store embeds as they receive them.

• A save keeps an embed when it sends the embed back with its embed_id. An embed without an embed_id is new. A save that leaves out an embed_id removes that embed.
• The server owns embed_id, the url of an upload, and the url and text of a stream. It ignores them in requests, and restores them from its records on a save.
• Servers SHOULD delete the content that they host for an embed when the embed is removed, or when its message is deleted or redacted.
• Servers SHOULD make the URLs they host unguessable, such as with a random path segment rather than just the embed_id.

4.8.3 Writes#

New upload and stream embeds get their content over HTTP. The result of the message or command (§4.1) lists them, in request order:

// -> the sender attaches a file
{
  "method": "message", "id": "c8", "params": {
    "room_id": "general",
    "body": {"text": "Before the fix:", "embeds": [{"kind": "upload", "title": "before.png"}]}
  }
}
// <- the broadcast first, with the embed pending
{"embed_id": "embed_1235", "kind": "upload", "title": "before.png"}
// <- then the result, with the write URL for the sender only
{
  "id": "c8", "result": {
    "message_id": "1724803500000",
    "embeds": [{"embed_id": "embed_1235", "kind": "upload", "write_url": "https://chat.example/w/4c7a…"}]
  }
}
// sender: curl -T before.png https://chat.example/w/4c7a…
// <- the embed as broadcast in a later snapshot, completed
{
  "embed_id": "embed_1235", "kind": "upload", "title": "before.png",
  "url": "https://chat.example/f/Zr8Tq1…",
  "og": {
    "title": "before.png",
    "image": {"url": "https://chat.example/f/Zr8Tq1…/thumb", "type": "image/webp", "width": 320, "height": 180}
  }
}

• The sender sends the content as the body of an HTTP PUT to write_url. write_url is a credential. It expires if it is not used.
• The server finishes each write exactly one time. On success, it publishes a snapshot with the completed embed. If the write fails or does not start in time, it publishes a snapshot without the embed.
• For a command, the server uses the finished write instead, such as to set an avatar (§4.8.6).

4.8.4 embed:upload#

Adds upload embeds: files the sender writes over HTTPWithout it no attachments

Adds upload embeds, files that the sender writes over HTTP. The sender gives an optional title, such as the file name. While url is absent, the upload is pending, and clients show a placeholder. On success, the server sets url to the file that it hosts.

• The server SHOULD add og describing the file: image for a preview, and video or audio for playable media. It MAY keep what the sender gave, such as og.image.alt.
• Without og, clients show a file card: title, with a link to url.

4.8.5 embed:stream#

Adds live-streamed text in a messageWithout it post the finished text

Lets a message carry live text. The sender writes it over HTTP, and readers see it grow. Stream embeds follow the rules for embed identity (§4.8.2) and writes (§4.8.3).

// -> the embed in a message request; the result and write follow §4.8.3
{"kind": "stream", "format": "terminal"}
// sender: foo 2>&1 | curl -T - <write_url>
// <- the embed as broadcast: live at its url, then finished with the kept text
{"embed_id": "embed_1234", "kind": "stream", "format": "terminal", "url": "https://chat.example/s/p3Wn9d…"}
{"embed_id": "embed_1234", "kind": "stream", "format": "terminal", "text": "…"}

• format defines how to render the text. The default, "plain", shows the text as is, with its line breaks. Clients MAY support other formats natively, such as "markdown" (CommonMark, §3.5.2) or "terminal". They render unknown formats as plain.
• Write: the sender sends UTF-8 text as a streaming PUT body to write_url. The end of the body ends the stream.
• Read: GET url returns the text that the server kept. It continues as more text arrives, and ends when the stream ends. A reader that reconnects replaces the text that it showed with the new response.
• Finish: when the stream ends, the server publishes a snapshot whose embed carries the kept text as text, in place of url. Both URLs then stop working. If the server has capability edit, the sender MAY save the message without the embed before that. This ends the stream.
• Server policy sets how much text the server keeps, the size and time limits, and the grace period after a writer disconnects. At a limit, the server ends the stream, and keeps the last part of the text.
• The chat server serves url. Clients SHOULD NOT connect to stream URLs on other origins.

4.8.6 Avatars#

A user object (§3.3) MAY carry avatar, an image to show next to the name of the user.

• Servers SHOULD send only https: URLs, or small data:image/{png,jpeg,gif,webp};base64, URLs.
• A larger image goes through an upload, with capabilities command and embed:upload. A /avatar command (§4.1) with one upload embed asks the server to use that file as the avatar of the sender. When the upload completes, the server sets avatar and sends user (§3.3.3).
• Clients choose which avatar sources to load, and MAY ignore any avatar. They load avatars only as images, never as documents. They bind or escape the values, and never insert them into HTML as raw text.
• Without a usable avatar, clients draw a placeholder such as initials.

Push reaches users when no client is open, such as a phone in a pocket. The server sends a small payload to a push service that the client registered, and the client shows it as a notification. Push has no capability of its own. server.push advertises it.

server.push (§3.1) maps each supported push kind to its public configuration. Its wake key lists the wake scopes that the server supports. If server.push is present, the server accepts push_register and push_unregister. A server that advertises push SHOULD advertise status (§4.5).

// <- the server frame offers relay and webpush
{
  "method": "server", "params": {
    "apron": 9, "capabilities": ["status"], "auth": ["webauthn", "token"],
    "push": {"relay": {}, "webpush": {"key": "BNcR..."}, "wake": ["mentions", "replies", "private"]}
  }
}
// ->
{
  "method": "push_register", "id": "c30", "params": {
    "kind": "relay", "url": "https://relay.example/p/xyz", "token": "...", "push_id": "t65S5XBst9bSDpjJ",
    "keys": {"p256dh": "BKx...", "auth": "Q2w..."}
  }
}
// ->
{
  "method": "push_register", "id": "c31", "params": {
    "kind": "webpush", "url": "https://push.example/s/abc", "push_id": "t65S5XBst9bSDpjJ",
    "keys": {"p256dh": "BOr...", "auth": "Hn3..."}, "wake": ["mentions", "private"]
  }
}
// ->
{"method": "push_unregister", "id": "c32", "params": {"url": "https://relay.example/p/xyz"}}

4.9.1 Registration#

• kind is a key of server.push other than wake. Fields other than url, push_id, and wake are specific to the kind. Third-party kinds (§4) define their own delivery.
• url is required. A registration belongs to the authenticated user and its url. It stays after the connection that made it closes.
• A registration with the same url replaces the earlier registration of the user. push_unregister removes it. Unregistering an unknown url succeeds.
• Servers MAY refuse a registration with denied, such as from a guest (§3.2). An endpoint that the server will not send to is invalid_params.
• Servers SHOULD accept only https push endpoints that resolve to addresses that are not internal.
• push_id (optional) is 1 to 64 characters from A-Z a-z 0-9 - _. Clients choose one for each server and account. It is an opaque value that shows neither the server nor the account.
• Clients SHOULD register on each connection. Servers MAY drop a registration that the client did not renew within a server-defined period. Servers MAY also drop the least recently renewed registrations above a server-defined number for each user.
• Clients SHOULD unregister before they sign out. Servers MAY remove the registrations of a user when they revoke the sessions of that user.
• Servers remove a registration whose url does not accept pushes, such as one that answers 404 or 410.

4.9.2 Kinds#

• relay: the server sends the payload in a POST to url, with token (optional) as a bearer token. The relay is responsible for delivery after that POST. Native apps use a relay that their vendor runs.
  • keys (optional) holds a p256dh and an auth that the client generated, as for webpush.
  • With keys, the body is the payload, encrypted as for webpush. It has Content-Type: application/octet-stream and Content-Encoding: aes128gcm.
  • Without keys, the body is the payload with Content-Type: application/json.
• webpush: Web Push (RFC 8030).
  • key is the VAPID public key of the server (RFC 8292): an uncompressed P-256 point in unpadded base64url. Clients subscribe with it as the application server key. They subscribe again when it changes.
  • url is the subscription endpoint. keys (required) holds its p256dh and auth in unpadded base64url, as in PushSubscription.toJSON().
  • Servers encrypt the payload as one aes128gcm record (RFC 8291), and sign with the private key for key.
• Servers send TTL and Urgency headers (RFC 8030) with every push, also to relays. Urgency is:
  • low for a push without message.
  • normal for a push that only joined selects.
  • high for all other pushes.

4.9.3 Payload#

Every kind delivers the same payload: a UTF-8 JSON object of at most 2048 bytes.

• push_id: the push_id of the registration, if it has one. Clients drop a payload with a push_id that they do not know. A client that registered a push_id MAY drop a payload without one.
• unread (optional): the unread count of the user, as the server counts it, such as messages after the read cursors of the user (§4.6). It is the same for all registrations of the user. Clients MAY show it as an app badge.
  • Servers whose server.push.wake lists badge send unread.
  • Servers MAY leave messages that a room mute silences out of unread. A mute without room_id does not change unread.
• message: the message (§3.5) without log_id. Clients never install it as a snapshot. Servers do not push transient notices.
  • Servers SHOULD omit format, embeds, and ext.
  • To fit the limit, servers MAY truncate body.text, and leave out any field except message_id, room_id, and from.user_id.
  • A payload without message shows no notification.
• Clients SHOULD show at most one notification for each push_id and message_id. A later notification for the same pair replaces the earlier one, from a push or from the client's own connection.

// a message push
{
  "push_id": "t65S5XBst9bSDpjJ", "unread": 2,
  "message": {
    "message_id": "1724803200042", "room_id": "general",
    "from": {"user_id": "alice", "name": "Alice"},
    "body": {"text": "Deploy is done, can someone check the dashboards?"}
  }
}
// a badge push, after the user read on another device
{"push_id": "t65S5XBst9bSDpjJ", "unread": 0}

4.9.4 Wake#

• wake (optional) lists the scopes that a registration wakes for. Each scope except badge selects new messages in rooms that the user can see:
  • mentions: messages whose mentions list the user (§3.5.5). Servers MAY also wake for an edit that adds the user to mentions.
  • private: messages in private rooms (§4.2.4) that the user joined, and in their threads.
  • replies: messages whose reply_to refers to a message of the user (§3.5.4).
  • joined: messages in rooms that the user joined.
  • badge: every change to unread. A push for a change that no other scope selects has no message. Servers ignore badge for webpush. Servers MAY skip intermediate values of unread, and send only the latest.
• Servers advertise only the scopes that they implement, and ignore other scopes in wake. An empty wake wakes for nothing. Without wake, the server uses its default scopes. These SHOULD be mentions and replies, where advertised.
• A push that mute or a chosen dnd (§4.5.1) silences has no message. It goes only to registrations that wake for badge.
• Servers do not wake a user for the user's own messages. Server policy decides other wake rules, such as rate limits.
• Suggested convention: wake a user only when the user's presence is idle or offline (§4.5.1). Servers MAY wait a short time first, and skip the push if the read_message_id of the user is past the message.

Passkeys let users sign in without passwords or shared tokens, with a credential that their device keeps.

A passkey is bound to its RP ID, the domain of the web client that registered it. Browsers offer it only on that domain, so a phishing site cannot use it. This also means that a third-party client cannot sign in with another client's passkey. To add such a client or device, the user signs in with another scheme, such as token (§3.2.1) or email (§4.11). A server can also offer a command (§4.1) that issues more bearer tokens.

Servers that list webauthn in server.auth MUST use this exchange. No separate capability is necessary.

Both steps are auth requests with scheme: "webauthn". action: "register" creates a credential, and action: "login" signs in. Both steps use the same action.

public_key holds creation options for a registration, or request options for a login. It uses standard WebAuthn JSON, with binary fields as unpadded base64url. Clients pass it to navigator.credentials.create or .get, and return the credential in finish.

• Registration MUST require discoverable credentials.
• Login omits allowCredentials, or sends an empty array.
• Both actions require user verification.
• Servers SHOULD use the name (§3.2) of a register begin step for user.name and user.displayName in public_key.

Challenges MUST be unpredictable, and MUST expire. They MUST be bound to the connection, the action, the RP ID, the allowed origin, and any proposed registration identity.

• A connection has one pending ceremony. A new begin step replaces it, and a disconnect cancels it. A matching finish step uses it up, also when the step fails.
• Servers MUST perform WebAuthn verification before they record a credential or authenticate.
• Only a verified finish step returns you.
• A registration on a connection that is already signed in adds the passkey to that account.
• Server policy decides who can register, and who can authenticate again.
• Invalid challenges and failed verification are denied.

A verified finish result MAY carry a bearer token (§3.2.1) to resume the session, if the server also lists token. Servers MUST bind such a token to the allowed origin of the ceremony, and MUST make it expire. A mismatched origin is denied.

Some sign-ins finish outside the connection. Email sign-in proves that a user controls an address. It suits sign-up and account recovery, and works on any device that gets mail. External sign-in sends the user to a web page of the server. The page can put any sign-in portal in front of Apron, such as OAuth, OpenID Connect, SAML, SSO, or a password check against a SASL backend.

Servers that list email or external in server.auth use this exchange, and also list token. An auth request without token proposes a sign-in or an addition. The server delivers a temporary token outside the connection. An auth request with that token approves the proposal:

// -> propose signing in with this address
{"method": "auth", "id": "c1", "params": {"scheme": "email", "email": "ada@example.com", "state": "q8Rz…"}}
// <- nothing is authenticated yet
{"id": "c1", "result": {}}

// email: "Your code is 418092, or open https://chat.example/login#token=Hk41x9…&state=q8Rz…"

// -> on any connection not signed in, such as one opened by the link
{"method": "auth", "id": "c2", "params": {"scheme": "email", "token": "Hk41x9…"}}
// <- signed in, with a bearer token for later connections
{"id": "c2", "result": {"you": {"user_id": "ada", "name": "Ada"}, "token": "st_Hk41…"}}

// -> propose an external sign-in that returns to this client
{"method": "auth", "id": "c1", "params": {"scheme": "external", "return_url": "https://web.apron.chat/", "state": "q8Rz…"}}
// <- the page to open
{"id": "c1", "result": {"url": "https://chat.example/sso?p=Qm7x…"}}

// the page signs the user in, then redirects to
// https://web.apron.chat/#token=Hk41x9…&state=q8Rz…&server=wss://chat.example/ws

// -> on a connection from https://web.apron.chat
{"method": "auth", "id": "c2", "params": {"scheme": "external", "token": "Hk41x9…"}}
// <-
{"id": "c2", "result": {"you": {"user_id": "ada", "name": "Ada"}, "token": "st_Hk41…"}}

4.11.1 Proposals#

• A proposal is an auth request without token. It authenticates nothing.
• On a connection that is signed in to an account, guests included, a proposal adds to that account. Otherwise it proposes a sign-in.
• A connection has one pending proposal, and a new one replaces it.
• A proposal expires within minutes. A disconnect does not cancel it. Approval uses it up.
• Failed attempts count against the proposal, whichever connection makes them. A few failed attempts cancel it.
• A proposal MAY carry state, an unguessable value of at most 256 bytes that the client chooses (like OAuth's state, it guards against a link that signs the user in to someone else's account). The server returns it unchanged in each link.

4.11.2 Temporary tokens#

• The server delivers a temporary token for the proposal, as a link, a code to type, or both.
• A temporary token expires within minutes of its delivery.
• A token that is short enough to type, such as six digits, works only on the connection that made the proposal (short codes are easy to guess). A token that works on other connections MUST be unguessable.
• A link carries the token in its URL fragment: #token=…, plus &state=… when the proposal carried state, plus &server=… with the server's address (A.4).
• A client asks its user before it uses a link without the state of a proposal that the client made. It then presents the link's token with scheme: "token".
• For a link with the state of its own proposal, a client uses the server that it proposed to, and ignores server.

4.11.3 Approval#

• Approval is an auth request with token, and token or either scheme that the server offers.
• Approval of a sign-in authenticates the connection that presents the token. That connection MUST NOT be signed in already. The result carries you and a bearer token for later connections (§3.2.1).
• Approval of an addition works only on a connection that is signed in to the account that proposed it (otherwise someone could lead a victim to link the victim's identity to the other person's account). It adds the address or the external identity to that account, and returns {}.
• An invalid, expired, or used token is denied. A sign-in token on a signed-in connection is also denied, and so is an address or an external identity that belongs to another account.

4.11.4 Email#

• A proposal carries email. It returns {}, whether or not the address has an account.
• The server emails the temporary token. It builds any link from its own configuration.
• Account creation for unknown addresses, send rate limits (retry_after), and the bearer token's lifetime are server policy.

4.11.5 External#

• A proposal MAY carry return_url, a URL of the client. Servers MUST accept only a return_url on an origin that they trust (otherwise the page would hand a working token to any site).
• A proposal returns url, a page of the server. url is an absolute https URL, or http on a loopback host. Clients reject any other url, such as javascript:….
• The client opens url in a browser. The page signs the user in by a method that the server chooses.
• With return_url, the page shows its host, and whether the user signs in or adds an identity. The page asks the user to confirm before it redirects, also when the user is already signed in to the page.
• The page redirects to return_url with the link fragment, which replaces any fragment of return_url.
• Without return_url, the page shows a code to type after the user signs in. It tells the user to type the code only in the client where they started.
• Servers SHOULD accept a link token only on a connection from the origin of return_url, such as by the WebSocket Origin header.
• Account creation for new external identities is server policy.

Some data has no field in this document: a bridge's IDs for the messages it relays, an agent's settings for a room, or a user's time zone. Capability ext gives that data a place that survives other clients' saves.

Keeps the ext that clients write on users, messages, and rooms, and merges it as below. ext is an object whose keys are extension names without the ext: prefix (§4), such as irc:

"ext": {"irc": {"network": "libera", "channel": "#ops", "nick": "ada_", "msgid": "a1b2c3"}}

• A write merges ext one level down. Each key that it carries replaces the kept value, an empty value ("", [], {}) clears that key, and keys that it leaves out stay. The value under a key is replaced whole. null is an ordinary value, and "ext": {} changes nothing.
• Writes are me (§3.3.2), message requests (§3.5, §4.4), and room_set (§4.2.4). A write that creates a record, or saves a message whose current snapshot is a tombstone, merges into an empty ext. A save with deleted: true drops ext.
• Complete user objects and records carry their complete ext. A user notification carries at least each key that changed, with a cleared key as its empty value, and clients merge it the same way.
• Clients do not have to parse ext, or send it back.
• Size limits apply to the merged ext. A write whose merged ext is over a limit is too_large, and changes nothing.
• Clients send ext only to a server that advertises capability ext, or the capability of the extension that defines the key.
• Without capability ext, servers MAY drop the ext that clients send.
• An extension keeps its own data under its name in ext, on whatever object it defines, such as the server frame. It needs only its own capability.

// kept: "ext": {"irc": {"nick": "ada_"}, "tz": "Europe/Oslo"}
// -> change the time zone only
{"method": "me", "id": "c50", "params": {"ext": {"tz": "America/Toronto"}}}
// <-
{"id": "c50", "result": {"you": {"user_id": "ada", "name": "Ada", "ext": {"irc": {"nick": "ada_"}, "tz": "America/Toronto"}}}}
// -> clear irc
{"method": "me", "id": "c51", "params": {"ext": {"irc": ""}}}
// <-
{"id": "c51", "result": {"you": {"user_id": "ada", "name": "Ada", "ext": {"tz": "America/Toronto"}}}}