From fcaa299f8111137ce932ea971ad801b37bce1dc6 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Wed, 25 Jul 2018 11:58:13 -0600
Subject: [PATCH] Include information on how invite_room_state works

This is completely optional, and the events included are up to the sender.

Sources:
* Structure: https://github.com/matrix-org/synapse/blob/d69decd5c78c72abef50b597a689e2bc55a39702/synapse/handlers/message.py#L896-L904
* What events are recommended: https://github.com/matrix-org/synapse/blob/d69decd5c78c72abef50b597a689e2bc55a39702/synapse/config/api.py#L30-L40
---
 api/server-server/invites.yaml | 88 +++++++++++++++++++++++++++++++++-
 1 file changed, 87 insertions(+), 1 deletion(-)

diff --git a/api/server-server/invites.yaml b/api/server-server/invites.yaml
index 4a0a610e..d1838bf5 100644
--- a/api/server-server/invites.yaml
+++ b/api/server-server/invites.yaml
@@ -49,11 +49,77 @@ paths:
           type: object
           required: true
           schema:
-            $ref: "definitions/invite_event.yaml"
+            allOf:
+              - $ref: "definitions/invite_event.yaml"
+              - type: object
+                properties:
+                  unsigned:
+                    type: object
+                    title: Unsigned Event Content
+                    description: |-
+                      Information included alongside the event that is not signed. May include more
+                      than what is listed here.
+                    properties:
+                      invite_room_state:
+                        type: array
+                        description: |-
+                          An optional list of simplified events to help the receiver of the invite
+                          identify the room. The recommended events to include are the join rules,
+                          canonical alias, avatar, and name of the room.
+                        items:
+                          type: object
+                          title: Invite Room State Event
+                          properties:
+                            type:
+                              type: string
+                              description: The type of event.
+                              example: "m.room.join_rules"
+                            state_key:
+                              type: string
+                              description: The state key for the event. May be an empty string.
+                              example: ""
+                            content:
+                              type: object
+                              description: The content for the event.
+                            sender:
+                              type: string
+                              description: The sender of the event.
+                              example: "@someone:matrix.org"
+                          required: ['type', 'state_key', 'content', 'sender']
+                        example: [
+                          {
+                            "type": "m.room.join_rules",
+                            "sender": "@someone:matrix.org",
+                            "state_key": "",
+                            "content": {
+                              "join_rule": "public"
+                            }
+                          }
+                        ]
           example: {
             "$ref": "examples/pdu.json",
             "type": "m.room.member",
             "state_key": "@joe:elsewhere.com",
+            "unsigned": {
+              "invite_room_state": [
+                {
+                  "type": "m.room.join_rules",
+                  "sender": "@someone:matrix.org",
+                  "state_key": "",
+                  "content": {
+                    "join_rule": "public"
+                  }
+                },
+                {
+                  "type": "m.room.name",
+                  "sender": "@someone:matrix.org",
+                  "state_key": "",
+                  "content": {
+                    "name": "Cool New Room"
+                  }
+                }
+              ]
+            },
             "content": {
                 "membership": "invite"
             },
@@ -91,6 +157,26 @@ paths:
                   "$ref": "examples/pdu.json",
                   "type": "m.room.member",
                   "state_key": "@someone:example.org",
+                  "unsigned": {
+                    "invite_room_state": [
+                      {
+                        "type": "m.room.join_rules",
+                        "sender": "@someone:matrix.org",
+                        "state_key": "",
+                        "content": {
+                          "join_rule": "public"
+                        }
+                      },
+                      {
+                        "type": "m.room.name",
+                        "sender": "@someone:matrix.org",
+                        "state_key": "",
+                        "content": {
+                          "name": "Cool New Room"
+                        }
+                      }
+                    ]
+                  },
                   "content": {
                       "membership": "invite"
                   },