Skip to content

Events Sent

The plugin and Property Inspector can send different events to the Stream Deck application:

Event Description
setSettings Save data persistently for the action's instance.
getSettings Request the persistent data for the action's instance.
setGlobalSettings Save data securely and globally for the plugin.
getGlobalSettings Request the global persistent data.
openUrl Open an URL in the default browser.
logMessage Write a debug log to the logs file.

The plugin can send some additional events:

Event Description
setTitle Dynamically change the title of an instance of an action.
setImage Dynamically change the image displayed by an instance of an action.
showAlert Temporarily show an alert icon on the image displayed by an instance of an action.
showOk Temporarily show an OK checkmark icon on the image displayed by an instance of an action.
setState Change the state of the action's instance supporting multiple states.
switchToProfile Switch to one of the preconfigured read-only profiles.
sendToPropertyInspector Send a payload to the Property Inspector.

The Property Inspector can also send this event:

Event Description
sendToPlugin Send a payload to the plugin.

setSettings

The plugin and Property Inspector can save data persistently for the action's instance. This is done using the setSettings event:

var json = {
    "event": "setSettings",
    "context": opaqueValue,
    "payload": {<json data>}
};
Members Description
event setSettings
context An opaque value identifying the instance's action or Property Inspector. In the case of the Property Inspector, this value is received by the Property Inspector as parameter of the connectElgatoStreamDeckSocket function.
payload A json object which is persistently saved for the action's instance.

Note that when the plugin uses this API, the Property Inspector will automatically receive a didReceiveSettings callback with the new settings. Similarly when the Property Inspector uses this API, the plugin will automatically receive a didReceiveSettings callback with the new settings.

The setSettings API is available since Stream Deck 4.0 for the plugin. Starting with Stream Deck 4.1, this API is available from the Property Inspector.


getSettings

The plugin and Property Inspector can request the persistent data stored for the action's instance. This is done using the getSettings event:

var json = {
    "event": "getSettings",
    "context": opaqueValue
};
Members Description
event getSettings
context An opaque value identifying the instance's action or Property Inspector. In the case of the Property Inspector, this value is received by the Property Inspector as parameter of the connectElgatoStreamDeckSocket function.

The plugin or Property Inspector will receive asynchronously an event didReceiveSettings containing the settings for this action:

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

This API has been introduced in Stream Deck 4.1.


setGlobalSettings

The plugin and Property Inspector can save persistent data globally and not just to one instance of an action. This is done using the setGlobalSettings event:

var json = {
    "event": "setGlobalSettings",
    "context": opaqueValue,
    "payload": {<json data>}
};
Members Description
event setGlobalSettings
context An opaque value identifying the plugin (inPluginUUID) or the Property Inspector (inPropertyInspectorUUID). This value is received during the Registration procedure.
payload A json object which is persistently saved globally.

Note that when the plugin uses this API, the Property Inspector will automatically receive a didReceiveGlobalSettings callback with the new settings. Similarly when the Property Inspector uses this API, the plugin will automatically receive a didReceiveGlobalSettings callback with the new settings.

This API has been introduced in Stream Deck 4.1.


getGlobalSettings

The plugin and Property Inspector can request the global persistent data. This is done using the getGlobalSettings event:

var json = {
    "event": "getGlobalSettings",
    "context": opaqueValue
};
Members Description
event getGlobalSettings
context An opaque value identifying the plugin (inPluginUUID) or the Property Inspector (inPropertyInspectorUUID). This value is received during the Registration procedure.

The plugin or Property Inspector will receive asynchronously an event didReceiveGlobalSettings containing the global settings:

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

This API has been introduced in Stream Deck 4.1.


openUrl

The plugin and Property Inspector can tell the Stream Deck application to open an URL in the default browser using the openUrl event:

var json = {
    "event": "openUrl",
    "payload": {
        "url": "https://www.elgato.com"
    }
};
Members Description
event openUrl
payload A json object

The payload object contains the following members:

Payload Description
url An URL to open in the default browser.

logMessage

The plugin and Property Inspector can use the logMessage event to write a debug message to the logs file:

var json = {
    "event": "logMessage",
    "payload": {
        "message": "Hello World!"
    }
};
Members Description
event logMessage
payload A json object

The payload object contains the following members:

Payload Description
message A string to write to the logs file.

Logs are saved to disk per plugin in the folder ~/Library/Logs/StreamDeck/ on macOS and %appdata%\Roaming\Elgato\StreamDeck\logs\ on Windows. Note that the log files are rotated each time the Stream Deck application is relaunched.

This API has been introduced in Stream Deck 4.1.


setTitle

The plugin can send a setTitle event to the Stream Deck application to dynamically change the title displayed by an instance of an action. The json structure looks like:

