{"action":"created","comment":{"url":"https://api.github.com/repos/matrix-org/matrix-doc/pulls/comments/41758813","id":41758813,"diff_hunk":"@@ -3,27 +3,154 @@ Instant Messaging\n \n .. _module:im:\n \n+This module adds support for sending human-readable messages to a room. It also\n+adds support for associating human-readable information with the room itself\n+such as a room name and topic.\n+\n Events\n ------\n \n {{m_room_message_event}}\n \n+\n+.. admonition:: Rationale\n+\n+  Not all clients can display all message types. The most commonly supported\n+  message type is raw text. As a result, we chose to have a textual fallback\n+  display method represented by the ``body`` key. This means that even if the\n+  client cannot display a particular ``msgtype``, they can still display\n+  *something*, even if it is just plain text.\n+\n {{m_room_message_feedback_event}}\n \n+Usage of this event is discouraged for several reasons:\n+ - The number of feedback events will grow very quickly with the number of users\n+   in the room. This event provides no way to \"batch\" feedback, unlike the\n+   `receipts module`_.\n+ - Pairing feedback to messages gets complicated when paginating as feedback\n+   arrives before the message it is acknowledging.\n+ - There are no guarantees that the client has seen the event ID being\n+   acknowledged.\n+\n+\n+.. _`receipts module`: `module:receipts`_\n+\n {{m_room_name_event}}\n \n {{m_room_topic_event}}\n \n m.room.message msgtypes\n------------------------\n-\n-.. TODO-spec\n-   How a client should handle unknown message types.\n-\n+~~~~~~~~~~~~~~~~~~~~~~~\n \n Each `m.room.message`_ MUST have a ``msgtype`` key which identifies the type\n of message being sent. Each type has their own required and optional keys, as\n-outlined below.\n+outlined below. If a client cannot display the given ``msgtype`` then it MUST\n+display the fallback plain text ``body`` key instead.\n \n {{msgtype_events}}\n \n+\n+Client behaviour\n+----------------\n+\n+Clients SHOULD verify the structure of incoming events to ensure that the\n+expected keys exist and that they are of the right type. Clients can discard\n+malformed events or display a placeholder message to the user. Redacted\n+``m.room.message`` events MUST be removed from the client. This can either be\n+replaced with placeholder text (e.g. \"[REDACTED]\") or the redacted message can\n+be removed entirely from the messages view.\n+\n+Events which have attachments (e.g. ``m.image``, ``m.file``) SHOULD be\n+uploaded using the `content repository module`_ where available. The\n+resulting ``mxc://`` URI can then be used in the ``url`` key. The\n+attachment SHOULD be uploaded *prior* to sending the event in order to stop a","path":"specification/modules/instant_messaging.rst","position":70,"original_position":70,"commit_id":"91ca36509b3112a83680a97a0d672a428b4d7fef","original_commit_id":"91ca36509b3112a83680a97a0d672a428b4d7fef","user":{"login":"illicitonion","id":1131704,"avatar_url":"https://avatars.githubusercontent.com/u/1131704?v=3","gravatar_id":"","url":"https://api.github.com/users/illicitonion","html_url":"https://github.com/illicitonion","followers_url":"https://api.github.com/users/illicitonion/followers","following_url":"https://api.github.com/users/illicitonion/following{/other_user}","gists_url":"https://api.github.com/users/illicitonion/gists{/gist_id}","starred_url":"https://api.github.com/users/illicitonion/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/illicitonion/subscriptions","organizations_url":"https://api.github.com/users/illicitonion/orgs","repos_url":"https://api.github.com/users/illicitonion/repos","events_url":"https://api.github.com/users/illicitonion/events{/privacy}","received_events_url":"https://api.github.com/users/illicitonion/received_events","type":"User","site_admin":false},"body":"SHOULD? How would they have the mxc:// URL without having done so?","created_at":"2015-10-12T14:02:22Z","updated_at":"2015-10-12T14:02:22Z","html_url":"https://github.com/matrix-org/matrix-doc/pull/85#discussion_r41758813","pull_request_url":"https://api.github.com/repos/matrix-org/matrix-doc/pulls/85","_links":{"self":{"href":"https://api.github.com/repos/matrix-org/matrix-doc/pulls/comments/41758813"},"html":{"href":"https://github.com/matrix-org/matrix-doc/pull/85#discussion_r41758813"},"pull_request":{"href":"https://api.github.com/repos/matrix-org/matrix-doc/pulls/85"}}},"pull_request":{"url":"https://api.github.com/repos/matrix-org/matrix-doc/pulls/85","id":47012524,"html_url":"https://github.com/matrix-org/matrix-doc/pull/85","diff_url":"https://github.com/matrix-org/matrix-doc/pull/85.diff","patch_url":"https://github.com/matrix-org/matrix-doc/pull/85.patch","issue_url":"https://api.github.com/repos/matrix-org/matrix-doc/issues/85","number":85,"state":"open","locked":false,"title":"Instant messaging module","user":{"login":"Kegsay","id":7190048,"avatar_url":"https://avatars.githubusercontent.com/u/7190048?v=3","gravatar_id":"","url":"https://api.github.com/users/Kegsay","html_url":"https://github.com/Kegsay","followers_url":"https://api.github.com/users/Kegsay/followers","following_url":"https://api.github.com/users/Kegsay/following{/other_user}","gists_url":"https://api.github.com/users/Kegsay/gists{/gist_id}","starred_url":"https://api.github.com/users/Kegsay/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Kegsay/subscriptions","organizations_url":"https://api.github.com/users/Kegsay/orgs","repos_url":"https://api.github.com/users/Kegsay/repos","events_url":"https://api.github.com/users/Kegsay/events{/privacy}","received_events_url":"https://api.github.com/users/Kegsay/received_events","type":"User","site_admin":false},"body":"This PR changes the IM module to conform to the module template. It also adds in a lot of new information about client behaviour.","created_at":"2015-10-07T10:53:05Z","updated_at":"2015-10-12T14:02:22Z","closed_at":null,"merged_at":null,"merge_commit_sha":"756eaf1a5c89eb349f856eee50c08e4410c4cc2f","assignee":{"login":"illicitonion","id":1131704,"avatar_url":"https://avatars.githubusercontent.com/u/1131704?v=3","gravatar_id":"","url":"https://api.github.com/users/illicitonion","html_url":"https://github.com/illicitonion","followers_url":"https://api.github.com/users/illicitonion/followers","following_url":"https://api.github.com/users/illicitonion/following{/other_user}","gists_url":"https://api.github.com/users/illicitonion/gists{/gist_id}","starred_url":"https://api.github.com/users/illicitonion/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/illicitonion/subscriptions","organizations_url":"https://api.github.com/users/illicitonion/orgs","repos_url":"https://api.github.com/users/illicitonion/repos","events_url":"https://api.github.com/users/illicitonion/events{/privacy}","received_events_url":"https://api.github.com/users/illicitonion/received_events","type":"User","site_admin":false},"milestone":null,"commits_url":"https://api.github.com/repos/matrix-org/matrix-doc/pulls/85/commits","review_comments_url":"https://api.github.com/repos/matrix-org/matrix-doc/pulls/85/comments","review_comment_url":"https://api.github.com/repos/matrix-org/matrix-doc/pulls/comments{/number}","comments_url":"https://api.github.com/repos/matrix-org/matrix-doc/issues/85/comments","statuses_url":"https://api.github.com/repos/matrix-org/matrix-doc/statuses/91ca36509b3112a83680a97a0d672a428b4d7fef","head":{"label":"matrix-org:module-im","ref":"module-im","sha":"91ca36509b3112a83680a97a0d672a428b4d7fef","user":{"login":"matrix-org","id":8418310,"avatar_url":"https://avatars.githubusercontent.com/u/8418310?v=3","gravatar_id":"","url":"https://api.github.com/users/matrix-org","html_url":"https://github.com/matrix-org","followers_url":"https://api.github.com/users/matrix-org/followers","following_url":"https://api.github.com/users/matrix-org/following{/other_user}","gists_url":"https://api.github.com/users/matrix-org/gists{/gist_id}","starred_url":"https://api.github.com/users/matrix-org/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/matrix-org/subscriptions","organizations_url":"https://api.github.com/users/matrix-org/orgs","repos_url":"https://api.github.com/users/matrix-org/repos","events_url":"https://api.github.com/users/matrix-org/events{/privacy}","received_events_url":"https://api.github.com/users/matrix-org/received_events","type":"Organization","site_admin":false},"repo":{"id":24998719,"name":"matrix-doc","full_name":"matrix-org/matrix-doc","owner":{"login":"matrix-org","id":8418310,"avatar_url":"https://avatars.githubusercontent.com/u/8418310?v=3","gravatar_id":"","url":"https://api.github.com/users/matrix-org","html_url":"https://github.com/matrix-org","followers_url":"https://api.github.com/users/matrix-org/followers","following_url":"https://api.github.com/users/matrix-org/following{/other_user}","gists_url":"https://api.github.com/users/matrix-org/gists{/gist_id}","starred_url":"https://api.github.com/users/matrix-org/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/matrix-org/subscriptions","organizations_url":"https://api.github.com/users/matrix-org/orgs","repos_url":"https://api.github.com/users/matrix-org/repos","events_url":"https://api.github.com/users/matrix-org/events{/privacy}","received_events_url":"https://api.github.com/users/matrix-org/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/matrix-org/matrix-doc","description":"Matrix Documentation (including The Spec)","fork":false,"url":"https://api.github.com/repos/matrix-org/matrix-doc","forks_url":"https://api.github.com/repos/matrix-org/matrix-doc/forks","keys_url":"https://api.github.com/repos/matrix-org/matrix-doc/keys{/key_id}","collaborators_url":"https://api.github.com/repos/matrix-org/matrix-doc/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/matrix-org/matrix-doc/teams","hooks_url":"https://api.github.com/repos/matrix-org/matrix-doc/hooks","issue_events_url":"https://api.github.com/repos/matrix-org/matrix-doc/issues/events{/number}","events_url":"https://api.github.com/repos/matrix-org/matrix-doc/events","assignees_url":"https://api.github.com/repos/matrix-org/matrix-doc/assignees{/user}","branches_url":"https://api.github.com/repos/matrix-org/matrix-doc/branches{/branch}","tags_url":"https://api.github.com/repos/matrix-org/matrix-doc/tags","blobs_url":"https://api.github.com/repos/matrix-org/matrix-doc/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/matrix-org/matrix-doc/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/matrix-org/matrix-doc/git/refs{/sha}","trees_url":"https://api.github.com/repos/matrix-org/matrix-doc/git/trees{/sha}","statuses_url":"https://api.github.com/repos/matrix-org/matrix-doc/statuses/{sha}","languages_url":"https://api.github.com/repos/matrix-org/matrix-doc/languages","stargazers_url":"https://api.github.com/repos/matrix-org/matrix-doc/stargazers","contributors_url":"https://api.github.com/repos/matrix-org/matrix-doc/contributors","subscribers_url":"https://api.github.com/repos/matrix-org/matrix-doc/subscribers","subscription_url":"https://api.github.com/repos/matrix-org/matrix-doc/subscription","commits_url":"https://api.github.com/repos/matrix-org/matrix-doc/commits{/sha}","git_commits_url":"https://api.github.com/repos/matrix-org/matrix-doc/git/commits{/sha}","comments_url":"https://api.github.com/repos/matrix-org/matrix-doc/comments{/number}","issue_comment_url":"https://api.github.com/repos/matrix-org/matrix-doc/issues/comments{/number}","contents_url":"https://api.github.com/repos/matrix-org/matrix-doc/contents/{+path}","compare_url":"https://api.github.com/repos/matrix-org/matrix-doc/compare/{base}...{head}","merges_url":"https://api.github.com/repos/matrix-org/matrix-doc/merges","archive_url":"https://api.github.com/repos/matrix-org/matrix-doc/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/matrix-org/matrix-doc/downloads","issues_url":"https://api.github.com/repos/matrix-org/matrix-doc/issues{/number}","pulls_url":"https://api.github.com/repos/matrix-org/matrix-doc/pulls{/number}","milestones_url":"https://api.github.com/repos/matrix-org/matrix-doc/milestones{/number}","notifications_url":"https://api.github.com/repos/matrix-org/matrix-doc/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/matrix-org/matrix-doc/labels{/name}","releases_url":"https://api.github.com/repos/matrix-org/matrix-doc/releases{/id}","created_at":"2014-10-09T16:41:02Z","updated_at":"2015-08-31T11:12:35Z","pushed_at":"2015-10-12T09:04:17Z","git_url":"git://github.com/matrix-org/matrix-doc.git","ssh_url":"git@github.com:matrix-org/matrix-doc.git","clone_url":"https://github.com/matrix-org/matrix-doc.git","svn_url":"https://github.com/matrix-org/matrix-doc","homepage":null,"size":3688,"stargazers_count":19,"watchers_count":19,"language":"JavaScript","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":5,"mirror_url":null,"open_issues_count":11,"forks":5,"open_issues":11,"watchers":19,"default_branch":"master"}},"base":{"label":"matrix-org:master","ref":"master","sha":"a320d58948d6aa2d39eac3f95685276e4b25eef1","user":{"login":"matrix-org","id":8418310,"avatar_url":"https://avatars.githubusercontent.com/u/8418310?v=3","gravatar_id":"","url":"https://api.github.com/users/matrix-org","html_url":"https://github.com/matrix-org","followers_url":"https://api.github.com/users/matrix-org/followers","following_url":"https://api.github.com/users/matrix-org/following{/other_user}","gists_url":"https://api.github.com/users/matrix-org/gists{/gist_id}","starred_url":"https://api.github.com/users/matrix-org/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/matrix-org/subscriptions","organizations_url":"https://api.github.com/users/matrix-org/orgs","repos_url":"https://api.github.com/users/matrix-org/repos","events_url":"https://api.github.com/users/matrix-org/events{/privacy}","received_events_url":"https://api.github.com/users/matrix-org/received_events","type":"Organization","site_admin":false},"repo":{"id":24998719,"name":"matrix-doc","full_name":"matrix-org/matrix-doc","owner":{"login":"matrix-org","id":8418310,"avatar_url":"https://avatars.githubusercontent.com/u/8418310?v=3","gravatar_id":"","url":"https://api.github.com/users/matrix-org","html_url":"https://github.com/matrix-org","followers_url":"https://api.github.com/users/matrix-org/followers","following_url":"https://api.github.com/users/matrix-org/following{/other_user}","gists_url":"https://api.github.com/users/matrix-org/gists{/gist_id}","starred_url":"https://api.github.com/users/matrix-org/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/matrix-org/subscriptions","organizations_url":"https://api.github.com/users/matrix-org/orgs","repos_url":"https://api.github.com/users/matrix-org/repos","events_url":"https://api.github.com/users/matrix-org/events{/privacy}","received_events_url":"https://api.github.com/users/matrix-org/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/matrix-org/matrix-doc","description":"Matrix Documentation (including The Spec)","fork":false,"url":"https://api.github.com/repos/matrix-org/matrix-doc","forks_url":"https://api.github.com/repos/matrix-org/matrix-doc/forks","keys_url":"https://api.github.com/repos/matrix-org/matrix-doc/keys{/key_id}","collaborators_url":"https://api.github.com/repos/matrix-org/matrix-doc/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/matrix-org/matrix-doc/teams","hooks_url":"https://api.github.com/repos/matrix-org/matrix-doc/hooks","issue_events_url":"https://api.github.com/repos/matrix-org/matrix-doc/issues/events{/number}","events_url":"https://api.github.com/repos/matrix-org/matrix-doc/events","assignees_url":"https://api.github.com/repos/matrix-org/matrix-doc/assignees{/user}","branches_url":"https://api.github.com/repos/matrix-org/matrix-doc/branches{/branch}","tags_url":"https://api.github.com/repos/matrix-org/matrix-doc/tags","blobs_url":"https://api.github.com/repos/matrix-org/matrix-doc/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/matrix-org/matrix-doc/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/matrix-org/matrix-doc/git/refs{/sha}","trees_url":"https://api.github.com/repos/matrix-org/matrix-doc/git/trees{/sha}","statuses_url":"https://api.github.com/repos/matrix-org/matrix-doc/statuses/{sha}","languages_url":"https://api.github.com/repos/matrix-org/matrix-doc/languages","stargazers_url":"https://api.github.com/repos/matrix-org/matrix-doc/stargazers","contributors_url":"https://api.github.com/repos/matrix-org/matrix-doc/contributors","subscribers_url":"https://api.github.com/repos/matrix-org/matrix-doc/subscribers","subscription_url":"https://api.github.com/repos/matrix-org/matrix-doc/subscription","commits_url":"https://api.github.com/repos/matrix-org/matrix-doc/commits{/sha}","git_commits_url":"https://api.github.com/repos/matrix-org/matrix-doc/git/commits{/sha}","comments_url":"https://api.github.com/repos/matrix-org/matrix-doc/comments{/number}","issue_comment_url":"https://api.github.com/repos/matrix-org/matrix-doc/issues/comments{/number}","contents_url":"https://api.github.com/repos/matrix-org/matrix-doc/contents/{+path}","compare_url":"https://api.github.com/repos/matrix-org/matrix-doc/compare/{base}...{head}","merges_url":"https://api.github.com/repos/matrix-org/matrix-doc/merges","archive_url":"https://api.github.com/repos/matrix-org/matrix-doc/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/matrix-org/matrix-doc/downloads","issues_url":"https://api.github.com/repos/matrix-org/matrix-doc/issues{/number}","pulls_url":"https://api.github.com/repos/matrix-org/matrix-doc/pulls{/number}","milestones_url":"https://api.github.com/repos/matrix-org/matrix-doc/milestones{/number}","notifications_url":"https://api.github.com/repos/matrix-org/matrix-doc/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/matrix-org/matrix-doc/labels{/name}","releases_url":"https://api.github.com/repos/matrix-org/matrix-doc/releases{/id}","created_at":"2014-10-09T16:41:02Z","updated_at":"2015-08-31T11:12:35Z","pushed_at":"2015-10-12T09:04:17Z","git_url":"git://github.com/matrix-org/matrix-doc.git","ssh_url":"git@github.com:matrix-org/matrix-doc.git","clone_url":"https://github.com/matrix-org/matrix-doc.git","svn_url":"https://github.com/matrix-org/matrix-doc","homepage":null,"size":3688,"stargazers_count":19,"watchers_count":19,"language":"JavaScript","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":5,"mirror_url":null,"open_issues_count":11,"forks":5,"open_issues":11,"watchers":19,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/matrix-org/matrix-doc/pulls/85"},"html":{"href":"https://github.com/matrix-org/matrix-doc/pull/85"},"issue":{"href":"https://api.github.com/repos/matrix-org/matrix-doc/issues/85"},"comments":{"href":"https://api.github.com/repos/matrix-org/matrix-doc/issues/85/comments"},"review_comments":{"href":"https://api.github.com/repos/matrix-org/matrix-doc/pulls/85/comments"},"review_comment":{"href":"https://api.github.com/repos/matrix-org/matrix-doc/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/matrix-org/matrix-doc/pulls/85/commits"},"statuses":{"href":"https://api.github.com/repos/matrix-org/matrix-doc/statuses/91ca36509b3112a83680a97a0d672a428b4d7fef"}}}}