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. + + +