Events Received

Events the plugin can receive from the Stream Deck application.

Once a plugin is loaded by the Stream Deck application, and the user sets some keys to use the plugin, the plugin will receive some events. Similarly, when a Property Inspector is displayed, it will receive some events.

Both the plugin and the Property Inspector can receive these events:

Event	Description
didReceiveSettings	Event received after calling the getSettings API to retrieve the persistent data stored for the action.
didReceiveGlobalSettings	Event received after calling the getGlobalSettings API to retrieve the global persistent data.

The plugin may receive these additional events:

Event	Description
keyDown	When the user presses a key, the plugin will receive the keyDown event.
keyUp	When the user releases a key, the plugin will receive the keyUp event.
touchTap	When the user touches the display, the plugin will receive the touchTap event (SD+).
dialDown	When the user presses the encoder down, the plugin will receive the dialDown event (SD+).
dialUp	When the user releases a pressed encoder, the plugin will receive the dialUp event (SD+).
dialRotate	When the user rotates the encoder, the plugin will receive the dialRotate event (SD+).
willAppear	When an instance of an action is displayed on Stream Deck, for example, when the hardware is first plugged in or when a folder containing that action is entered, the plugin will receive a willAppear event.
willDisappear	When an instance of an action ceases to be displayed on Stream Deck, for example, when switching profiles or folders, the plugin will receive a willDisappear event.
titleParametersDidChange	When the user changes the title or title parameters, the plugin will receive a titleParametersDidChange event.
deviceDidConnect	When a device is plugged to the computer, the plugin will receive a deviceDidConnect event.
deviceDidDisconnect	When a device is unplugged from the computer, the plugin will receive a deviceDidDisconnect event.
applicationDidLaunch	When a monitored application is launched, the plugin will receive the applicationDidLaunch event.
applicationDidTerminate	When a monitored application is terminated, the plugin will receive the applicationDidTerminate event.
systemDidWakeUp	When the computer wakes up, the plugin will receive the systemDidWakeUp event.
didReceiveDeepLink	Occurs when Stream Deck receives a deep-link message intended for the plugin. The message is re-routed to the plugin, and provided as part of the payload.
propertyInspectorDidAppear	Event received when the Property Inspector appears in the Stream Deck user interface, for example, when selecting a new instance.
propertyInspectorDidDisappear	Event received when the Property Inspector is removed from the Stream Deck user interface, for example, when selecting a different instance.
sendToPlugin	Event received by the plugin when the Property Inspector uses the sendToPlugin event.

The Property Inspector may also receive these events:

Event	Description
sendToPropertyInspector	Event received by the Property Inspector when the plugin uses the sendToPropertyInspector event.

didReceiveSettings

The didReceiveSettings event is received after calling the getSettings API to retrieve the persistent data stored for the action.

{
  "action": "com.elgato.example.action1", 
  "event": "didReceiveSettings", 
  "context": uniqueValue, 
  "device": uniqueValue, 
  "payload": {
   "settings": {<json data>},
    "coordinates": {
      "column": 3, 
      "row": 1
    }, 
    "isInMultiAction": false
  }
}

Members	Description
action	The action's unique identifier.
event	didReceiveSettings
context	A value identifying the instance's action.
device	A value to identify the device.
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains persistently stored data.
coordinates	The coordinates of the action triggered.
state	Only set when the action has multiple states defined in its manifest.json. The 0-based value contains the current state of the action.
isInMultiAction	Boolean indicating if the action is inside a Multi-Action.

didReceiveGlobalSettings

The didReceiveGlobalSettings event is received after calling the getGlobalSettings API to retrieve the global persistent data stored for the plugin.

{
  "event": "didReceiveGlobalSettings", 
  "payload": {
   "settings": {<json data>}
  }
}

Members	Description
event	didReceiveGlobalSettings
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains persistently stored data.

didReceiveDeepLink

