### 设备间消息发送（Send-to-Device messaging）

本模块为客户端提供了一种交换信令消息的方式，这些消息不会作为共享通信历史的一部分被永久存储。每条消息将精确地送达每个客户端设备一次。

该 API 的主要动机是用于交换在房间有向无环图（DAG）中无意义或不希望持久保存的数据——例如，一次性身份验证令牌或密钥数据。它并不适用于会话内容，会话内容应使用常规的 [`/rooms/<room_id>/send`](/client-server-api/#put_matrixclientv3roomsroomidsendeventtypetxnid) API 发送，以保持 Matrix 协议的一致性。

#### 客户端行为

要向其他设备发送消息，客户端应调用 [`/sendToDevice`](/client-server-api/#put_matrixclientv3sendtodeviceeventtypetxnid)。每个事务中，每台设备只能发送一条消息，且所有消息的事件类型必须一致。请求体中的设备ID可以设置为 `*`，以请求将消息发送到所有已知设备。

如果有等待客户端接收的设备间消息，这些消息将通过 [`/sync`](/client-server-api/#get_matrixclientv3sync) 返回，详见[对 /sync 的扩展](/client-server-api/#extensions-to-sync)。客户端应检查每个返回事件的 `type` 字段，并忽略其无法识别的事件。

#### 服务器行为

服务器应为本地用户存储待发送消息，直到它们成功送达目标设备。当客户端使用与有待发送消息的设备相关联的访问令牌调用 [`/sync`](/client-server-api/#get_matrixclientv3sync) 时，服务器应按到达顺序在响应体中列出这些待发送消息。

当客户端再次使用第一次响应中的 `next_batch` 令牌调用 `/sync` 时，服务器应推断该响应中的所有设备间消息已成功送达，并从存储中删除它们。

如果有大量待发送的设备间消息，服务器应限制在每次 `/sync` 响应中发送的消息数量。建议合理的上限为 100 条消息。

如果客户端向远程域的用户发送消息，这些消息应通过[联邦协议（federation）](/server-server-api#send-to-device-messaging)发送至远程服务器。

#### 协议定义

{{% http-api spec="client-server" api="to_device" %}}

##### 对 /sync 的扩展

本模块在 [`/sync`](/client-server-api/#get_matrixclientv3sync) 响应中增加了以下属性：

| 参数       | 类型        | 说明                                                               |
|------------|-------------|--------------------------------------------------------------------|
| to_device  | ToDevice    | 可选。关于本客户端设备的设备间消息（send-to-device）信息。          |

`ToDevice`

| 参数       | 类型        | 说明                                   |
|------------|-------------|----------------------------------------|
| events     | [Event]     | 设备间消息列表。                       |

`Event`

| 参数      | 类型           | 说明                                                                                     |
|-----------|----------------|------------------------------------------------------------------------------------------|
| content   | EventContent   | 本事件的内容。此对象中的字段将根据事件类型有所不同。                                     |
| sender    | string         | 发送本事件的 Matrix 用户ID。                                                            |
| type      | string         | 事件类型。                                                                              |

示例响应：

```json
{
  "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"]
        }
      }
    ]
  }
}
```