推送网关 API

本页面的翻译未经核对，可能存在翻译质量不佳、错翻、漏翻等情况。您可以在 Forgejo 存储库打开 Issue、提交 Pull Request 或邮件联系我们提出改进建议和参与翻译与核对。

客户端可能希望在主服务器接收到事件时获得推送通知。对此进行管理的是一个名为推送网关的独立实体。

概述

客户端的主服务器会将接收到的事件信息转发给推送网关。随后，推送网关会向推送通知提供商（如 APNS、GCM）发送推送通知。

                                   +--------------------+  +-------------------+
                  Matrix HTTP      |                    |  |                   |
             Notification Protocol |   应用开发者         |  |   设备供应商        |
                                   |                    |  |                   |
           +-------------------+   | +----------------+ |  | +---------------+ |
           |                   |   | |                | |  | |               | |
           | Matrix 主服务器    +----->   推送网关       +------> 推送提供商      | |
           |                   |   | |                | |  | |               | |
           +-^-----------------+   | +----------------+ |  | +----+----------+ |
             |                     |                    |  |      |            |
    Matrix   |                     |                    |  |      |            |
 客户端/服务器 API  +              |                    |  |      |            |
             |      |              +--------------------+  +-------------------+
             |   +--+-+                                           |
             |   |    <-------------------------------------------+
             +---+    |
                 |    |          提供商推送协议
                 +----+

            移动设备或客户端

API 标准

不支持的端点

如果收到对不支持（或未知）端点的请求，则服务器必须以 404 M_UNRECOGNIZED 错误进行响应。

类似地，405 M_UNRECOGNIZED 错误用于表示对已知端点使用了不被支持的方法。

主服务器行为

本节描述了“HTTP”推送器用于向推送网关发送事件通知的格式。如果端点返回 HTTP 错误码，主服务器应在合理的时间内采用指数退避机制进行重试。

在推送事件通知时，主服务器应在 /notify 请求中包含所有与事件相关的字段。当主服务器执行 format 为 "event_id_only" 的推送时，仅需填写 event_id、room_id、counts 和 devices 字段。

请注意，本端点的大多数数值和行为已由客户端-服务器 API 的推送模块描述。

POST /_matrix/push/v1/notify

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.

Clients interested in receiving notifications via this endpoint MUST configure its full URI when creating the associated pusher via /_matrix/client/v3/pushers/set.

Rate-limited:	No
Requires authentication:	No

Request

Request body

Name	Type	Description
`notification`	`Notification`	Required: Information about the push notification

Notification
Name	Type	Description
`content`	`EventContent`	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`	`Counts`	This is a dictionary of the current number of unacknowledged communications for the recipient user. Counts whose value is zero should be omitted.
`devices`	`[Device]`	Required: This is an array of devices that the notification should be sent to.
`event_id`	`string`	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.
`prio`	`string`	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. One of: `[high, low]`.
`room_alias`	`string`	An alias to display for the room in which the event occurred.
`room_id`	`string`	The ID of the room in which this event occurred. Required if the notification relates to a specific Matrix event.
`room_name`	`string`	The name of the room in which the event occurred.
`sender`	`string`	The sender of the event as in the corresponding event field.
`sender_display_name`	`string`	The current display name of the sender in the room in which the event occurred.
`type`	`string`	The type of the event as in the event’s `type` field.
`user_is_target`	`boolean`	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).

Counts
Name	Type	Description
`missed_calls`	`integer`	The number of unacknowledged missed calls a user has across all rooms of which they are a member.
`unread`	`integer`	The number of unread messages a user has across all of the rooms they are a member of.

Device
Name	Type	Description
`app_id`	`string`	Required: The `app_id` given when the pusher was created.
`data`	`PusherData`	A dictionary of additional pusher-specific data. This is the `data` dictionary passed in at pusher creation minus the `url` key.
`pushkey`	`string`	Required: The `pushkey` given when the pusher was created.
`pushkey_ts`	`integer`	The unix timestamp (in seconds) when the pushkey was last updated.
`tweaks`	`Tweaks`	A dictionary of customisations made to the way this notification is to be presented. These are added by push rules.

PusherData
Name	Type	Description
`format`	`string`	The format to use for sending notifications.

Request body example

{
  "notification": {
    "content": {
      "body": "I'm floating in a most peculiar way.",
      "msgtype": "m.text"
    },
    "counts": {
      "missed_calls": 1,
      "unread": 2
    },
    "devices": [
      {
        "app_id": "org.matrix.matrixConsole.ios",
        "data": {},
        "pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/",
        "pushkey_ts": 12345678,
        "tweaks": {
          "sound": "bing"
        }
      }
    ],
    "event_id": "$3957tyerfgewrf384",
    "prio": "high",
    "room_alias": "#exampleroom:matrix.org",
    "room_id": "!slw48wfj34rtnrf:example.com",
    "room_name": "Mission Control",
    "sender": "@exampleuser:matrix.org",
    "sender_display_name": "Major Tom",
    "type": "m.room.message"
  }
}

Responses

Status	Description
`200`	A list of rejected push keys.

200 response

Name	Type	Description
`rejected`	`[string]`	Required: 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.

{
  "rejected": [
    "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/"
  ]
}