Available from Stream Deck 6.5 onwards.

Occurs when Stream Deck receives a deep-link message intended for the plugin. The message is re-routed to the plugin, and provided as part of the payload. One-way deep-link message can be routed to the plugin using the URL format:

streamdeck://plugins/message/<PLUGIN_UUID>/{MESSAGE}

{
    event: "didReceiveDeepLink",
    payload: {
        url: string
    }
}

Members	Description
event	didReceiveDeepLink
payload	A JSON object
payload.url	The deep-link URL, with the prefix omitted. For example the URL streamdeck://plugins/message/com.elgato.test/hello-world would result in a url of hello-world

touchTap (SD+)

When the user touches the display, the plugin will receive the touchTap event.

{
  "action": "com.elgato.example.action2",
  "event": "touchTap",
  "context": uniqueValue,
  "device": uniqueValue,
  "payload": {
    "settings": {<json data>},
    "controller": "Encoder",
    "coordinates": {
      "column": 3,
      "row": 0
    },
    "tapPos": [10, 20],
    "hold": false
  }
}

Members	Description
action	The action's unique identifier. If your plugin supports multiple actions, you should use this value to see which action was triggered.
event	touchTap
context	A value identifying the instance's action. You will need to pass this opaque value to several APIs like the setTitle API.
device	A value to identify the device.
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains data that you can set and are stored persistently.
controller	Encoder.
coordinates	The coordinates of the action triggered.
tapPos	The array which holds (x, y) coordinates as a position of tap inside of LCD slot associated with action.
hold	Boolean which is true when long tap happened

dialDown (SD+)

When the user presses the encoder down, the plugin will receive the dialDown event (SD+).

{
  "action": "com.elgato.example.action2",
  "event": "dialDown",
  "context": uniqueValue,
  "device": uniqueValue,
  "payload": {
    "controller": "Encoder",
    "settings": {<json data>},
    "coordinates": {
      "column": 0,
      "row": 0
    },
  }
}

Members	Description
action	The action's unique identifier. If your plugin supports multiple actions, you should use this value to see which action was triggered.
event	dialDown
context	A value identifying the instance's action. You will need to pass this opaque value to several APIs like the setTitle API.
device	A value to identify the device.
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains data that you can set and are stored persistently.
coordinates	The coordinates of the action triggered.
controller	Encoder.

dialUp (SD+)

When the user releases a pressed encoder, the plugin will receive the dialUp event (SD+).

{
  "action": "com.elgato.example.action2",
  "event": "dialUp",
  "context": uniqueValue,
  "device": uniqueValue,
  "payload": {
    "controller": "Encoder",
    "settings": {<json data>},
    "coordinates": {
      "column": 0,
      "row": 0
    },
  }
}

Members	Description
action	The action's unique identifier. If your plugin supports multiple actions, you should use this value to see which action was triggered.
event	dialUp
context	A value identifying the instance's action. You will need to pass this opaque value to several APIs like the setTitle API.
device	A value to identify the device.
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains data that you can set and are stored persistently.
coordinates	The coordinates of the action triggered.
controller	Encoder.

dialRotate (SD+)

When the user rotates the encoder, the plugin will receive the dialRotate event.

{
  "action": "com.elgato.example.action2",
  "event": "dialRotate",
  "context": uniqueValue,
  "device": uniqueValue,
  "payload": {
    "settings": {<json data>},
    "controller": "Encoder",
    "coordinates": {
      "column": 3,
      "row": 0
    },
    "ticks": -5,
    "pressed": false
  }
}

Members	Description
action	The action's unique identifier. If your plugin supports multiple actions, you should use this value to see which action was triggered.
event	dialRotate
context	A value identifying the instance's action. You will need to pass this opaque value to several APIs like the setTitle API.
device	A value to identify the device.
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains data that you can set and are stored persistently.
controller	Encoder.
coordinates	The coordinates of the action triggered.
ticks	The integer which holds the number of "ticks" on encoder rotation. Positive values are for clockwise rotation, negative values are for counterclockwise rotation, zero value is never happen
pressed	Boolean which is true on rotation when encoder pressed

