3.8 KiB
3.8 KiB
设备间消息发送（Send-to-Device messaging）
本模块为客户端提供了一种交换信令消息的方式，这些消息不会作为共享通信历史的一部分被永久存储。每条消息将精确地送达每个客户端设备一次。
该 API 的主要动机是用于交换在房间有向无环图（DAG）中无意义或不希望持久保存的数据——例如，一次性身份验证令牌或密钥数据。它并不适用于会话内容，会话内容应使用常规的 /rooms/<room_id>/send API 发送，以保持 Matrix 协议的一致性。
客户端行为
要向其他设备发送消息，客户端应调用 /sendToDevice。每个事务中，每台设备只能发送一条消息，且所有消息的事件类型必须一致。请求体中的设备ID可以设置为 *，以请求将消息发送到所有已知设备。
如果有等待客户端接收的设备间消息，这些消息将通过 /sync 返回，详见对 /sync 的扩展。客户端应检查每个返回事件的 type 字段，并忽略其无法识别的事件。
服务器行为
服务器应为本地用户存储待发送消息，直到它们成功送达目标设备。当客户端使用与有待发送消息的设备相关联的访问令牌调用 /sync 时，服务器应按到达顺序在响应体中列出这些待发送消息。
当客户端再次使用第一次响应中的 next_batch 令牌调用 /sync 时，服务器应推断该响应中的所有设备间消息已成功送达，并从存储中删除它们。
如果有大量待发送的设备间消息，服务器应限制在每次 /sync 响应中发送的消息数量。建议合理的上限为 100 条消息。
如果客户端向远程域的用户发送消息，这些消息应通过联邦协议（federation）发送至远程服务器。
协议定义
{{% http-api spec="client-server" api="to_device" %}}
对 /sync 的扩展
本模块在 /sync 响应中增加了以下属性：
| 参数 | 类型 | 说明 |
|---|---|---|
| to_device | ToDevice | 可选。关于本客户端设备的设备间消息（send-to-device）信息。 |
ToDevice
| 参数 | 类型 | 说明 |
|---|---|---|
| events | [Event] | 设备间消息列表。 |
Event
| 参数 | 类型 | 说明 |
|---|---|---|
| content | EventContent | 本事件的内容。此对象中的字段将根据事件类型有所不同。 |
| sender | string | 发送本事件的 Matrix 用户ID。 |
| type | string | 事件类型。 |
示例响应：
{
"next_batch": "s72595_4483_1934",
"rooms": {"leave": {}, "join": {}, "invite": {}},
"to_device": {
"events": [
{
"sender": "@alice:example.com",
"type": "m.new_device",
"content": {
"device_id": "XYZABCDE",
"rooms": ["!726s6s6q:example.com"]
}
}
]
}
}