var json = {
    "event": "setTitle",
    "context": opaqueValue,
    "payload": {
        "title": "MyTitle",
        "target": software, hardware or both
    }
};

Note: In order to show the title on your hardware or software, the Show Title checkbox in the Stream Deck window must be activated:

Activate Show Title

Members Description
event setTitle
context An opaque value identifying the instance's action you want to modify.
payload A json object

The payload object contains the following members:

Payload Description
title The title to display. If there is no title parameter, the title is reset to the title set by the user.
target Specify if you want to display the title on the hardware and software (0), only on the hardware (1) or only on the software (2). Default is 0.

setImage

The plugin can send a setImage event to the Stream Deck application to dynamically change the image displayed by an instance of an action. The json structure looks like:

var json = {
    "event": "setImage",
    "context": opaqueValue,
    "payload": {
        "image": <base64 encoded image>,
        "target": software, hardware or both
    }
};
Members Description
event setImage
context An opaque value identifying the instance's action you want to modify.
payload A json object

The payload object contains the following members:

Payload Description
image The image to display encoded in base64 with the image format declared in the mime type (PNG, JPEG, BMP, ...). If no image is passed, the image is reset to the default image from the manifest.
target Specify if you want to display the title on the hardware and software (0), only on the hardware (1) or only on the software (2). Default is 0.

Examples of base64 encoded images:

"data:image/png;base64,iVBORw0KGgoA..."
"data:image/jpg;base64,/9j/4AAQSkZJ..."
"data:image/bmp;base64,/9j/Qk32PAAA..."

showAlert

The plugin can send a showAlert event to the Stream Deck application to temporarily show an alert icon on the image displayed by an instance of an action. The json structure looks like:

var json = {
    "event": "showAlert",
    "context": opaqueValue,
};
Members Description
event showAlert
context An opaque value identifying the instance's action.

showOk

The plugin can send a showOk event to the Stream Deck application to temporarily show an OK checkmark icon on the image displayed by an instance of an action. The json structure looks like:

var json = {
    "event": "showOk",
    "context": opaqueValue,
};
Members Description
event showOk
context An opaque value identifying the instance's action.

setState

This function can be used by a plugin to dynamically change the state of an action supporting multiple states:

var json = {
    "event": "setState",
    "context": opaqueValue,
    "payload": {
        "state": 0-based integer
    }
};
Members Description
event setState
context An opaque value identifying the instance's action.
payload A json object

The payload object contains the following members:

Payload Description
state A 0-based integer value representing the state requested.

switchToProfile

The plugin can tell the Stream Deck application to switch to one of his preconfigured read-only profile using the switchToProfile event:

var json = {
    "event": "switchToProfile",
    "context": opaqueValue,
    "device": opaqueValue,
    "payload": {
        "profile": "ProfileName"
    }
};
Members Description
event switchToProfile
context An opaque value identifying the plugin. This value should be set to the PluginUUID received during the registration procedure.
device An opaque value identifying the device.
payload A json object

The payload object contains the following members:

Payload Description
profile The name of the profile to switch to. The name should be identical to the name provided in the manifest.json file.

Note that a plugin can only switch to read-only profiles that are declared in its manifest.json file. If the profile field is missing or empty, the Stream Deck application will switch back to the previously selected profile.


sendToPropertyInspector

The plugin can send a payload to the Property Inspector using the sendToPropertyInspector event:

var json = {
    "action": "com.elgato.example.action1",
    "event": "sendToPropertyInspector",
    "context": opaqueValue,
    "payload": {<json data>}
};
Members Description
action The action unique identifier.
event sendToPropertyInspector
context An opaque value identifying the instance's action.
payload A json object that will be received by the Property Inspector.

The Property Inspector will receive asynchronously an event sendToPropertyInspector containing the payload:

var json = {
  "action": "com.elgato.example.action1", 
  "event": "sendToPropertyInspector", 
  "context": opaqueValue, 
  "payload": {<json data>}
};

sendToPlugin

The Property Inspector can send a payload to the plugin using the sendToPlugin event:

var json = {
    "action": "com.elgato.example.action1",
    "event": "sendToPlugin",
    "context": opaqueValue,
    "payload": {<json data>}
};
Members Description
action The action unique identifier. If your plugin supports multiple actions, you should use this value to find out which action was triggered.
event sendToPlugin
context An opaque value identifying the Property Inspector. This value is received by the Property Inspector as parameter of the connectElgatoStreamDeckSocket function.
payload A json object that will be received by the plugin.

The plugin will receive asynchronously an event sendToPlugin containing the payload:

var json = {
  "action": "com.elgato.example.action1", 
  "event": "sendToPlugin", 
  "context": opaqueValue, 
  "payload": {<json data>}
};