keyDown

When the user presses a key, the plugin will receive the keyDown event.

{
    "action": "com.elgato.example.action1",
    "event": "keyDown",
    "context": uniqueValue,
    "device": uniqueValue,
    "payload": {
        "settings": {<json data>},
        "coordinates": {
            "column": 3, 
            "row": 1
        },
        "state": 0,
        "userDesiredState": 1,
        "isInMultiAction": false
    }
}

Members	Description
action	The action's unique identifier. If your plugin supports multiple actions, you should use this value to see which action was triggered.
event	keyDown
context	A value identifying the instance's action. You will need to pass this opaque value to several APIs like the setTitle API.
device	A value to identify the device.
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains data that you can set and are stored persistently.
coordinates	The coordinates of the action triggered.
state	Only set when the action has multiple states defined in its manifest.json. The 0-based value contains the current state of the action.
userDesiredState	Only set when the action is triggered with a specific value from a Multi-Action. For example, if the user sets the Game Capture Record action to be disabled in a Multi-Action, you would see the value 1. 0 and 1 are valid.
isInMultiAction	Boolean indicating if the action is inside a Multi-Action.

keyUp

When the user releases a key, the plugin will receive the keyUp event as a JSON structure like:

{
    "action": "com.elgato.example.action1",
    "event": "keyUp",
    "context": uniqueValue,
    "device": uniqueValue,
    "payload": {
        "settings": {<json data>},
        "coordinates": {
            "column": 3, 
            "row": 1
        },
        "state": 0,
        "userDesiredState": 1,
        "isInMultiAction": false
    }
}

Members	Description
action	The action's unique identifier. If your plugin supports multiple actions, you should use this value to find out which action was triggered.
event	keyUp
context	A value to identify the instance's action. You will need to pass this opaque value to several APIs like the setTitle API.
device	A value to identify the device.
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains data that you can set and is stored persistently.
coordinates	The coordinates of the action triggered.
state	Only set when the action has multiple states defined in its manifest.json. The 0-based value contains the current state of the action.
userDesiredState	Only set when the action is triggered with a specific value from a Multi-Action. For example, if the user sets the Game Capture Record action to be disabled in a Multi-Action, you would see the value 1. 0 and 1 are valid.
isInMultiAction	Boolean indicating if the action is inside a Multi-Action.

willAppear

When an instance of an action is displayed on Stream Deck, for example, when the hardware is first plugged in or when a folder containing that action is entered, the plugin will receive a willAppear event. You will see such an event when:

• the Stream Deck application is started

• the user switches between profiles

• the user sets a key to use your action

{
    "action": "com.elgato.example.action1",
    "event": "willAppear",
    "context": uniqueValue,
    "device": uniqueValue,
    "payload": {
        "settings": {<json data>},
        "coordinates": {
            "column": 3, 
            "row": 1
        },
        "controller": "Keypad"
        "state": 0,
        "isInMultiAction": false
    }
}

Members	Description
action	The action's unique identifier. If your plugin supports multiple actions, you should use this value to know which action was triggered.
event	willAppear
context	A value to identify the instance's action. You will need to pass this opaque value to several APIs like the setTitle API.
device	A value to identify the device.
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains data that you can set and are stored persistently.
coordinates	The coordinates of the action triggered.
controller	Defines the controller type the action is applicable to. Keypad refers to a standard action on a Stream Deck device, e.g. 1 of the 15 buttons on the Stream Deck MK.2, or a pedal on the Stream Deck Pedal, etc., whereas an Encoder refers to a dial / touchscreen on the Stream Deck+.
state	Only set when the action has multiple states defined in its manifest.json. The 0-based value contains the current state of the action.
isInMultiAction	Boolean indicating if the action is inside a Multi-Action.

