2021-01-19 23:57:35 +00:00
---
type: module
weight: 80
---
2021-01-21 05:45:35 +00:00
### Send-to-Device messaging
2021-01-19 23:57:35 +00:00
This module provides a means by which clients can exchange signalling
messages without them being stored permanently as part of a shared
communication history. A message is delivered exactly once to each
client device.
The primary motivation for this API is exchanging data that is
meaningless or undesirable to persist in the room DAG - for example,
one-time authentication tokens or key data. It is not intended for
2021-01-30 21:25:57 +00:00
conversational data, which should be sent using the normal [`/rooms/<room_id>/send` ](/client-server-api/#put_matrixclientr0roomsroomidsendeventtypetxnid ) API for
2021-01-19 23:57:35 +00:00
consistency throughout Matrix.
#### Client behaviour
To send a message to other devices, a client should call
2021-01-30 21:25:57 +00:00
[`/sendToDevice` ](/client-server-api/#put_matrixclientr0sendtodeviceeventtypetxnid ). Only one message can be sent to each device per
2021-01-19 23:57:35 +00:00
transaction, and they must all have the same event type. The device ID
in the request body can be set to `*` to request that the message be
sent to all known devices.
If there are send-to-device messages waiting for a client, they will be
2021-01-30 21:25:57 +00:00
returned by [`/sync` ](/client-server-api/#get_matrixclientr0sync ), as detailed in [Extensions to /sync ](/client-server-api/#extensions-to-sync ). Clients should
2021-01-19 23:57:35 +00:00
inspect the `type` of each returned event, and ignore any they do not
understand.
#### Server behaviour
Servers should store pending messages for local users until they are
2021-01-30 21:25:57 +00:00
successfully delivered to the destination device. When a client calls
[`/sync` ](/client-server-api/#get_matrixclientr0sync )
2021-01-19 23:57:35 +00:00
with an access token which corresponds to a device with pending
messages, the server should list the pending messages, in order of
arrival, in the response body.
When the client calls `/sync` again with the `next_batch` token from the
first response, the server should infer that any send-to-device messages
in that response have been delivered successfully, and delete them from
the store.
If there is a large queue of send-to-device messages, the server should
limit the number sent in each `/sync` response. 100 messages is
recommended as a reasonable limit.
If the client sends messages to users on remote domains, those messages
should be sent on to the remote servers via
2021-01-21 05:45:35 +00:00
[federation ](/server-server-api#send-to-device-messaging ).
2021-01-19 23:57:35 +00:00
#### Protocol definitions
2021-01-29 23:32:31 +00:00
{{% http-api spec="client-server" api="to_device" %}}
2021-01-19 23:57:35 +00:00
##### Extensions to /sync
2021-01-30 21:25:57 +00:00
This module adds the following properties to the [`/sync` ](/client-server-api/#get_matrixclientr0sync ) response:
2021-01-19 23:57:35 +00:00
2021-01-22 01:08:08 +00:00
| Parameter | Type | Description |
|-----------|-----------|-----------------------------------------------------------------------------|
| to_device | ToDevice | Optional. Information on the send-to-device messages for the client device. |
2021-01-19 23:57:35 +00:00
`ToDevice`
2021-01-22 01:08:08 +00:00
| Parameter | Type | Description |
|-----------|-----------|----------------------------------|
| events | [Event] | List of send-to-device messages. |
2021-01-19 23:57:35 +00:00
`Event`
2021-01-22 01:08:08 +00:00
| Parameter | Type | Description |
|------------|--------------|-------------------------------------------------------------------------------------------------|
| content | EventContent | The content of this event. The fields in this object will vary depending on the type of event. |
| sender | string | The Matrix user ID of the user who sent this event. |
| type | string | The type of event. |
2021-01-19 23:57:35 +00:00
Example response:
2021-01-20 18:48:15 +00:00
```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"]
}
2021-01-19 23:57:35 +00:00
}
2021-01-20 18:48:15 +00:00
]
}
}
```