Protocol Reference

Protocol Reference

This reference is generated from JSON Schemas used in the testing and development of Valent. For any other use, please see the upstream version of the KDE Connect protocol instead.

Table of Contents

Core Protocol

The core of the KDE Connect protocol is built on the exchange of JSON packets, similar to JSON-RPC.

References

Packets

kdeconnect.*

The structure of a KDE Connect packet is similar to a JSON-RPC request, although the protocols are quite different. The id field holds a timestamp, the type field holds a type string and the body field holds a dictionary of parameters. While the id field is not used in KDE Connect, the type and body fields are analogous to the method and params members of a JSON-RPC request.

Packets are sent by devices with no guarantee that they will be received, or that if received there will be a response. For this reason, plugins consistently handle any incoming packet regardless of whether it was expected or not. In other words, packet handling in KDE Connect is typically idempotent.

Payloads are declared by the presence of the payloadSize and payloadTransferInfo fields, which indicate that the packet sender is waiting to transfer payloadSize bytes over the connection described by payloadTransferInfo. For example, the payloadTransferInfo dictionary might have a port entry holding a TCP port the device is listening on for incoming connections.

{
    "id": 0,
    "type": "kdeconnect.share.request",
    "body": {
        "filename": "image.png"
    },
    "payloadSize": 882,
    "payloadTransferInfo": {
        "port": 1739
    }
}

  • id: Number 🔒

    A UNIX epoch timestamp (ms). In some cases KDE Connect clients erroneously set this field as a string.

  • type: String 🔒

    pattern: /^kdeconnect(\.[a-z_]+)+$/

    A string in the form of kdeconnect.<plugin> or kdeconnect.<plugin>.<action> such as kdeconnect.mpris and kdeconnect.mpris.request.

  • body: Object 🔒

    A dictionary of parameters appropriate for the packet type.

This packet has no body fields.

  • payloadSize: Number

    range: Unrestricted

    The size of the payload to expect. There is a currently unused convention of using -1 to declare a stream of indefinite size.

  • payloadTransferInfo: Object

    A dictionary of properties necessary for clients to negotiate a transfer channel.

kdeconnect.identity

The KDE Connect identity packet is used to identify devices and their capabilities.

Each networking module may define additional fields necessary for clients to connect. For example, in the LAN protocol the identity packet is broadcast over UDP with a tcpPort field.