willDisappear

When an instance of an action ceases to be displayed on Stream Deck, for example, when switching profiles or folders, the plugin will receive a willDisappear event. You will see such an event when:

• the user switches between profiles

• the user deletes an action

{
    "action": "com.elgato.example.action1",
    "event": "willDisappear",
    "context": uniqueValue,
    "device": uniqueValue,
    "payload": {
        "settings": {<json data>},
        "coordinates": {
           "column": 3, 
           "row": 1
        },
        "controller": "Encoder"
        "state": 0,
        "isInMultiAction": false
    }
}

Members	Description
action	The action's unique identifier. If your plugin supports multiple actions, you should use this value to find out which action was triggered.
event	willDisappear
context	A value to identify the instance's action. You will need to pass this opaque value to several APIs like the setTitle API.
device	A value to identify the device.
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains data that you can set and is stored persistently.
coordinates	The coordinates of the action triggered.
controller	Defines the controller type the action is applicable to. Keypad refers to a standard action on a Stream Deck device, e.g. 1 of the 15 buttons on the Stream Deck MK.2, or a pedal on the Stream Deck Pedal, etc., whereas an Encoder refers to a dial / touchscreen on the Stream Deck+.
state	Only set when the action has multiple states defined in its manifest.json. The 0-based value contains the current state of the action.
isInMultiAction	Boolean indicating if the action is inside a Multi-Action.

titleParametersDidChange

When the user changes the title or title parameters of the instance of an action, the plugin will receive a titleParametersDidChange event.

{
  "action": "com.elgato.example.action1", 
  "event": "titleParametersDidChange", 
  "context": "uniqueValue", 
  "device": "uniqueValue", 
  "payload": {
    "coordinates": {
      "column": 3, 
      "row": 1
    }, 
    "settings": {<json data>}, 
    "state": 0, 
    "title": "", 
    "titleParameters": {
      "fontFamily": "", 
      "fontSize": 12, 
      "fontStyle": "", 
      "fontUnderline": false, 
      "showTitle": true, 
      "titleAlignment": "bottom", 
      "titleColor": "#ffffff"
    }
  }
}

Members	Description
action	The action's unique identifier. If your plugin supports multiple actions, you should use this value to find out which action was triggered.
event	titleParametersDidChange
context	A value to identify the instance's action. You will need to pass this value to several APIs like the setTitle API.
device	A value to identify the device.
payload	A JSON object

The payload object contains the following members:

Payload	Description
settings	This JSON object contains data that you can set and is stored persistently.
coordinates	The coordinates of the action triggered.
state	This value indicates which state of the action the title or title parameters have been changed.
title	The new title.
titleParameters	A JSON object describing the new title parameters.

The titleParameters object contains the following members:

TitleParameters	Description
fontFamily	The font family for the title.
fontSize	The font size for the title.
fontStyle	The font style for the title.
fontUnderline	Boolean indicating an underline under the title.
showTitle	Boolean indicating if the title is visible.
titleAlignment	Vertical alignment of the title. Possible values are "top", "bottom" and "middle".
titleColor	Title color.

deviceDidConnect

When a device is plugged into the computer, the plugin will receive a deviceDidConnect event.

{
 "event": "deviceDidConnect",
    "device": uniqueValue,
     "deviceInfo": {
        "name": "Device Name",
        "type": 0,
         "size": {
            "columns": 5,
            "rows": 3
        }
    },
}

Members	Description
event	deviceDidConnect
device	A value to identify the device.
deviceInfo	A JSON object containing information about the device.

The deviceInfo object contains the following members:

device	Description
type	Type of device. Possible values are kESDSDKDeviceType_StreamDeck (0), kESDSDKDeviceType_StreamDeckMini (1), kESDSDKDeviceType_StreamDeckXL (2), kESDSDKDeviceType_StreamDeckMobile (3) and kESDSDKDeviceType_CorsairGKeys (4).
size	The number of columns and rows of keys that the device owns.
name	The name of the device set by the user.

