From 0a07d688184cd0658cd03c25c747706ef4098434 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 28 Jan 2015 18:20:28 +0000 Subject: [PATCH 01/24] Add overview on push. --- drafts/push_overview.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 drafts/push_overview.rst diff --git a/drafts/push_overview.rst b/drafts/push_overview.rst new file mode 100644 index 00000000..6cee68c5 --- /dev/null +++ b/drafts/push_overview.rst @@ -0,0 +1,31 @@ +Push Notifications +================== + +Matrix supports push notifications as a first class citizen. Home Servers send +notifications of user events to user-configured HTTP endpoints. User may also +configure a number of rules that determine what events generate notifications. +These are all stored and managed by the users home server such that settings can +be reused between client apps as appropriate. + +Nomenclature +------------ + +Pusher + A 'pusher' is an activity in the Home Server that manages the sending + of HTTP notifications for a single device of a single user. + +Push Rules + A push rule is a single rule, configured by a matrix user, that gives + instructions to the Home Server about whether an event should be notified + about and how given a set of conditions. Matrix clients allow the user to + configure these. They create and view them via the Client to Server REST API. + +Push Gateway + A push gateway is a server that receives HTTP event notifications from Home + Servers and passes them on to a different protocol such as APNS for iOS + devices or GCM for Android devices. Matrix.org provides a reference push + gateway, 'sygnal'. + +For information on the client-server API for setting pushers and push rules, see +the Client Server API section. For more information on the format of HTTP +notifications, see the HTTP Notification Protocol section. From c27fb8a2620ed952bde6c0032ed25daacab913e3 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 2 Feb 2015 13:49:18 +0000 Subject: [PATCH 02/24] Add WIP docs for the client-server bit of push. --- drafts/push_csapi.rst | 52 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 drafts/push_csapi.rst diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst new file mode 100644 index 00000000..bc960fe4 --- /dev/null +++ b/drafts/push_csapi.rst @@ -0,0 +1,52 @@ +Push Notifications +================== + +Pushers +------- +To receive any notification pokes at all, it is necessary to configure a +'pusher' on the Home Server that you wish to receive notifications from. There +is a single API endpoint for this:: + +Fetching a user account displayname:: + + POST $PREFIX/pushers/set + +This takes a JSON object with the following keys: + +pushkey + This is a unique identifier for this pusher. The value you should use for this + is the routing or destination address information for the notification, for + example, the APNS token for APNS or the Registration ID for GCM. If your + notification client has no such concept, use any unique identifier. +kind + The kind of pusher to configure. 'http' makes a pusher that sends HTTP pokes. + null deletes the pusher. +instance_handle + This is an identifier for the device which owns the pusher. It may be up to 32 + characters long. It must be unique among all the pushers for a given user + (therefore the device ID may not be used). It is advised that when an app's + data is copied or restored to a different device, this ID remain the same (ie. + be shared by multiple pushers for multiple devices). Client apps should be + aware that this situation can occur and be able to rectify it (eg. by + offerring to reset the instance_hanlde, optionally duplicating all push rules + to new instance handle). +app_id + appId is a reverse-DNS style identifier for the application. It is recommended + that this end with the platform, such that different platform versions get + different app identifiers. Max length, 64 chars. +app_display_name + A string that will allow the user to identify what application owns this + pusher. +device_display_name + A string that will allow the user to identify what device owns this pusher. +lang + The preferred language for receiving notifications (eg, 'en' or 'en-US') +data + A dictionary of information for the pusher implementation itself. For HTTP + pushers, this must contain a 'url' key which is a string of the URL that + should be used to send notifications. + +If the pusher was created successfully, an empty JSON dictionary is returned. + + + From f68fa8d6f887cc58e591cc06c708548b6c2636a7 Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 2 Feb 2015 15:14:45 +0000 Subject: [PATCH 03/24] Push rules c/s spec. --- drafts/push_csapi.rst | 105 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index bc960fe4..89212576 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -49,4 +49,109 @@ data If the pusher was created successfully, an empty JSON dictionary is returned. +Push Rules +---------- +Home Servers have an interface to configure what events trigger notifications. +This behaviour is configured through 'Push Rules'. Push Rules come in a variety +of different kinds and each kind of rule has an associated priority. The +different kinds of rule, in descending order of priority, are: + +Override Rules + The highest priority rules are user-configured overrides. +Content Rules + These configure behaviour for (unencrypted) messages that match certain + patterns. +Room Rules + These change the behaviour of all messages to a given room. The rule_id of a + room rule is always the room that it affects. +Sender + These rules configure notification behaviour for messages from a specific, + named Matrix user ID. The rule_id of Sender rules is always the Matrix user + ID of the user whose messages theyt apply to. +Underride + These are identical to override rules, but have a lower priority than content, + room and sender rules. +Default + These are rules provided by the home server and cannot be changed by the user. + They are the lowest priority rule and establish baseline behaviour. + +In addition, each kind of rule except default may be either global or +device-specific. Device specific rules only affect delivery of notifications via +pushers with a matching instance_handle. All device-specific rules are higher +priority than all global rules. Thusly, the full list of rule kinds, in +descending priority order, is as follows: + + * Device-specific Override + * Device-specific Content + * Device-specific Room + * Device-specific Sender + * Device-specific Underride + * Global Override + * Global Content + * Global Room + * Global Sender + * Global Underride + * Global Default + +For some kinds of rule, rules of the same kind also have an ordering with +respect to one another. The kinds that do not are room and sender rules where +the rules are mutually exclusive by definition and therefore an ordering would +be redundant. Actions for the highest priority rule and only that rule apply +(for example, a set_sound action in a lower priority rule will not apply if a +higher priority rule matches, even if that rule does not specify a sound). + +Push Rules: Actions: +-------------------- +All rules have an associated list of 'actions'. An action affects if and how a +notification is delievered for a matching event. This standard defines the +following actions, although if Home servers wish to support more, they are free +to do so: + +notify + This causes each matching event to generate a notification. +dont_notify + Prevents this event from generating a notification +coalesce + This enables notifications for matching events but activates Home Server + specific behaviour to intelligently coalesce multiple events into a single + notification. Not all Home Servers may support this. Those that do not should + treat it as the 'notify' action. +set_sound + Sets the value 'sound' key that is sent in the notification poke. This has an + associated string which is the value to set the 'sound' key to. + +Actions that have no parameter are represented as a string. Those with a +parameter are represented as a dictionary with a single key/value pair where the +key is the name of the action and the value is the parameter, eg. { "set_sound": +"ping.wav" } + +Push Rules: Conditions: +----------------------- +Override, Underride and Default rules have a list of 'conditions'. All +conditions must hold true for an event in order for a rule to be applied to an +event. Matrix specifies the following conditions, although if Home Servers wish +to support others, they are free to do so: + +event_match + This is a glob pattern match on a field of the event. Parameters: + * 'key': The dot-separated field of the event to match, eg. content.body + * 'pattern': The glob-style pattern to match against. Patterns with no + special glob characters should be treated as having asterisks + prepended and appended when testing the condition. +device + Matches the instance_handle of the device that the notification would be + delivered to. Parameters: + * 'instance_handle': The instance_handle of the device. +contains_display_name + This matches unencrypted messages where content.body contains the owner's + display name in that room. This is a separate rule because display names may + change and as such it would be hard to maintain a rule that matched the user's + display name. This condition has no parameters. +room_member_count + This matches the current number of members in the room. + * 'is': A decimal integer optionally prefixed by one of, '==', '<', '>', + '>=' or '<='. A prefix of '<' matches rooms where the member count is + strictly less than the given number and so forth. If no prefix is present, + this matches rooms where the member count is exactly equal to the given + number (ie. the same as '=='). From b7a6e8f7b52c366cbcb6ed8577e0d12b6e99cf0d Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 2 Feb 2015 16:25:53 +0000 Subject: [PATCH 04/24] Finish non-API doc parts of push rules. --- drafts/push_csapi.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index 89212576..bd204389 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -60,7 +60,9 @@ Override Rules The highest priority rules are user-configured overrides. Content Rules These configure behaviour for (unencrypted) messages that match certain - patterns. + patterns. Content rules take one parameter, 'pattern', that gives the pattern + to match against. This is treated in the same way as pattern for event_match + conditions, below. Room Rules These change the behaviour of all messages to a given room. The rule_id of a room rule is always the room that it affects. @@ -100,6 +102,8 @@ be redundant. Actions for the highest priority rule and only that rule apply (for example, a set_sound action in a lower priority rule will not apply if a higher priority rule matches, even if that rule does not specify a sound). +Rules also have an identifier, rule_id, which is a string. + Push Rules: Actions: -------------------- All rules have an associated list of 'actions'. An action affects if and how a @@ -155,3 +159,8 @@ room_member_count this matches rooms where the member count is exactly equal to the given number (ie. the same as '=='). +Room, Sender, User and Content rules do not have conditions in the same way, +but instead have predefined conditions, the behaviour of which can be configured +using parameters named as described above. In the cases of room and sender +rules, the rule_id of the rule determines its behaviour. + From 0c79798f708334c19097f873d24e37e46d75b6da Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 2 Feb 2015 17:10:09 +0000 Subject: [PATCH 05/24] More WIP API docs and remove spurious line. --- drafts/push_csapi.rst | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index bd204389..1c99a859 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -7,8 +7,6 @@ To receive any notification pokes at all, it is necessary to configure a 'pusher' on the Home Server that you wish to receive notifications from. There is a single API endpoint for this:: -Fetching a user account displayname:: - POST $PREFIX/pushers/set This takes a JSON object with the following keys: @@ -164,3 +162,20 @@ but instead have predefined conditions, the behaviour of which can be configured using parameters named as described above. In the cases of room and sender rules, the rule_id of the rule determines its behaviour. +Push Rules: API +--------------- +Rules live under a hierarchy in the REST API that resembles:: + + $PREFIX/pushrules/// + +To add or change a rule, a client performs a PUT request to the appropriate URL. +When adding rules of a type that has an ordering, the client can add parameters +that define the priority of the rule: + +before + Use 'before' with a rule_id as its value to make the new rule the next-less + important rule with respect to the given rule. +after + This makes the new rule the next-most important rule relative to the given + rule. + From 88178e376e6b352dedfe6b98b05c034e3158c94a Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 2 Feb 2015 17:26:58 +0000 Subject: [PATCH 06/24] Oops, before is *more* important. --- drafts/push_csapi.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index 1c99a859..115b9216 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -173,9 +173,8 @@ When adding rules of a type that has an ordering, the client can add parameters that define the priority of the rule: before - Use 'before' with a rule_id as its value to make the new rule the next-less + Use 'before' with a rule_id as its value to make the new rule the next-more important rule with respect to the given rule. after - This makes the new rule the next-most important rule relative to the given + This makes the new rule the next-less important rule relative to the given rule. - From c40b97aaf5089140ab29a53529dc9f67b63e820e Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 2 Feb 2015 18:16:36 +0000 Subject: [PATCH 07/24] Rule adding API with examples --- drafts/push_csapi.rst | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index 115b9216..3c6edac6 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -168,6 +168,17 @@ Rules live under a hierarchy in the REST API that resembles:: $PREFIX/pushrules/// +The component parts are as follows: + +scope + Either 'global' or 'device/' to specify global rules or + device rules for the given instance_handle. +kind + The kind of rule, ie. 'override', 'underride', 'sender', 'room', 'content' or + 'default'. +rule_id + The identifier for the rule. + To add or change a rule, a client performs a PUT request to the appropriate URL. When adding rules of a type that has an ordering, the client can add parameters that define the priority of the rule: @@ -178,3 +189,33 @@ before after This makes the new rule the next-less important rule relative to the given rule. + +All requests to the push rules API also require an access_token as a query +paraemter. + +The content of the PUT request is a JSON object with a list of actions under the +'actions' key and either conditions (under the 'conditions' key) or the +appropriate parameters for the rule (under the appropriate key name). + +Examples: + +To create a rule that suppresses notifications for the room '#spam:matrix.org':: + + curl -X PUT -H "Content-Type: application/json" -d '{ "actions" : ["dont_notify"] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/room/%23spam%3Amatrix.org?access_token=123456" + +To suppress notifications for the user '@spambot:matrix.org':: + + curl -X PUT -H "Content-Type: application/json" -d '{ "actions" : ["dont_notify"] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/sender/room/%40spambot%3Amatrix.org?access_token=123456" + +To always notify for messages that contain the work 'cake' and set a specific sound (with a rule_id of 'SSByZWFsbHkgbGlrZSBjYWtl'):: + + curl -X PUT -H "Content-Type: application/json" -d '{ "pattern": "cake", "actions" : ["notify", {"set_sound":"cakealarm.wav"}] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/sender/content/SSByZWFsbHkgbGlrZSBjYWtl?access_token=123456" + +To add a rule suppressing notifications for messages starting with 'cake' but ending with 'lie', superseeding the previous rule:: + + curl -X PUT -H "Content-Type: application/json" -d '{ "pattern": "cake*lie", "actions" : ["notify"] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/sender/content/U3BvbmdlIGNha2UgaXMgYmVzdA?access_token=123456&before=SSByZWFsbHkgbGlrZSBjYWtl" + +To add a custom sound for notifications messages containing the word 'beer' in any rooms with 10 members or fewer (with greater importance than the room, sender and content rules):: + + curl -X PUT -H "Content-Type: application/json" -d '{ "conditions": [{"kind": "event_match", "key": "content.body", "pattern": "beer" }, {"kind": "room_member_count", "is": "<=10"}], "actions" : ["notify", {"set_sound":"beeroclock.wav"}] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/override/U2VlIHlvdSBpbiBUaGUgRHVrZQ?access_token=123456 + From 1a5678786fb34d35110d44ca5a5aefd53509f34a Mon Sep 17 00:00:00 2001 From: David Baker Date: Mon, 2 Feb 2015 18:36:04 +0000 Subject: [PATCH 08/24] Doc deleting & getting rules. --- drafts/push_csapi.rst | 98 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index 3c6edac6..0a3294d4 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -219,3 +219,101 @@ To add a custom sound for notifications messages containing the word 'beer' in a curl -X PUT -H "Content-Type: application/json" -d '{ "conditions": [{"kind": "event_match", "key": "content.body", "pattern": "beer" }, {"kind": "room_member_count", "is": "<=10"}], "actions" : ["notify", {"set_sound":"beeroclock.wav"}] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/override/U2VlIHlvdSBpbiBUaGUgRHVrZQ?access_token=123456 + +To delete rules, a client would just make a DELETE request to the same URL:: + + curl -X DELETE "http://localhost:8008/_matrix/client/api/v1/pushrules/global/room/%23spam%3Amatrix.org?access_token=123456" + + +Retrieving the current ruleset can be done either by fetching individual rules +using the scheme as specified above. This returns the rule in the same format as +would be given in the PUT API with the addition of a rule_id:: + + curl "http://localhost:8008/_matrix/client/api/v1/pushrules/global/room/%23spam%3Amatrix.org?access_token=123456" + +Returns:: + + { + "actions": [ + "dont_notify" + ], + "rule_id": "#spam:matrix.org" + } + +Clients can also fetch broader sets of rules by removing path components. +Requesting the root level returns a structure as follows:: + + { + "device": { + "exampledevice": { + "content": [], + "default": [], + "override": [], + "room": [ + { + "actions": [ + "dont_notify" + ], + "rule_id": "#spam:matrix.org" + } + ], + "sender": [], + "underride": [] + } + }, + "global": { + "content": [], + "default": [ + { + "actions": [ + "notify", + { + "set_sound": "default" + } + ], + "conditions": [ + { + "key": "content.body", + "kind": "event_match", + "pattern": "*@test:steve*" + } + ] + }, + { + "actions": [ + "notify", + { + "set_sound": "default" + } + ], + "conditions": [ + { + "kind": "contains_display_name" + } + ] + }, + { + "actions": [ + "notify", + { + "set_sound": "default" + } + ], + "conditions": [ + { + "is": "2", + "kind": "room_member_count" + } + ] + } + ], + "override": [], + "room": [], + "sender": [], + "underride": [] + } + } + +Adding patch components to the request drills down into this structure to filter +to only the requested set of rules. + From 067e4bb7771282a71567bc60fc28b99dc75ad5e9 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 3 Feb 2015 14:21:56 +0000 Subject: [PATCH 09/24] Add docs for http notification poke protocol. --- drafts/push_overview.rst | 3 +- drafts/push_pgwapi.rst | 128 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 130 insertions(+), 1 deletion(-) create mode 100644 drafts/push_pgwapi.rst diff --git a/drafts/push_overview.rst b/drafts/push_overview.rst index 6cee68c5..216ebdcd 100644 --- a/drafts/push_overview.rst +++ b/drafts/push_overview.rst @@ -24,7 +24,8 @@ Push Gateway A push gateway is a server that receives HTTP event notifications from Home Servers and passes them on to a different protocol such as APNS for iOS devices or GCM for Android devices. Matrix.org provides a reference push - gateway, 'sygnal'. + gateway, 'sygnal'. A client app tells a Home Server what push gateway + to send notifications to when it sets up a pusher. For information on the client-server API for setting pushers and push rules, see the Client Server API section. For more information on the format of HTTP diff --git a/drafts/push_pgwapi.rst b/drafts/push_pgwapi.rst new file mode 100644 index 00000000..bf0a4c37 --- /dev/null +++ b/drafts/push_pgwapi.rst @@ -0,0 +1,128 @@ +Push Notifications: HTTP Notification Protocol +============================================== +This describes the format used by "http" pushers to send notifications of +events. + +Notifications are sent as HTTP POST requests to the URL configured when the +pusher is created. The body of the POST request is a JSON dictionary. The format +is as follows:: + + { + "notification": { + "id": "$3957tyerfgewrf384", + "type": "m.room.message", + "sender": "@exampleuser:matrix.org", + "sender_display_name": "Major Tom", + "room_name": "Mission Control", + "room_alias": "#exampleroom:matrix.org", + "prio": "high", + "content": { + "msgtype": "m.text", + "body": "I'm floating in a most peculiar way." + } + }, + "counts": { + "unread" : 2, + "missed_calls": 1 + } + "devices": [ + { + "app_id": "org.matrix.matrixConsole.ios", + "pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/", + "pushkey_ts": 12345678, + "data" : { + }, + "tweaks": { + "sound": "bing.wav" + } + } + ] + } + } + +The contents of this dictionary are defined as follows: + +id + An identifier for this notification that may be used to detect duplicate + notification requests. This is not necessarily the ID of the event that + triggered the notification. +type + The type of the event as in the event's 'type' field. +sender + The sender of the event as in the corresponding event field. +sender_display_name + The current display name of the sender in the room in which the event + occurred. +room_name + The name of the room in which the event occurred. +room_alias + An alias to display for the room in which the event occurred. +prio + The priority of the notification. Acceptable values are 'high' or 'low. If + omitted, 'high' is assumed. This may be used by push gateways to deliver less + time-sensitive notifications in a way that will preserve battery power on + mobile devices. +content + The 'content' field from the event, if present. If the event had no content + field, this field is omitted. +counts + This is a dictionary of the current number of unacknowledged communications + for the recipient user. Counts whose value is zero are omitted. +unread + The number of unread messages a user has accross all of the rooms they are a + member of. +missed_calls + The number of unacknowledged missed calls a user has accross all rooms of + which they are a member. +device + This is an array of devices that the notification should be sent to. +app_id + The app_id given when the pusher was created. +pushkey + The pushkey given when the pusher was created. +pushkey_ts + The unix timestamp (in seconds) when the pushkey was last updated. +data + A dictionary of additional pusher-specific data. For 'http' pushers, this is + the data dictionary passed in at pusher creation minus the 'url' key. +tweaks + A dictionary of customisations made to the way this notification is to be + presented. These are added by push rules. +sound + Sets the sound file that should be played. 'default' means that a default + sound should be played. + +The recipient of an HTTP notification should respond with an HTTP 2xx response +when the notification has been processed. If the endpoint returns an HTTP error +code, the Home Server should retry for a reasonable amount of time with a +reasonable backoff scheme. + +The endpoint should return a JSON dictionary as follows:: + + { + "rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ] + } + +Whose keys are: + +rejected + A list of all pushkeys given in the notification request that are not valid. + These could have been rejected by an upstream gateway because they have + expired or have never been valid. Home Servers must cease sending notification + requests for these pushkeys and remove the associated pushers. It may not + necessarily be the notification in the request that failed: it could be that + a previous notification to the same pushkey failed. + +Push: Recommendations for APNS +------------------------------ +For sending APNS notifications, the exact format is flexible and up to the +client app and its push gateway to agree on (since APNS requires that the sender +have a private key owned by the app developer, each app must have its own push +gateway). However, Matrix strongly recommends: + + * That the APNS token be base64 encoded and used as the pushkey. + * That a different app_id be used for apps on the production and sandbox + APS environments. + * That PANS push gateways do not attempt to wait for errors from the APNS + gateway before returning and instead to store failures and return + 'rejected' responses next time that pushkey is used. From 8920d58cc43a6767c042a635ac6109713ce788ac Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 3 Feb 2015 14:35:01 +0000 Subject: [PATCH 10/24] Strongly recommend standard URI scheme for notification pokes. --- drafts/push_pgwapi.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/drafts/push_pgwapi.rst b/drafts/push_pgwapi.rst index bf0a4c37..8dd054f6 100644 --- a/drafts/push_pgwapi.rst +++ b/drafts/push_pgwapi.rst @@ -4,7 +4,11 @@ This describes the format used by "http" pushers to send notifications of events. Notifications are sent as HTTP POST requests to the URL configured when the -pusher is created. The body of the POST request is a JSON dictionary. The format +pusher is created, but Matrix strongly recommends that the path should be:: + + /_matrix/push/v1/notify + +The body of the POST request is a JSON dictionary. The format is as follows:: { From 91d12dc9553995fd5dc8907cfaed7b842755c6b5 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 3 Feb 2015 15:38:12 +0000 Subject: [PATCH 11/24] Replace set_sound with more generic set_tweaks. --- drafts/push_csapi.rst | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index 0a3294d4..b979331f 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -97,8 +97,8 @@ For some kinds of rule, rules of the same kind also have an ordering with respect to one another. The kinds that do not are room and sender rules where the rules are mutually exclusive by definition and therefore an ordering would be redundant. Actions for the highest priority rule and only that rule apply -(for example, a set_sound action in a lower priority rule will not apply if a -higher priority rule matches, even if that rule does not specify a sound). +(for example, a set_tweak action in a lower priority rule will not apply if a +higher priority rule matches, even if that rule does not specify any tweaks). Rules also have an identifier, rule_id, which is a string. @@ -118,14 +118,28 @@ coalesce specific behaviour to intelligently coalesce multiple events into a single notification. Not all Home Servers may support this. Those that do not should treat it as the 'notify' action. -set_sound - Sets the value 'sound' key that is sent in the notification poke. This has an - associated string which is the value to set the 'sound' key to. - -Actions that have no parameter are represented as a string. Those with a -parameter are represented as a dictionary with a single key/value pair where the -key is the name of the action and the value is the parameter, eg. { "set_sound": -"ping.wav" } +set_tweak + Sets an entry in the 'tweaks' dictionary key that is sent in the notification + poke. This takes the form of a dictionary with a 'set_tweak' key whose value + is the name of the tweak to set. It must also have a 'value' key which is + the value to which it should be set. + +Actions that have no parameters are represented as a string. Otherwise, they are +represented as a dictionary with a key equal to their name and other keys as +their parameters, eg. { "set_tweak": "sound", "value": "default" } + +Push Rule Actions: Tweaks +------------------------- +The 'set_tweak' key action is used to add an entry to the 'tweaks' dictionary +that is sent in the notification poke. The following tweaks are e defined: + +sound + A sound to be played when this notification arrives. 'default' means to + play a default sound. + +Tweaks are passed transparently through the Home Server so client applications +and push gateways may agree on additional tweaks, for example, how to flash the +notification light on a mobile device. Push Rules: Conditions: ----------------------- From f24e951b024c206aa9fa4caee77576d6a1ed12ac Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 3 Feb 2015 16:21:09 +0000 Subject: [PATCH 12/24] s/instance_handle/profile_tag/ --- drafts/push_csapi.rst | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index b979331f..8e1fd99c 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -19,15 +19,13 @@ pushkey kind The kind of pusher to configure. 'http' makes a pusher that sends HTTP pokes. null deletes the pusher. -instance_handle - This is an identifier for the device which owns the pusher. It may be up to 32 - characters long. It must be unique among all the pushers for a given user - (therefore the device ID may not be used). It is advised that when an app's - data is copied or restored to a different device, this ID remain the same (ie. - be shared by multiple pushers for multiple devices). Client apps should be - aware that this situation can occur and be able to rectify it (eg. by - offerring to reset the instance_hanlde, optionally duplicating all push rules - to new instance handle). +profile_tag + This is a string that determines what set of device rules will be matched when + evaluating push rules for this pusher. It is an arbitrary string. Multiple + devices maybe use the same profile_tag. It is advised that when an app's + data is copied or restored to a different device, this value remain the same. + Client apps should offer ways to change the profile_tag, optionally copying + rules from the old profile tag. app_id appId is a reverse-DNS style identifier for the application. It is recommended that this end with the platform, such that different platform versions get @@ -77,7 +75,7 @@ Default In addition, each kind of rule except default may be either global or device-specific. Device specific rules only affect delivery of notifications via -pushers with a matching instance_handle. All device-specific rules are higher +pushers with a matching profile_tag. All device-specific rules are higher priority than all global rules. Thusly, the full list of rule kinds, in descending priority order, is as follows: @@ -154,10 +152,10 @@ event_match * 'pattern': The glob-style pattern to match against. Patterns with no special glob characters should be treated as having asterisks prepended and appended when testing the condition. -device - Matches the instance_handle of the device that the notification would be +profile_tag + Matches the profile_tag of the device that the notification would be delivered to. Parameters: - * 'instance_handle': The instance_handle of the device. + * 'profile_tag': The profile_tag to match with. contains_display_name This matches unencrypted messages where content.body contains the owner's display name in that room. This is a separate rule because display names may @@ -185,8 +183,8 @@ Rules live under a hierarchy in the REST API that resembles:: The component parts are as follows: scope - Either 'global' or 'device/' to specify global rules or - device rules for the given instance_handle. + Either 'global' or 'device/' to specify global rules or + device rules for the given profile_tag. kind The kind of rule, ie. 'override', 'underride', 'sender', 'room', 'content' or 'default'. From dbbf9626b4e2d1c0549bae0daee8891553179fa2 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 4 Feb 2015 11:34:32 +0000 Subject: [PATCH 13/24] Fix various incorreect examples in the doc. --- drafts/push_csapi.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index 8e1fd99c..9016d0e2 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -61,7 +61,7 @@ Content Rules conditions, below. Room Rules These change the behaviour of all messages to a given room. The rule_id of a - room rule is always the room that it affects. + room rule is always the ID of the room that it affects. Sender These rules configure notification behaviour for messages from a specific, named Matrix user ID. The rule_id of Sender rules is always the Matrix user @@ -211,21 +211,21 @@ appropriate parameters for the rule (under the appropriate key name). Examples: -To create a rule that suppresses notifications for the room '#spam:matrix.org':: +To create a rule that suppresses notifications for the room with ID '!dj234r78wl45Gh4D:matrix.org':: - curl -X PUT -H "Content-Type: application/json" -d '{ "actions" : ["dont_notify"] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/room/%23spam%3Amatrix.org?access_token=123456" + curl -X PUT -H "Content-Type: application/json" -d '{ "actions" : ["dont_notify"] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456" To suppress notifications for the user '@spambot:matrix.org':: - curl -X PUT -H "Content-Type: application/json" -d '{ "actions" : ["dont_notify"] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/sender/room/%40spambot%3Amatrix.org?access_token=123456" + curl -X PUT -H "Content-Type: application/json" -d '{ "actions" : ["dont_notify"] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/sender/%40spambot%3Amatrix.org?access_token=123456" To always notify for messages that contain the work 'cake' and set a specific sound (with a rule_id of 'SSByZWFsbHkgbGlrZSBjYWtl'):: - curl -X PUT -H "Content-Type: application/json" -d '{ "pattern": "cake", "actions" : ["notify", {"set_sound":"cakealarm.wav"}] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/sender/content/SSByZWFsbHkgbGlrZSBjYWtl?access_token=123456" + curl -X PUT -H "Content-Type: application/json" -d '{ "pattern": "cake", "actions" : ["notify", {"set_sound":"cakealarm.wav"}] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/content/SSByZWFsbHkgbGlrZSBjYWtl?access_token=123456" To add a rule suppressing notifications for messages starting with 'cake' but ending with 'lie', superseeding the previous rule:: - curl -X PUT -H "Content-Type: application/json" -d '{ "pattern": "cake*lie", "actions" : ["notify"] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/sender/content/U3BvbmdlIGNha2UgaXMgYmVzdA?access_token=123456&before=SSByZWFsbHkgbGlrZSBjYWtl" + curl -X PUT -H "Content-Type: application/json" -d '{ "pattern": "cake*lie", "actions" : ["notify"] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/content/U3BvbmdlIGNha2UgaXMgYmVzdA?access_token=123456&before=SSByZWFsbHkgbGlrZSBjYWtl" To add a custom sound for notifications messages containing the word 'beer' in any rooms with 10 members or fewer (with greater importance than the room, sender and content rules):: From 8184855d5ad4dfe03957732b1b3d202c5cce8fdb Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 4 Feb 2015 16:30:57 +0000 Subject: [PATCH 14/24] add note about scope of rule_ids. --- drafts/push_csapi.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index 9016d0e2..e9abf326 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -98,7 +98,10 @@ be redundant. Actions for the highest priority rule and only that rule apply (for example, a set_tweak action in a lower priority rule will not apply if a higher priority rule matches, even if that rule does not specify any tweaks). -Rules also have an identifier, rule_id, which is a string. +Rules also have an identifier, rule_id, which is a string. The rule_id may +alphanumeric characters only. The rule_id is unique within the kind of rule and +scope: rule_ids need not be unique between rules of the same kind on different +devices. Push Rules: Actions: -------------------- From e6c9e77d350dbc5eceaf6c6a85f3b4dbc19e9a22 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 5 Feb 2015 10:49:48 +0000 Subject: [PATCH 15/24] Change server default rules. --- drafts/push_csapi.rst | 69 ++++++++----------------------------------- 1 file changed, 12 insertions(+), 57 deletions(-) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index e9abf326..ae9591bf 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -69,15 +69,12 @@ Sender Underride These are identical to override rules, but have a lower priority than content, room and sender rules. -Default - These are rules provided by the home server and cannot be changed by the user. - They are the lowest priority rule and establish baseline behaviour. -In addition, each kind of rule except default may be either global or -device-specific. Device specific rules only affect delivery of notifications via -pushers with a matching profile_tag. All device-specific rules are higher -priority than all global rules. Thusly, the full list of rule kinds, in -descending priority order, is as follows: +In addition, each kind of rule may be either global or device-specific. Device +specific rules only affect delivery of notifications via pushers with a matching +profile_tag. All device-specific rules are higher priority than all global +rules. Thusly, the full list of rule kinds, in descending priority order, is as +follows: * Device-specific Override * Device-specific Content @@ -89,7 +86,6 @@ descending priority order, is as follows: * Global Room * Global Sender * Global Underride - * Global Default For some kinds of rule, rules of the same kind also have an ordering with respect to one another. The kinds that do not are room and sender rules where @@ -101,7 +97,12 @@ higher priority rule matches, even if that rule does not specify any tweaks). Rules also have an identifier, rule_id, which is a string. The rule_id may alphanumeric characters only. The rule_id is unique within the kind of rule and scope: rule_ids need not be unique between rules of the same kind on different -devices. +devices. + +A home server may also have server default rules of each kind and in each scope. +Server default rules are lower priority than user-defined rules in eacgh scope. +Server defined rules do not have a rule_id. A rule has a rule_id if and only if +it is a user-defined rule. Push Rules: Actions: -------------------- @@ -189,8 +190,7 @@ scope Either 'global' or 'device/' to specify global rules or device rules for the given profile_tag. kind - The kind of rule, ie. 'override', 'underride', 'sender', 'room', 'content' or - 'default'. + The kind of rule, ie. 'override', 'underride', 'sender', 'room', 'content'. rule_id The identifier for the rule. @@ -262,7 +262,6 @@ Requesting the root level returns a structure as follows:: "device": { "exampledevice": { "content": [], - "default": [], "override": [], "room": [ { @@ -278,50 +277,6 @@ Requesting the root level returns a structure as follows:: }, "global": { "content": [], - "default": [ - { - "actions": [ - "notify", - { - "set_sound": "default" - } - ], - "conditions": [ - { - "key": "content.body", - "kind": "event_match", - "pattern": "*@test:steve*" - } - ] - }, - { - "actions": [ - "notify", - { - "set_sound": "default" - } - ], - "conditions": [ - { - "kind": "contains_display_name" - } - ] - }, - { - "actions": [ - "notify", - { - "set_sound": "default" - } - ], - "conditions": [ - { - "is": "2", - "kind": "room_member_count" - } - ] - } - ], "override": [], "room": [], "sender": [], From 94af47ffd4eb051282779df1ab6f54f906ae0489 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 5 Feb 2015 13:03:10 +0000 Subject: [PATCH 16/24] Server default riules will have a rule_id when you need it to work out what the rule does. --- drafts/push_csapi.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index ae9591bf..39645ae2 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -101,8 +101,8 @@ devices. A home server may also have server default rules of each kind and in each scope. Server default rules are lower priority than user-defined rules in eacgh scope. -Server defined rules do not have a rule_id. A rule has a rule_id if and only if -it is a user-defined rule. +Server defined rules do not have a rule_id except when it is necessary to derive +the function of the rule (ie. in room and sender rules). Push Rules: Actions: -------------------- From 8360be247b45236410423563298957323265bac7 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 5 Feb 2015 13:15:34 +0000 Subject: [PATCH 17/24] Leave out what characters are allowed in a rule ID as we allow most thigs in matrix usernames currently. --- drafts/push_csapi.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index 39645ae2..5f8515f1 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -94,10 +94,9 @@ be redundant. Actions for the highest priority rule and only that rule apply (for example, a set_tweak action in a lower priority rule will not apply if a higher priority rule matches, even if that rule does not specify any tweaks). -Rules also have an identifier, rule_id, which is a string. The rule_id may -alphanumeric characters only. The rule_id is unique within the kind of rule and -scope: rule_ids need not be unique between rules of the same kind on different -devices. +Rules also have an identifier, rule_id, which is a string. The rule_id is +unique within the kind of rule and scope: rule_ids need not be unique between +rules of the same kind on different devices. A home server may also have server default rules of each kind and in each scope. Server default rules are lower priority than user-defined rules in eacgh scope. From 7c0d1c86d8f38f19a6c114961e13f6a83472907b Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 5 Feb 2015 14:56:07 +0000 Subject: [PATCH 18/24] How to tell server default rules from other rules. --- drafts/push_csapi.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index 5f8515f1..1cc0131e 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -101,7 +101,8 @@ rules of the same kind on different devices. A home server may also have server default rules of each kind and in each scope. Server default rules are lower priority than user-defined rules in eacgh scope. Server defined rules do not have a rule_id except when it is necessary to derive -the function of the rule (ie. in room and sender rules). +the function of the rule (ie. in room and sender rules). Server default rules +have an attribute, "default" set to true. Push Rules: Actions: -------------------- From 6c5d07a0d14d5ad8a9084bf6b8aa1096cea648d7 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sun, 8 Feb 2015 02:32:06 +0000 Subject: [PATCH 19/24] typoe --- drafts/push_pgwapi.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drafts/push_pgwapi.rst b/drafts/push_pgwapi.rst index 8dd054f6..bb95acaf 100644 --- a/drafts/push_pgwapi.rst +++ b/drafts/push_pgwapi.rst @@ -127,6 +127,6 @@ gateway). However, Matrix strongly recommends: * That the APNS token be base64 encoded and used as the pushkey. * That a different app_id be used for apps on the production and sandbox APS environments. - * That PANS push gateways do not attempt to wait for errors from the APNS + * That APNS push gateways do not attempt to wait for errors from the APNS gateway before returning and instead to store failures and return 'rejected' responses next time that pushkey is used. From 2c8b875cf133b14604f6cb45b55f5eb76511e6ed Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sun, 8 Feb 2015 02:33:53 +0000 Subject: [PATCH 20/24] typoe --- drafts/push_csapi.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index 1cc0131e..c23ff0b1 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -133,7 +133,7 @@ their parameters, eg. { "set_tweak": "sound", "value": "default" } Push Rule Actions: Tweaks ------------------------- The 'set_tweak' key action is used to add an entry to the 'tweaks' dictionary -that is sent in the notification poke. The following tweaks are e defined: +that is sent in the notification poke. The following tweaks are defined: sound A sound to be played when this notification arrives. 'default' means to From 56f4467cede56b3014318f914705e8b7f372bdbd Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Mon, 9 Feb 2015 09:19:45 +0000 Subject: [PATCH 21/24] Fix syntax error --- drafts/push_csapi.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index c23ff0b1..9c89170d 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -159,6 +159,7 @@ event_match profile_tag Matches the profile_tag of the device that the notification would be delivered to. Parameters: + * 'profile_tag': The profile_tag to match with. contains_display_name This matches unencrypted messages where content.body contains the owner's From 246531813bc7e3893596d20ba27aff5f27bd1516 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Thu, 12 Feb 2015 20:23:36 +0000 Subject: [PATCH 22/24] typo --- drafts/push_csapi.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index 9c89170d..01bbe00a 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -99,7 +99,7 @@ unique within the kind of rule and scope: rule_ids need not be unique between rules of the same kind on different devices. A home server may also have server default rules of each kind and in each scope. -Server default rules are lower priority than user-defined rules in eacgh scope. +Server default rules are lower priority than user-defined rules in each scope. Server defined rules do not have a rule_id except when it is necessary to derive the function of the rule (ie. in room and sender rules). Server default rules have an attribute, "default" set to true. From 7a0f7b4b43c5eb34e9fb7e62a270edd2a8e08c90 Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 13 Feb 2015 13:40:44 +0000 Subject: [PATCH 23/24] Add that rules with no conditions always match. --- drafts/push_csapi.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/drafts/push_csapi.rst b/drafts/push_csapi.rst index 01bbe00a..9cef9004 100644 --- a/drafts/push_csapi.rst +++ b/drafts/push_csapi.rst @@ -147,8 +147,9 @@ Push Rules: Conditions: ----------------------- Override, Underride and Default rules have a list of 'conditions'. All conditions must hold true for an event in order for a rule to be applied to an -event. Matrix specifies the following conditions, although if Home Servers wish -to support others, they are free to do so: +event. A rule with no conditions always matches. Matrix specifies the following +conditions, although if Home Servers wish to support others, they are free to +do so: event_match This is a glob pattern match on a field of the event. Parameters: From f0cc0e082c39d3054ba3d381c8022be25ff41879 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 19 Feb 2015 10:13:21 +0000 Subject: [PATCH 24/24] Add room_id in push poke to spec. --- drafts/push_pgwapi.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/drafts/push_pgwapi.rst b/drafts/push_pgwapi.rst index bb95acaf..92035581 100644 --- a/drafts/push_pgwapi.rst +++ b/drafts/push_pgwapi.rst @@ -14,6 +14,7 @@ is as follows:: { "notification": { "id": "$3957tyerfgewrf384", + "room_id": "!slw48wfj34rtnrf:example.com", "type": "m.room.message", "sender": "@exampleuser:matrix.org", "sender_display_name": "Major Tom", @@ -50,6 +51,8 @@ id An identifier for this notification that may be used to detect duplicate notification requests. This is not necessarily the ID of the event that triggered the notification. +room_id + The ID of the room in which this event occurred. type The type of the event as in the event's 'type' field. sender