From f0411a3cc5a1f0f041e51b06fe32a9c25f2e19bc Mon Sep 17 00:00:00 2001
From: Sorunome <mail@sorunome.de>
Date: Mon, 13 Jan 2020 12:52:22 +0100
Subject: [PATCH] make clear displayname and avatar_url are optional, add
 status codes

---
 proposals/2403-knock.md | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/proposals/2403-knock.md b/proposals/2403-knock.md
index 6e3396c6b..b8a816bcb 100644
--- a/proposals/2403-knock.md
+++ b/proposals/2403-knock.md
@@ -6,7 +6,8 @@ said room.
 # Proposal
 This proposal implements the reserved "knock" membership type for the `m.room.member` state event.
 This state event indicates that a user knocks a room, that is asking for permission to join. It
-contains an optional "reason" parameter to specify the reason you want to join. This membership can
+contains an optional "reason" parameter to specify the reason you want to join. Like other
+memtership types the parameters "displayname" and "avatar_url" are optional. This membership can
 be set from users who aren't currently in said room. An example for the membership would look as
 follows:
 ```json
@@ -77,6 +78,14 @@ The user knocked successfully. Empty reply:
 {}
 ```
 
+#### Status code 400:
+This request was invalid, e.g. bad JSON. Example reply:
+```json
+{
+  "errcode": "M_UNKNOWN",
+  "error": "An unknown error occurred"}
+```
+
 #### Status code 403:
 The user wasn't allowed to knock (e.g. they are banned). Error reply:
 ```json
@@ -86,6 +95,16 @@ The user wasn't allowed to knock (e.g. they are banned). Error reply:
 }
 ```
 
+#### Status code 429:
+This request was rate-limited. Example reply:
+```json
+{
+  "errcode": "M_LIMIT_EXCEEDED",
+  "error": "Too many requests",
+  "retry_after_ms": 2000
+}
+```
+
 ## Server-Server API
 The new endpoint for the server-server API is `PUT /_matrix/federation/v2/knock/{roomId}/{eventId}`.
 The path parameters are the room id you want to knock and the event id of the knock event. The post
@@ -123,12 +142,22 @@ The knock was performed successfully. The knock event is sent back with the "eve
     "state_key": "@alice:example.org",
     "content": {
       "membership": "knock",
+      "displayname": "Alice",
+      "avatar_url": "mxc://example.org/avatar",
       "reason": "I want to join this room as I really love foxes!"
     }
   }
 }
 ```
 
+#### Status code 400:
+This request was invalid, e.g. bad JSON. Example reply:
+```json
+{
+  "errcode": "M_UNKNOWN",
+  "error": "An unknown error occurred"}
+```
+
 #### Status code 403:
 The user wasn't allowed to knock. Error reply:
 ```json