deviceDidDisconnect

When a device is unplugged from the computer, the plugin will receive a deviceDidDisconnect event.

{
 "event": "deviceDidDisconnect",
    "device": uniqueValue
};

Members	Description
event	deviceDidDisconnect
device	A value to identify the device.

applicationDidLaunch

A plugin can request in its manifest.json to be notified when some applications are launched or terminated. The manifest.json should contain an ApplicationsToMonitor object specifying the list of application identifiers to monitor. On macOS, the application bundle identifier is used while the exe filename is used on Windows. For example, the Apple Mail sample plugin uses the following:

"ApplicationsToMonitor": {
 "mac": [
  "com.apple.mail"
 ]
]

When a monitored application is launched, the plugin will receive the applicationDidLaunch event.

{
    "event": "applicationDidLaunch",
    "payload" : {
        "application": "com.apple.mail"
    }
}

Members	Description
event	applicationDidLaunch
payload	A JSON object

The payload object contains the following members:

Payload	Description
application	The identifier of the application that has been launched.

applicationDidTerminate

A plugin can request in its manifest.json to be notified when some applications are launched or terminated. The manifest.json should contain an ApplicationsToMonitor object specifying the list of application identifiers to monitor. On macOS, the application bundle identifier is used while the exe filename is used on Windows. For example, the Apple Mail sample plugin uses the following:

"ApplicationsToMonitor": {
 "mac": [
  "com.apple.mail"
 ]
]

When a monitored application is terminated, the plugin will receive the applicationDidTerminate event.

{
    "event": "applicationDidTerminate",
    "payload" : {
        "application": "com.apple.mail"
    }
}

Members	Description
event	applicationDidTerminate
payload	A JSON object

The payload object contains the following members:

Payload	Description
application	The identifier of the application that has been launched.

systemDidWakeUp

When the computer wakes up, the plugin will receive the systemDidWakeUp event.

{
 "event": "systemDidWakeUp"
}

Members	Description
event	systemDidWakeUp

Several important points to note:

• A plugin could get multiple systemDidWakeUp events when waking up the computer

• When the plugin receives the systemDidWakeUp event, there is no guarantee that the devices are available

This API has been introduced in Stream Deck 4.3.

propertyInspectorDidAppear

The plugin will receive a propertyInspectorDidAppear event when the Property Inspector appears:

{
  "action": "com.elgato.example.action1", 
  "event": "propertyInspectorDidAppear", 
  "context": uniqueValue, 
  "device": uniqueValue
}

Members	Description
action	The action's unique identifier.
event	propertyInspectorDidAppear
context	A value to identify the instance's action.
device	A value to identify the device.

This API has been introduced in Stream Deck 4.1.

propertyInspectorDidDisappear

The plugin will receive a propertyInspectorDidDisappear event when the Property Inspector disappears:

{
  "action": "com.elgato.example.action1", 
  "event": "propertyInspectorDidDisappear", 
  "context": uniqueValue, 
  "device": uniqueValue
}

Members	Description
action	The action's unique identifier.
event	propertyInspectorDidDisappear
context	A value to identify the instance's action.
device	A value to identify the device.

sendToPlugin

The plugin will receive a sendToPlugin event when the Property Inspector sends a sendToPlugin event:

{
  "action": "com.elgato.example.action1", 
  "event": "sendToPlugin", 
  "context": uniqueValue, 
  "payload": {<json data>}
}

sendToPropertyInspector

The Property Inspector will receive a sendToPropertyInspector event when the plugin sends a sendToPropertyInspector event:

{
  "action": "com.elgato.example.action1", 
  "event": "sendToPropertyInspector", 
  "context": uniqueValue, 
  "payload": {<json data>}
}