{
    "id": 0,
    "type": "kdeconnect.identity",
    "body": {
        "deviceId": "740bd4b9_b418_4ee4_97d6_caf1da8151be",
        "deviceName": "FOSS Phone",
        "deviceType": "phone",
        "incomingCapabilities": [
            "kdeconnect.mock.echo",
            "kdeconnect.mock.transfer"
        ],
        "outgoingCapabilities": [
            "kdeconnect.mock.echo",
            "kdeconnect.mock.transfer"
        ],
        "protocolVersion": 7
    }
}

  • deviceId: String 🔒

    pattern: /^[a-fA-F0-9]{8}_[a-fA-F0-9]{4}_[a-fA-F0-9]{4}_[a-fA-F0-9]{4}_[a-fA-F0-9]{12}|.*$/

    A unique ID for the device, which should be a UUIDv4 string with hyphens (-) replaced with underscores (_), such as 740bd4b9_b418_4ee4_97d6_caf1da8151be.

    Note that older clients may report a device ID in a different format, and a compliant implementation must accept and respond with the device’s reported ID. Implementations are responsible for any sanitization necessary for internal use.

  • deviceName: String 🔒

    pattern: /^[^"',;:.!?()\[\]<>]{1,32}$/

    A human-readable label for the device. Must be 1-32 characters in length and can’t contain any of the following punctuation marks "',;:.!?()[]<>. When displayed to the user for pairing or other privileged interactions, it should always be displayed within quotes.

  • deviceType: String 🔒

    enum: 'desktop'|'laptop'|'phone'|'tablet'|'tv'

    A device type string. Since the incomingCapabilities and outgoingCapabilities fields describe the functionality of a device, the deviceType field is typically only used to select an icon.

  • incomingCapabilities: Array of String 🔒

    A list of packet types the device can consume. Note that this is only an indication a device can consume a packet type, not that it will.

  • outgoingCapabilities: Array of String 🔒

    A list of packet types the device can provide. Note that this is only an indication a device can provide a packet type, not that it will.

  • protocolVersion: Number 🔒

    enum: 7

    The protocol version. The only value currently valid is 7

kdeconnect.pair

The KDE Connect pair packet is used to negotiate pairing between devices. Devices must be paired before sending any other packets and should reject any incoming packets from unpaired devices.

A device sends a packet with pair set to true to request pairing. A response is expected with pair set to true to accept or false to reject. By convention the request times out after 30 seconds.

A device sends a packet with pair set to false to unpair or reject a pairing request. No response is expected.

{
    "id": 0,
    "type": "kdeconnect.pair",
    "body": {
        "pair": true
    }
}

{
    "id": 0,
    "type": "kdeconnect.pair",
    "body": {
        "pair": false
    }
}

  • pair: Boolean 🔒

    If true a pairing request is being accepted or a new one started. If false a pairing request is being rejected or a paired device is unpairing.

Battery Plugin

The Battery plugin allows a device to expose the status of its battery.

References

Packets

kdeconnect.battery

This packet is a battery status update.

{
    "id": 0,
    "type": "kdeconnect.battery",
    "body": {
        "currentCharge": 15,
        "isCharging": false,
        "thresholdEvent": 1
    }
}

  • currentCharge: Number 🔒

    range: -1–100

    The current battery percentage, typically between 0 and 100. If the value is -1, the device should be treated as though it has no battery.

  • isCharging: Boolean 🔒

    A boolean value indicating whether the battery is currently charging.

  • thresholdEvent: Number

    enum: 0|1

    Either 1 if the battery is below the threshold level, 0 otherwise. The threshold is chosen arbitrarily by the reporting device.

kdeconnect.battery.request

⚠️ Deprecated: This packet is sent to request a battery status update.

{
    "id": 0,
    "type": "kdeconnect.battery.request",
    "body": {
        "request": true
    }
}

  • request: Boolean 🔒

    ⚠️ Deprecated: Whether to request a status update. It only makes sense for this to be true.

Clipboard Plugin

The Clipboard plugin allows syncing clipboard text content between devices.

References

Packets

kdeconnect.clipboard

This packet is sent when the clipboard content changes. In other words, it is typically sent when the selection owner changes.

{
    "id": 0,
    "type": "kdeconnect.clipboard",
    "body": {
        "content": "some text"
    }
}

  • content: String 🔒

    Text content of the clipboard.

kdeconnect.clipboard.connect

This packet is only sent when a device connects.

{
    "id": 0,
    "type": "kdeconnect.clipboard",
    "body": {
        "content": "some text",
        "timestamp": 0
    }
}

  • content: String 🔒

    Text content of the clipboard.

  • timestamp: Number 🔒

    UNIX epoch timestamp (ms) for the clipboard content. If the timestamp is 0 or less than the local timestamp, the content should be ignored.

Connectivity Report Plugin

The Connectivity Report plugin allows a device to expose the status of its connectivity.

References

Packets

kdeconnect.connectivity_report

This packet is a connectivity report.

{
    "id": 0,
    "type": "kdeconnect.connectivity_report",
    "body": {
        "signalStrengths": {
            "6": {
                "networkType": "4G",
                "signalStrength": 3
            },
            "17": {
                "networkType": "HSPA",
                "signalStrength": -1
            }
        }
    }
}

  • signalStrengths: Object 🔒

    A dictionary of signal states. Each key is an arbitrary, but unique, string and each value is a Signal object.

    • Signal (Object)

      The ID of the attachment.

      • networkType: String 🔒

        enum: 'GSM'|'CDMA'|'iDEN'|'UMTS'|'CDMA2000'|'EDGE'|'GPRS'|'HSPA'|'LTE'|'5G'|'Unknown'

        The network type.

      • signalStrength: Number 🔒

        range: -1–5

        The signal strength. As with the battery plugin, -1 means the device is not available. Values 0 through 5 describe the coarse strength of the signal.

kdeconnect.connectivity_report.request

⚠️ Deprecated: This packet is sent to request a connectivity report.

{
    "id": 0,
    "type": "kdeconnect.connectivity_report.request",
    "body": {}
}

This packet has no body fields.

Contacts Plugin

The Contacts plugin allows devices to share contacts in vCard format.

References

Packets

kdeconnect.contacts.request_all_uids_timestamps

This packet is a request for a list of contact UIDs with modification timestamps.

{
    "id": 0,
    "type": "kdeconnect.contacts.request_all_uids_timestamps",
    "body": {}
}

This packet has no body fields.

kdeconnect.contacts.request_vcards_by_uid

This packet is a request for a list of contact UIDs with vCard data.

{
    "id": 0,
    "type": "kdeconnect.contacts.request_vcards_by_uid",
    "body": {
        "uids": [
            "test-contact1",
            "test-contact2"
        ]
    }
}

kdeconnect.contacts.response_uids_timestamps

This packet is a list of contact UIDs with modification timestamps.

{
    "id": 0,
    "type": "kdeconnect.contacts.response_all_uids_timestamps",
    "body": {
        "uids": [
            "test-contact1",
            "test-contact2"
        ],
        "test-contact1": 1608700784336,
        "test-contact2": 1608700782848
    }
}

  • uids: Array of String 🔒

    A list of contact UIDs. Each UID has a corresponding uid-timestamp pair in the body object.

kdeconnect.contacts.response_vcards

This packet is a list of contact UIDs with vCard data.

{
    "id": 0,
    "type": "kdeconnect.contacts.response_vcards",
    "body": {
        "uids": [
            "test-contact1",
            "test-contact2"
        ],
        "test-contact1": "BEGIN:VCARD\nVERSION:2.1\nFN:Contact One\nTEL;CELL:123-456-7890\nX-KDECONNECT-ID-DEV-test-device:test-contact1\nX-KDECONNECT-TIMESTAMP:1608700784336\nEND:VCARD",
        "test-contact2": "BEGIN:VCARD\nVERSION:2.1\nFN:Contact Two\nTEL;CELL:123-456-7891\nX-KDECONNECT-ID-DEV-test-device:test-contact2\nX-KDECONNECT-TIMESTAMP:1608700782848\nEND:VCARD"
    }
}

  • uids: Array of String 🔒

    A list of contact UIDs. Each UID has a corresponding uid-vcard pair in the body object.

FindMyPhone Plugin

The FindMyPhone plugin allows requesting a device to announce it’s location, usually by playing a sound like a traditional cordless phone.

References

Packets

kdeconnect.findmyphone.request

This packet is a request for a device to announce its location. By convention, sending a second packet cancels the request.

{
    "id": 0,
    "type": "kdeconnect.findmyphone.request",
    "body": {}
}

This packet has no body fields.

Lock

The Lock plugin allows requesting a device to lock or unlock.

References

Packets

kdeconnect.lock

This packet is a lock status update.

{
    "id": 0,
    "type": "kdeconnect.lock",
    "body": {
        "isLocked": true
    }
}

  • isLocked: Boolean 🔒

    Indicates the current locked status of the device. If true the device is locked and false if unlocked.

kdeconnect.lock.request

This packet is a request for a lock status update or change.

{
    "id": 0,
    "type": "kdeconnect.lock.request",
    "body": {
        "requestLocked": true
    }
}

{
    "id": 0,
    "type": "kdeconnect.lock.request",
    "body": {
        "setLocked": false
    }
}

  • requestLocked: Boolean

    enum: True

    Indicates this is a request for the current locked status. Always true, if present.

  • setLocked: Boolean

    A request to change the locked status. If true the device will be locked or if false unlocked.

MousePad Plugin

The MousePad plugin allows remote control of the pointer and keyboard.

References

Packets

kdeconnect.mousepad.echo

This packet is an echo for a kdeconnect.mousepad.request packet.

{
    "id": 0,
    "type": "kdeconnect.mousepad.echo",
    "body": {
        "key": "a",
        "isAck": true
    }
}

  • key: String

    A request to press-release a single readable character, which may be a unicode character and thus more than one byte.

  • specialKey: Number

    range: 0–32

    A request to press-release a single non-printable character, usually a control character or function key such as Backspace or F10.

  • alt: Boolean

    Indicates whether the Alt modifier should be applied to the associated key or specialKey.

  • ctrl: Boolean

    Indicates whether the Control modifier should be applied to the associated key or specialKey.

  • shift: Boolean

    Indicates whether the Shift modifier should be applied to the associated key or specialKey.

  • super: Boolean

    Indicates whether the Super modifier should be applied to the associated key or specialKey.

  • singleclick: Boolean

    A single press-release of the primary pointer button.

  • doubleclick: Boolean

    A double press-release of the primary pointer button.

  • middleclick: Boolean

    A single press-release of the middle pointer button.

  • rightclick: Boolean

    A single press-release of the secondary pointer button.

  • singlehold: Boolean

    A single press of the primary pointer button.

  • singlerelease: Boolean

    A single release of the primary pointer button.

  • dx: Number

    A double precision integer indicating a relative position delta for the pointer on the X-axis.

  • dy: Number

    A double precision integer indicating a relative position delta for the pointer on the Y-axis.

  • scroll: Boolean

    Whether the associated dx or dy movement is a scroll event.

  • isAck: Boolean 🔒

    Indicates the packet is a confirmation of a request. Always true and always present.

kdeconnect.mousepad.keyboardstate

This packet is a keyboard status update.

{
    "id": 0,
    "type": "kdeconnect.mousepad.keyboardstate",
    "body": {
        "state": true
    }
}

  • state: Boolean 🔒

    Indicates the keyboard is ready to receive keypress events.

kdeconnect.mousepad.request

This packet is a request for a pointer or keyboard event.

{
    "id": 0,
    "type": "kdeconnect.mousepad.request",
    "body": {
        "key": "a",
        "sendAck": true
    }
}

{
    "id": 0,
    "type": "kdeconnect.mousepad.request",
    "body": {
        "dx": 1.0,
        "dy": -1.0
    }
}

  • key: String

    A request to press-release a single readable character, which may be a unicode character and thus more than one byte.

  • specialKey: Number

    range: 0–32

    A request to press-release a single non-printable character, usually a control character or function key such as Backspace or F10.

  • alt: Boolean

    Indicates whether the Alt modifier should be applied to the associated key or specialKey.

  • ctrl: Boolean

    Indicates whether the Control modifier should be applied to the associated key or specialKey.

  • shift: Boolean

    Indicates whether the Shift modifier should be applied to the associated key or specialKey.

  • super: Boolean

    Indicates whether the Super modifier should be applied to the associated key or specialKey.

  • singleclick: Boolean

    A single press-release of the primary pointer button.

  • doubleclick: Boolean

    A double press-release of the primary pointer button.

  • middleclick: Boolean

    A single press-release of the middle pointer button.

  • rightclick: Boolean

    A single press-release of the secondary pointer button.

  • singlehold: Boolean

    A single press of the primary pointer button.

  • singlerelease: Boolean

    A single release of the primary pointer button.

  • dx: Number

    A double precision integer indicating a position delta on the X-axis.

  • dy: Number

    A double precision integer indicating a position delta on the Y-axis.

  • scroll: Boolean

    Whether the associated dx or dy movement is a scroll event.

  • sendAck: Boolean

    Indicates that the devices wants a kdeconnect.mousepad.echo packet as confirmation of a keyboard event.

MPRIS Plugin

The MPRIS plugin allows sharing control of media players.

References

Packets

kdeconnect.mpris

This packet is used to expose media players to a remote device and transfer album art.

{
    "id": 0,
    "type": "kdeconnect.mpris",
    "body": {
        "playerList": [
            "Test Player"
        ],
        "supportAlbumArtPayload": true
    }
}

{
    "id": 0,
    "type": "kdeconnect.mpris",
    "body": {
        "player": "Test Player",
        "canPause": true,
        "canPlay": true,
        "canGoNext": true,
        "canGoPrevious": false,
        "canSeek": true,
        "isPlaying": true,
        "pos": 0,
        "albumArtUrl": "file:///path/to/image.png",
        "nowPlaying": "Unknown",
        "artist": "Test Artist",
        "title": "Test Title",
        "album": "Test Album",
        "length": 180000,
        "volume": 100
    }
}

{
    "id": 0,
    "type": "kdeconnect.mpris",
    "body": {
        "player": "Test Player",
        "albumArtUrl": "file:///path/to/image.png",
        "transferringAlbumArt": true
    },
    "payloadSize": 882,
    "payloadTransferInfo": {
        "port": 1739
    }
}

  • playerList: Array of String

    A list of player names.

  • player: String

    A player name. This field is used to target a player.

  • canPause: Boolean

    Can pause.

  • canPlay: Boolean

    Can play.

  • canGoNext: Boolean

    Can go next.

  • canGoPrevious: Boolean

    Can go previous.

  • canSeek: Boolean

    Can seek.

  • isPlaying: Boolean

    Whether playback is active.

  • loopStatus: String

    enum: 'None'|'Track'|'Playlist'

    The loop status.

  • shuffle: Boolean

    Whether shuffle is enabled.

  • pos: Number

    range: Unrestricted

    Current track position (ms).

  • albumArtUrl: String

    Current track album art URL.

  • nowPlaying: String

    ⚠️ Deprecated: An inclusive string of the format ‘Artist - Title’.

  • artist: String

    Current track artist.

  • title: String

    Current track title.

  • album: String

    Current track album.

  • length: Number

    Current track length (ms).

  • volume: Number

    range: 0–100

    Current player volume (%).

  • supportAlbumArtPayload: Boolean

    Indicates this device supports album art payloads. This field should be set when responding with a list of players.

  • transferringAlbumArt: Boolean

    Indicates this packet carries an album art payload.

kdeconnect.mpris.request

This packet is used to request the status of remote media players, issue commands, and request the transfer of album art payloads.

{
    "id": 0,
    "type": "kdeconnect.mpris.request",
    "body": {
        "requestPlayerList": true
    }
}

{
    "id": 0,
    "type": "kdeconnect.mpris.request",
    "body": {
        "player": "Test Player",
        "requestNowPlaying": true,
        "requestVolume": true
    }
}

{
    "id": 0,
    "type": "kdeconnect.mpris.request",
    "body": {
        "player": "Test Player",
        "action": "Play"
    }
}

{
    "id": 0,
    "type": "kdeconnect.mpris.request",
    "body": {
        "player": "Test Player",
        "albumArtUrl": "file:///path/to/image.png"
    }
}

  • player: String

    The player name

  • requestNowPlaying: Boolean

    Whether the current status is requested.

  • requestPlayerList: Boolean

    Whether the player list is requested.

  • requestVolume: Boolean

    Whether the current volume is requested.

  • Seek: Number

    A request to seek relative to the current position (us).

  • setLoopStatus: String

    enum: 'None'|'Track'|'Playlist'

    A request to set the loop status.

  • SetPosition: Number

    range: Unrestricted

    A request to set the track position (ms).

  • setShuffle: Boolean

    A request to set the shuffle mode.

  • setVolume: Number

    range: 0–100

    A request to set the player volume.

  • action: String

    enum: 'Pause'|'Play'|'PlayPause'|'Stop'|'Next'|'Previous'

    A request to activate a player action.

Notification Plugin

The Notification plugin syncs notifications between devices.

References

Packets

kdeconnect.notification

This packet is a notification.

{
    "id": 0,
    "type": "kdeconnect.notification",
    "body": {
        "id": "notification-id",
        "title": "Information",
        "text": "Something happened",
        "ticker": "Information: Something happened",
        "appName": "Terminal",
        "isClearable": true,
        "onlyOnce": false,
        "silent": true,
        "requestReplyId": "17499937-334b-4704-9c2c-24a0bcd4155a",
        "time": "1631436143331",
        "actions": [
            "Ignore",
            "Open"
        ],
        "payloadHash": "d97f60d052bf11d1e88821e04fff0007"
    }
}

{
    "id": 0,
    "type": "kdeconnect.notification",
    "body": {
        "id": "notification-id",
        "isCancel": true
    }
}

  • id: String 🔒

    The notification ID.

  • isCancel: Boolean

    If true the notification with the indicated ID has been closed.

  • isClearable: Boolean

    If true the notification with the indicated ID can be closed.

  • onlyOnce: Boolean

    If true the notification should only be sent the first time it’s received, otherwise it should be re-sent each time. See the silent field for determining whether a notification is new or not.

  • silent: Boolean

    If true the notification is preexisting, otherwise the remote device just received it.

  • time: String

    A UNIX epoch timestamp (ms) in string form.

  • appName: String 🔒

    The notifying application name.

  • ticker: String 🔒

    The notification title and text in a single string.

  • title: String 🔒

    The notification title.

  • text: String 🔒

    The notification body.

  • payloadHash: String

    An MD5 hash of the notification icon. If the packet contains this field, it will be accompanied by payload transfer information.

  • actions: Array of String

    A list of action names for the notification. Respond with kdeconnect.notification.action to activate.

  • requestReplyId: String

    The UUID for repliable notifications (eg. chat). Respond with kdeconnect.notification.reply to reply.

kdeconnect.notification.action

This packet is an activation of a notification action.

{
    "id": 0,
    "type": "kdeconnect.notification.action",
    "body": {
        "key": "notification-id",
        "action": "Open"
    }
}

kdeconnect.notification.reply

This packet is a reply for a repliable notification.

{
    "id": 0,
    "type": "kdeconnect.notification.reply",
    "body": {
        "requestReplyId": "reply-id",
        "message": "Reply text"
    }
}

  • message: String 🔒

    The message to reply with.

  • requestReplyId: String 🔒

    The reply ID of the notification.

kdeconnect.notification.request

This packet is a request for notifications.

{
    "id": 0,
    "type": "kdeconnect.notification.request",
    "body": {
        "cancel": "notification-id"
    }
}

{
    "id": 0,
    "type": "kdeconnect.notification.request",
    "body": {
        "request": true
    }
}

  • cancel: String

    If present, holds the ID of a notification that should be closed.

  • request: Boolean

    Indicates this is a request for the notifications.

Ping Plugin

The Ping plugin allows sending and receiving simple ‘pings’, with an optional message. Usually these are displayed as notifications.

References

Packets

kdeconnect.ping

This packet is a ping request.

{
    "id": 0,
    "type": "kdeconnect.ping",
    "body": {
        "message": "A message"
    }
}

{
    "id": 0,
    "type": "kdeconnect.ping",
    "body": {}
}

  • message: String

    An optional message.

Presenter Plugin

The Presenter plugin allows sending and receiving simple ‘pings’, with an optional message. Usually these are displayed as notifications.

References

Packets

kdeconnect.presenter

This packet is a presentation remote event.

{
    "id": 0,
    "type": "kdeconnect.presenter",
    "body": {
        "dx": 1.0,
        "dy": 1.0
    }
}

{
    "id": 0,
    "type": "kdeconnect.presenter",
    "body": {
        "stop": true
    }
}

  • dx: Number

    A double precision integer indicating a position delta on the X-axis.

  • dy: Number

    A double precision integer indicating a position delta on the Y-axis.

  • stop: Boolean

    Stop controlling the virtual pointer.

RunCommand Plugin

The RunCommand plugin allows defining and executing remote commands.

References

Packets

kdeconnect.runcommand

This packet is a list of available commands.

{
    "id": 0,
    "type": "kdeconnect.runcommand",
    "body": {
        "commandList": "{\"command-id1\": {\"name\": \"Command\",\"command\": \"/path/to/command1\"}}"
    }
}

  • commandList: String 🔒

    A serialized dictionary of commands that the device offers. The key is sent in a kdeconnect.runcommand.request packet to execute its corresponding command. Each value has a name field and a command field.

kdeconnect.runcommand.request

This packet is a runcommand status update.

{
    "id": 0,
    "type": "kdeconnect.runcommand.request",
    "body": {
        "key": "bea9fb3e-0c80-4d05-afdc-6a8f4156bc03"
    }
}

{
    "id": 0,
    "type": "kdeconnect.runcommand.request",
    "body": {
        "requestCommandList": true
    }
}

  • key: String

    If the packet body contains this field it is a request to execute the command with the ID key.

  • requestCommandList: Boolean

    If the packet body contains this field it is a request for the command list.

SFTP Plugin

The SFTP plugin enables secure file sharing with SFTP.

References

Packets

kdeconnect.sftp

This packet contains SFTP login information.

{
    "id": 0,
    "type": "kdeconnect.sftp",
    "body": {
        "ip": "192.168.1.71",
        "port": 1743,
        "user": "kdeconnect",
        "password": "UzcNCrI7T668JyxUFjOxQncBPNcO",
        "path": "/storage/emulated/0",
        "multiPaths": [
            "/storage/0000-0000",
            "/storage/0000-0000/DCIM/Camera",
            "/storage/emulated/0",
            "/storage/emulated/0/DCIM/Camera"
        ],
        "pathNames": [
            "SD Card",
            "Camera Pictures (SD Card)",
            "All files",
            "Camera pictures"
        ]
    }
}

  • errorMessage: String

    An error message.

  • ip: String 🔒

    The host address.

  • port: Number 🔒

    The host port.

  • user: String 🔒

    The user. Currently always kdeconnect.

  • password: String 🔒

    The one-time password. Deprecated; use private key authentication via the TLS certificate.

  • path: String 🔒

    The base path of the remote server. This should generally only be used as a fallback if the multiPaths field is missing.

  • multiPaths: Array of String 🔒

    An ordered list of paths for the remote server. Usually contains at least a ‘root’ directory and a path the the camera folder, but may contain additional paths to external storage devices.

  • pathNames: Array of String 🔒

    An ordered list of names associated with the paths in multiPaths, in the same order.

kdeconnect.sftp.request

This packet is a request to start SFTP.

{
    "id": 0,
    "type": "kdeconnect.sftp.request",
    "body": {
        "startBrowsing": true
    }
}

  • startBrowsing: Boolean 🔒

    A request for the remote device to prepare for SFTP and respond with a kdeconnect.sftp packet.

Share Plugin

The Share plugin allows sharing files, text content and URLs.

References

Packets

kdeconnect.share.request

This packet is an upload request.

{
    "id": 0,
    "type": "kdeconnect.share.request",
    "body": {
        "filename": "image.png"
    },
    "payloadSize": 882,
    "payloadInfo": {
        "port": 1739
    }
}

{
    "id": 0,
    "type": "kdeconnect.share.request",
    "body": {
        "text": "Some text"
    }
}

{
    "id": 0,
    "type": "kdeconnect.share.request",
    "body": {
        "url": "https://kdeconnect.kde.org"
    }
}

  • filename: String

    Name of the file being transferred. If the packet contains this field, it will be accompanied by payload transfer information.

  • creationTime: Number

    Creation time of the file being transferred as a UNIX epoch timestamp (ms).

  • lastModified: Number

    Modification time of the file being transferred as a UNIX epoch timestamp (ms).

  • open: Boolean

    Whether a received file should be opened when the transfer completes.

  • numberOfFiles: Number

    Number of files in a composite file transfer.

  • totalPayloadSize: Number

    Total size in bytes of a composite file transfer.

  • text: String

    Text content being shared. The receiving device decides how to present to text to the user.

  • url: String

    URL being shared. The receiving device will typically open the URL with the default handler for the URI scheme.

kdeconnect.share.request.update

This packet is the metadata for a multi-file transfer. By convention it is sent in advance of the packets containing the payload, which will include the same fields, potentially with updated totals.

{
    "id": 0,
    "type": "kdeconnect.share.request.update",
    "body": {
        "numberOfFiles": 1,
        "totalPayloadSize": 4096
    }
}

{
    "id": 0,
    "type": "kdeconnect.share.request.update",
    "body": {
        "numberOfFiles": 2,
        "totalPayloadSize": 8192
    }
}

  • numberOfFiles: Number

    Number of files in a multi-file transfer.

  • totalPayloadSize: Number

    Total size in bytes of a multi-file transfer.

SMS Plugin

The SMS plugin allows sending and receiving SMS/MMS messages.

References

Packets

kdeconnect.sms.attachment_file

This packet is a message attachment transfer.

{
    "id": 0,
    "type": "kdeconnect.sms.attachment_file",
    "body": {
        "filename": "image.png"
    },
    "payloadSize": 882,
    "payloadTransferInfo": {
        "port": 1739
    }
}

  • filename: String 🔒

    The name of the file being transferred.

kdeconnect.sms.messages

This packet is a list of messages.

{
    "id": 0,
    "type": "kdeconnect.sms.messages",
    "body": {
        "messages": [
            {
                "addresses": [
                    {
                        "address": "+1-234-567-8912"
                    }
                ],
                "attachments": [
                    {
                        "part_id": 190,
                        "mime_type": "image/jpeg",
                        "encoded_thumbnail": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAIAAAB7GkOtAAAACXBIWXMAAC4jAAAuIwF4pT92AAAAB3RJTUUH5AkCAgMHUNVLwAAAAxFJREFUeNrtwYEAAAAAw6D5U1/hAFUBAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADAbwK0AAH/2ARQAAAAAElFTkSuQmCC",
                        "unique_identifier": "PART_1624666113891_image000000.jpg"
                    }
                ],
                "body": "Thread 1, Message 2",
                "date": 2,
                "type": 2,
                "read": 1,
                "thread_id": 1,
                "_id": 2,
                "sub_id": 1,
                "event": 1
            },
            {
                "addresses": [
                    {
                        "address": "+1-234-567-8914"
                    }
                ],
                "body": "Message one",
                "date": 3,
                "type": 2,
                "read": 1,
                "thread_id": 2,
                "_id": 3,
                "sub_id": 1,
                "event": 1
            }
        ],
        "version": 2
    }
}

  • messages: Array of Message 🔒

    A list of messages.

    • Message (Object)

      A message object.

      • _id: Number 🔒

        The message ID.

      • addresses: Array of Address 🔒

        A list of participating contacts. If the message is incoming, the first Address will be the sender. If the message is outgoing, every Address will be a recipient.

        • Address (Object)

          An object representing a phone number or other contact method.

          • address: String

            A free-form address string. Usually a phone number or e-mail address.

      • attachments: Array of Attachment

        A list of message attachments.

        • Attachment (Object)

          A file attachment. Send the part_id and unique_identifier with a kdeconnect.sms.request_attachment packet to transfer the full file.

          • part_id: Number 🔒

            The ID of the attachment.

          • mime_type: String 🔒

            The mime-type of the attachment.

          • encoded_thumbnail: String 🔒

            A base64 encoded preview of the attachment.

          • unique_identifier: String 🔒

            Unique name of the file.

      • body: String

        The message body.

      • date: Number 🔒

        A UNIX epoch timestamp (ms) for the message.

      • event: Number

        The event type. 1 for ‘text’, 2 for ‘multi-target’.

      • read: Number

        enum: 0|1

        Whether the message is read or not.

      • sub_id: Number

        range: Unrestricted

        The SIM card or subscription ID.

      • thread_id: Number 🔒

        range: Unrestricted

        The thread ID.

      • type: Number 🔒

        range: 0–6

        The message status. Typically either 1 (inbox) or 2 (sent). See Android’s Telephony.TextBasedSmsColumns message type enumeration.

  • version: Number

    enum: 2

    The version of SMS protocol in use.

kdeconnect.sms.request

This packet is a request to send an SMS/MMS message.

{
    "id": 0,
    "type": "kdeconnect.sms.request",
    "body": {
        "addresses": [
            {
                "address": "+1-234-567-8901"
            }
        ],
        "attachments": [
            {
                "fileName": "image.jpeg",
                "base64EncodeFile": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAIAAAB7GkOtAAAACXBIWXMAAC4jAAAuIwF4pT92AAAAB3RJTUUH5AkCAgMHUNVLwAAAAxFJREFUeNrtwYEAAAAAw6D5U1/hAFUBAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADAbwK0AAH/2ARQAAAAAElFTkSuQmCC",
                "mimeType": "image/jpeg"
            }
        ],
        "messageBody": "Outgoing message",
        "subID": 1,
        "version": 2
    }
}

  • addresses: Array of Address 🔒

    A list of target contacts.

    • Address (Object)

      An object representing a phone number or other contact method.

      • address: String

        A free-form address string. Usually a phone number or e-mail address.

  • attachments: Array of Outgoing Attachment

    None

    • Outgoing Attachment (Object)

      None

      • fileName: String

        A file name.

      • base64EncodedFile: String

        Base64 encoded data.

      • mimeType: String

        A mime-type string.

  • messageBody: String 🔒

    None

  • subID: Number

    The SIM card or account to send with.

  • version: Number

    enum: 2

    The version of SMS protocol in use.

kdeconnect.sms.request_attachment

This packet is a request for a message attachment.

{
    "id": 0,
    "type": "kdeconnect.sms.request_attachment",
    "body": {
        "part_id": 190,
        "unique_identifier": "PART_1624666113891_image000000.jpg"
    }
}

  • part_id: Number 🔒

    The ID of the attachment.

  • unique_identifier: String 🔒

    Unique name of the file.

kdeconnect.sms.request_conversation

This packet is a request for messages from a thread.

{
    "id": 0,
    "type": "kdeconnect.sms.request_conversation",
    "body": {
        "threadID": 42
    }
}

{
    "id": 0,
    "type": "kdeconnect.sms.request_conversation",
    "body": {
        "threadID": 42,
        "rangeStartTimestamp": 1643990699000,
        "numberToRequest": 10
    }
}

  • threadID: Number 🔒

    range: Unrestricted

    The thread ID.

  • rangeStartTimestamp: Number

    range: Unrestricted

    UNIX epoch timestamp (ms) for the earliest message.

  • numberToRequest: Number

    range: Unrestricted

    The maximum number of messages to return.

kdeconnect.sms.request_conversations

This packet is a request for the latest message in each thread.

{
    "id": 0,
    "type": "kdeconnect.sms.request_conversations",
    "body": {}
}

This packet has no body fields.

SystemVolume Plugin

The SystemVolume plugin allows sharing volume controls between devices.

References

Packets

kdeconnect.systemvolume

This packet is a mixer stream state update.

{
    "id": 0,
    "type": "kdeconnect.systemvolume",
    "body": {
        "sinkList": [
            {
                "name": "alsa_output.pci-0000_00_1b.0.analog-stereo",
                "description": "Built-in Audio Analog Stereo",
                "muted": false,
                "volume": 32768,
                "maxVolume": 65536,
                "enabled": false
            }
        ]
    }
}

{
    "id": 0,
    "type": "kdeconnect.systemvolume",
    "body": {
        "name": "alsa_output.pci-0000_00_1b.0.analog-stereo",
        "volume": 49,
        "muted": false,
        "enabled": true
    }
}

  • sinkList: Array of Stream

    The list of audio streams.

    • Stream (Object)

      An audio stream object

      • name: String 🔒

        The stream name.

      • description: String 🔒

        The stream display name.

      • enabled: Boolean

        Whether the stream is enabled.

      • muted: Boolean 🔒

        Whether the stream is muted.

      • maxVolume: Number

        The stream max volume level.

      • volume: Number 🔒

        The stream volume level.

  • name: String

    The stream name.

  • enabled: Boolean

    Whether the stream is enabled.

  • muted: Boolean

    Whether the stream is muted.

  • volume: Number

    The stream volume level.

kdeconnect.systemvolume.request

This packet is a audio stream request. It is used to request both the list of streams and changes to those streams.

{
    "id": 0,
    "type": "kdeconnect.systemvolume.request",
    "body": {
        "requestSinks": true
    }
}

{
    "id": 0,
    "type": "kdeconnect.systemvolume.request",
    "body": {
        "name": "alsa_output.pci-0000_00_1b.0.analog-stereo",
        "volume": 49,
        "muted": false,
        "enabled": true
    }
}

  • requestSinks: Boolean

    Indicates this is a request for the stream list.

  • name: String

    The name of a stream. If the packet contains this field, it is a request to adjust a stream.

  • enabled: Boolean

    Indicates the stream should become the active default. Always true if present.

  • muted: Boolean

    The requested mute state.

  • volume: Number

    range: Unrestricted

    The requested volume. The maximum value is provided by the maxVolume field of the stream.

Telephony Plugin

The Telephony plugin allows notification of events such as incoming or missed calls.

References

Packets

kdeconnect.telephony

This packet is a telephony event, such as the phone ringing.

Note that both the sms event type and the messageBody field are deprecated in favor of the SMS plugin.

{
    "id": 0,
    "type": "kdeconnect.telephony",
    "body": {
        "event": "talking",
        "contactName": "John Smith",
        "phoneNumber": "555-555-5555",
        "phoneThumbnail": "<base64 encoded JPEG>"
    }
}

{
    "id": 0,
    "type": "kdeconnect.telephony",
    "body": {
        "event": "talking",
        "contactName": "John Smith",
        "phoneNumber": "555-555-5555",
        "isCancel": true
    }
}

{
    "id": 0,
    "type": "kdeconnect.telephony",
    "body": {
        "event": "sms",
        "contactName": "John Smith",
        "messageBody": "A text message",
        "phoneNumber": "555-555-5555",
        "phoneThumbnail": "<base64 encoded JPEG>"
    }
}

  • event: String 🔒

    enum: 'missedCall'|'ringing'|'talking'|'sms'

    None

  • contactName: String

    The contact name associated with the event.

  • messageBody: String

    ⚠️ Deprecated: The message text associated with the event.

  • phoneNumber: String

    The phone number associated with the event.

  • phoneThumbnail: String

    base64 encoded JPEG.

  • isCancel: Boolean

    If event has stopped.

kdeconnect.telephony.request_mute

This packet is sent to request the ringer be muted.

{
    "id": 0,
    "type": "kdeconnect.telephony.request_mute",
    "body": {}
}

This packet has no body fields.

Appendix

Data Types

These are the basic data types in the KDE Connect protocol, as described by the JSON Schema specification. Note that the integer type defined in some versions of JSON Schema is never used.

Boolean

A logical data type that can have only the values true or false.

Number

A numeric data type in the double-precision 64-bit floating point format (IEEE 754).

String

A null-terminated sequence of UTF-8 encoded bytes.

Array

An ordered collection of values.

Object

A mapping collection of string keys to values.

Null

The intentional absence of any object value. Note that this type is currently unused in the protocol and reserved for future use.

Symbols

  • ⚠️ Deprecated

    Clients are free to ignore these packets and fields, and encouraged to stop using them when possible.

  • 🔒 Required

    Packets missing these fields may be ignored or result in undefined behaviour.

References