diff --git a/api/client-server/v1/sync.yaml b/api/client-server/v1/sync.yaml index 973ccc6e..58cd5544 100644 --- a/api/client-server/v1/sync.yaml +++ b/api/client-server/v1/sync.yaml @@ -131,6 +131,14 @@ paths: "type": "m.presence" } ], + "account_data": [ + { + "type": "org.example.custom.config", + "content": { + "custom_config_key": "custom_config_value" + } + } + ], "rooms": [ { "membership": "join", @@ -246,10 +254,18 @@ paths: } ], "visibility": "private", - "account_data": [{ - "type": "m.tag", - "content": {"tags": {"work": {"order": "1"}}} - }] + "account_data": [ + { + "type": "m.tag", + "content": {"tags": {"work": {"order": 1}}} + }, + { + "type": "org.example.custom.room.config", + "content": { + "custom_config_key": "custom_config_value" + } + } + ] } ] } diff --git a/api/client-server/v2_alpha/account-data.yaml b/api/client-server/v2_alpha/account-data.yaml new file mode 100644 index 00000000..b634dddc --- /dev/null +++ b/api/client-server/v2_alpha/account-data.yaml @@ -0,0 +1,105 @@ +swagger: '2.0' +info: + title: "Matrix Client-Server Client Config API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/v2_alpha +consumes: + - application/json +produces: + - application/json +securityDefinitions: + accessToken: + type: apiKey + description: The user_id or application service access_token + name: access_token + in: query +paths: + "/user/{userId}/account_data/{type}": + put: + summary: Set some account_data for the user. + description: |- + Set some account_data for the client. This config is only visible to the user + that set the account_data. The config will be synced to clients in the + top-level ``account_data``. + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + required: true + description: |- + The id of the user to set account_data for. The access token must be + authorized to make requests for this user id. + x-example: "@alice:example.com" + - in: path + type: string + name: type + required: true + description: |- + The event type of the account_data to set. Custom types should be + namespaced to avoid clashes. + x-example: "org.example.custom.config" + - in: body + name: content + required: true + description: |- + The content of the account_data + schema: + type: object + example: |- + {"custom_account_data_key": "custom_config_value"} + responses: + 200: + description: + The account_data was successfully added. + "/user/{userId}/rooms/{roomId}/account_data/{type}": + put: + summary: Set some account_data for the user. + description: |- + Set some account_data for the client on a given room. This config is only + visible to the user that set the account_data. The config will be synced to + clients in the per-room ``account_data``. + security: + - accessToken: [] + parameters: + - in: path + type: string + name: userId + required: true + description: |- + The id of the user to set account_data for. The access token must be + authorized to make requests for this user id. + x-example: "@alice:example.com" + - in: path + type: string + name: roomId + required: true + description: |- + The id of the room to set account_data on. + x-example: "!726s6s6q:example.com" + - in: path + type: string + name: type + required: true + description: |- + The event type of the account_data to set. Custom types should be + namespaced to avoid clashes. + x-example: "org.example.custom.room.config" + - in: body + name: content + required: true + description: |- + The content of the account_data + schema: + type: object + example: |- + {"custom_account_data_key": "custom_account_data_value"} + responses: + 200: + description: + The account_data was successfully added. diff --git a/api/client-server/v2_alpha/sync.yaml b/api/client-server/v2_alpha/sync.yaml index 6f2f1412..675eda5d 100644 --- a/api/client-server/v2_alpha/sync.yaml +++ b/api/client-server/v2_alpha/sync.yaml @@ -211,6 +211,16 @@ paths: } ] }, + "account_data": { + "events": [ + { + "type": "org.example.custom.config", + "content": { + "custom_config_key": "custom_config_value" + } + } + ] + }, "rooms": { "join": { "!726s6s6q:example.com": { @@ -265,7 +275,13 @@ paths: "events": [ { "type": "m.tag", - "content": {"tags": {"work": {"order": "1"}}} + "content": {"tags": {"work": {"order": 1}}} + }, + { + "type": "org.example.custom.room.config", + "content": { + "custom_config_key": "custom_config_value" + } } ] } diff --git a/specification/modules/account_data.rst b/specification/modules/account_data.rst new file mode 100644 index 00000000..784bc874 --- /dev/null +++ b/specification/modules/account_data.rst @@ -0,0 +1,27 @@ +Client Config +============= + +.. _module:account_data: + +Clients can store custom config data for their account on their homeserver. +This account data will be synced between different devices and can persist +across installations on a particular device. Users may only view the account +data for their own account + +The account_data may be either global or scoped to a particular rooms. + +Events +------ + +The client recieves the account data as events in the ``account_data`` sections +of a v2 /sync. + +These events can also be received in a v1 /events response or in the +``account_data`` section of a room in v1 /initialSync. ``m.tag`` +events appearing in v1 /events will have a ``room_id`` with the room +the tags are for. + +Client Behaviour +---------------- + +{{v2_account_data_http_api}} diff --git a/specification/targets.yaml b/specification/targets.yaml index caae953f..afb7f8d9 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -27,6 +27,7 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/search.rst - modules/guest_access.rst - modules/tags.rst + - modules/account_data.rst title_styles: ["=", "-", "~", "+", "^", "`"]