# Copyright 2016 OpenMarket Ltd # Copyright 2018 New Vector Ltd # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. openapi: 3.1.0 info: title: Matrix Push Notification API version: 1.0.0 paths: /notify: post: summary: Notify a push gateway about an event. description: |- This endpoint is invoked by HTTP pushers to notify a push gateway about an event or update the number of unread notifications a user has. In the former case it will contain selected information about the event. In either case it may contain numeric counts of the number of unread events of different types the user has. The counts may be sent along with a notification about an event or by themselves. Notifications about a particular event will normally cause the user to be alerted in some way. It is therefore necessary to perform duplicate suppression for such notifications using the `event_id` field to avoid retries of this HTTP API causing duplicate alerts. The operation of updating counts of unread notifications should be idempotent and therefore do not require duplicate suppression. Notifications are sent to the URL configured when the pusher is created. This means that the HTTP path may be different depending on the push gateway. operationId: notify requestBody: content: application/json: schema: type: object example: { "notification": { "event_id": "$3957tyerfgewrf384", "room_id": "!slw48wfj34rtnrf:example.com", "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" } } ] } } required: - notification properties: notification: type: object title: Notification description: Information about the push notification required: - devices properties: event_id: type: string description: |- The Matrix event ID of the event being notified about. This is required if the notification is about a particular Matrix event. It may be omitted for notifications that only contain updated badge counts. This ID can and should be used to detect duplicate notification requests. room_id: type: string description: |- The ID of the room in which this event occurred. Required if the notification relates to a specific Matrix event. type: type: string description: The type of the event as in the event's `type` field. sender: type: string description: The sender of the event as in the corresponding event field. sender_display_name: type: string description: |- The current display name of the sender in the room in which the event occurred. room_name: type: string description: The name of the room in which the event occurred. room_alias: type: string description: An alias to display for the room in which the event occurred. user_is_target: type: boolean description: |- This is true if the user receiving the notification is the subject of a member event (i.e. the `state_key` of the member event is equal to the user's Matrix ID). prio: type: string enum: - high - low description: |- The priority of the notification. 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: type: object title: EventContent description: |- The `content` field from the event, if present. The pusher may omit this if the event had no content or for any other reason. counts: type: object title: Counts description: |- This is a dictionary of the current number of unacknowledged communications for the recipient user. Counts whose value is zero should be omitted. properties: unread: type: integer description: |- The number of unread messages a user has across all of the rooms they are a member of. missed_calls: type: integer description: |- The number of unacknowledged missed calls a user has across all rooms of which they are a member. devices: type: array title: Devices description: This is an array of devices that the notification should be sent to. items: type: object title: Device properties: app_id: type: string description: The `app_id` given when the pusher was created. pushkey: type: string description: The `pushkey` given when the pusher was created. pushkey_ts: type: integer format: int64 description: |- The unix timestamp (in seconds) when the pushkey was last updated. data: type: object title: PusherData description: |- A dictionary of additional pusher-specific data. This is the `data` dictionary passed in at [pusher creation](/client-server-api/#post_matrixclientv3pushersset) minus the `url` key. properties: format: type: string description: |- The format to use for sending notifications. tweaks: type: object title: Tweaks description: |- A dictionary of customisations made to the way this notification is to be presented. These are added by push rules. required: - app_id - pushkey description: Information about the push notification. required: true responses: "200": description: A list of rejected push keys. content: application/json: schema: type: object # empty json object properties: rejected: type: array description: |- 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. Homeservers 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. May be empty. items: type: string description: A pushkey that has been rejected. required: - rejected examples: response: value: { "rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ] } servers: - url: "{protocol}://{hostname}{basePath}" variables: protocol: enum: - http - https default: https hostname: default: localhost:8008 basePath: default: /_matrix/push/v1