swagger: '2.0' info: title: "Matrix Client-Server Push API" version: "1.0.0" host: localhost:8008 schemes: - https - http basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% 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: "/pushers": get: summary: Gets the current pushers for the authenticated user description: |- Gets all currently active pushers for the authenticated user security: - accessToken: [] responses: 200: description: The pushers for this user examples: application/json: |- [ { "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=", "kind": "http", "app_id": "face.mcapp.appy.prod", "app_display_name": "Appy McAppface", "device_display_name": "Alice's Phone", "profile_tag": "xyz", "lang": "en-US", "data": { "url": "https://example.com/_matrix/push/v1/notify" } } ] schema: type: array items: type: object title: Pusher properties: pushkey: type: string description: |- 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. Max length, 512 bytes. kind: type: string description: |- The kind of pusher to configure. ``"http"`` makes a pusher that sends HTTP pokes. ``null`` deletes the pusher. app_id: type: string description: |- This 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: type: string description: |- A string that will allow the user to identify what application owns this pusher. device_display_name: type: string description: |- a string that will allow the user to identify what device owns this pusher. profile_tag: type: string description: |- This string determines which set of device specific rules this pusher executes. lang: type: string description: |- The preferred language for receiving notifications (e.g. 'en' or 'en-US') data: type: object description: |- A dictionary of information for the pusher implementation itself. If ``kind`` is ``http``, this should contain ``url`` which is the URL to use to send notifications to. title: PusherData properties: url: type: string description: |- Required if ``kind`` is ``http``. The URL to use to send notifications to. tags: - Push notifications "/pushers/set": post: summary: Modify a pusher for this user on the homeserver. description: |- This endpoint allows the creation, modification and deletion of `pushers`_ for this user ID. The behaviour of this endpoint varies depending on the values in the JSON body. security: - accessToken: [] parameters: - in: body name: pusher description: The pusher information required: true schema: type: object example: |- { "lang": "en", "kind": "http", "app_display_name": "Mat Rix", "device_display_name": "iPhone 9", "profile_tag": "xxyyzz", "app_id": "com.example.app.ios", "pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ", "data": { "url": "https://push-gateway.location.here" }, "append": false } properties: pushkey: type: string description: |- 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. Max length, 512 bytes. kind: type: string description: |- The kind of pusher to configure. ``"http"`` makes a pusher that sends HTTP pokes. ``null`` deletes the pusher. app_id: type: string description: |- This 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: type: string description: |- A string that will allow the user to identify what application owns this pusher. device_display_name: type: string description: |- a string that will allow the user to identify what device owns this pusher. profile_tag: type: string description: |- This string determines which set of device specific rules this pusher executes. lang: type: string description: |- The preferred language for receiving notifications (e.g. 'en' or 'en-US') data: type: object description: |- A dictionary of information for the pusher implementation itself. If ``kind`` is ``http``, this should contain ``url`` which is the URL to use to send notifications to. title: PusherData properties: url: type: string description: |- Required if ``kind`` is ``http``. The URL to use to send notifications to. append: type: boolean description: |- If true, the homeserver should add another pusher with the given pushkey and App ID in addition to any others with different user IDs. Otherwise, the homeserver must remove any other pushers with the same App ID and pushkey for different users. The default is ``false``. required: ['kind', 'app_id', 'app_display_name', 'device_display_name', 'pushkey', 'lang', 'data'] responses: 200: description: The pusher was set. examples: application/json: |- {} schema: type: object # empty json object 400: description: One or more of the pusher values were invalid. examples: application/json: |- { "error": "Missing parameters: lang, data", "errcode": "M_MISSING_PARAM" } schema: type: object 429: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" tags: - Push notifications