Events Sent

Events the plugin can send to the Stream Deck application.

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.
​setFeedback​
Dynamically change properties of items on the Stream Deck + touch display.
​setFeedbackLayout​
Dynamically change the current layout for the Stream Deck + touch display.
​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 using the setSettings event:
{
    "event": "setSettings",
    "context": uniqueValue,
    "payload": {<json data>}
}
Members
Description
event
setSettings
context
A value to Identify the instance's action or Property Inspector. This value is received by the Property Inspector as a 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 using the getSettings event:
{
    "event": "getSettings",
    "context": uniqueValue
}
Members
Description
event
getSettings
context
A value to Identify 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:
{
  "action": "com.elgato.example.action1", 
  "event": "didReceiveSettings", 
  "context": uniqueValue, 
  "device": uniqueValue, 
  "payload": {
   "settings": {<json data>},
    "coordinates": {
      "column": 3, 
      "row": 1
    }, 
    "isInMultiAction": false
  }
}
setGlobalSettings
The plugin and Property Inspector can save persistent data globally. The data will be saved securely to the Keychain on macOS and the Credential Store on Windows. This API can be used to save tokens that should be available to every action in the plugin.
This is done using the setGlobalSettings event:
{
    "event": "setGlobalSettings",
    "context": uniqueValue,
    "payload": {<json data>}
}
Members
Description
event
setGlobalSettings
context
A value to Identify 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 persistent global data using the getGlobalSettings event:
{
    "event": "getGlobalSettings",
    "context": uniqueValue
}
Members
Description
event
getGlobalSettings
context
A value to Identify 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 didReceiveGlobalSettingsthe p containing the global settings:
{
  "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:
{
    "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:
{
 "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/ElgatoStreamDeck/ on macOS and %appdata%\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.
{
    "event": "setTitle",
    "context": uniqueValue,
    "payload": {
        "title": "MyTitle",
        "target": software, hardware or both,
        "state": 0-based integer
    }
}
Note: Show the title on your hardware or software using the Show Title checkbox in the Stream Deck window:
Title Styles
Members
Description
event
setTitle
context
A value to Identify 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.
state
A 0-based integer value representing the state of an action with multiple states. If not specified, the title is set to all states.
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.
{
    "event": "setImage",
    "context": uniqueValue,
    "payload": {
        "image": <base64 encoded image>,
        "target": software, hardware or both,
        "state": 0-based integer
    }
}
Members
Description
event
setImage
context
A value to Identify 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, ...). svg is also supported. If not provided, 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.
state
A 0-based integer value representing the state of an action with multiple states. If not specified, the image is set to all states.
Examples of base64 encoded images:
"data:image/png;base64,iVBORw0KGgoA..."
"data:image/jpg;base64,/9j/4AAQSkZJ..."
"data:image/bmp;base64,/9j/Qk32PAAA..."
Starting with Stream Deck 4.5.1, this API accepts svg images. Here is an example with an svg image:
{
 "event": "setImage",
 "context": context,
 "payload": {
  "image": "data:image/svg+xml;charset=utf8,<svg height=\"100\" width=\"100\"><circle cx=\"50\" cy=\"50\" r=\"40\" stroke=\"black\" stroke-width=\"3\" fill=\"red\" /></svg>",
  "target": 2
 }
}
setFeedback (SD+)
The plugin can send a setFeedback event to the Stream Deck application to dynamically change properties of items on the Stream Deck + touch display layout.
{
    "event": "setFeedback",
    "context": uniqueValue,
    "payload": {
        <key1>: <value1>,
        <key2>: <value2>,
        ...
    }
}
Members
Description
event
setFeedback
context
A value to Identify the instance's action you want to modify.
payload
A JSON object
The payload object contains one ore more key/value pairs defined as follows:
Payload
Description
key
The key is a name of the element in layout to be changed with given value
value
The value to be set in key named layout element
Examples
If your plugin uses the Indicator Layout, you can set the value of the title item by using the title key in the setFeedback payload.
{
  "title": "Example Title"
}
You can also set multiple properties at once with a single payload. The Indicator Layout has items with keys title, icon, value, and indicator.
{
  "title": "Example Title",
  "icon": "./path-to-icon/icon.svg",
  "value": "55",
  "indicator": { "value": 50, "enabled": true }
}
setFeedbackLayout (SD+)
The plugin can send a setFeedbackLayout event to the Stream Deck application to dynamically change the current Stream Deck + touch display layout. setFeedbackLayout can use the id of a built-in layout or a relative path to a custom layout JSON file. See Layouts for more information.
{
    "event": "setFeedbackLayout",
    "context": uniqueValue,
    "payload": {
        "layout": "$A0"
    }
}
The payload object contains the layout:
Payload
Description
layout
A predefined layout identifier or the relative path to a json file that contains a custom layout
Example
The default layout is defined in the manifest and use the following payload to switch to a predefined custom layout.
"payload": {
  "layout": "./path-to-layout/layout.json"
}
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.
{
    "event": "showAlert",
    "context": uniqueValue,
}
Members
Description
event
showAlert
context
A value to identify 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.
{
    "event": "showOk",
    "context": uniqueValue,
}
Members
Description
event
showOk
context
A value to identify the instance's action.
setState
This function can be used by a plugin to dynamically change the state of an action supporting multiple states:
{
    "event": "setState",
    "context": uniqueValue,
    "payload": {
        "state": 0-based integer
    }
}
Members
Description
event
setState
context
A value to identify 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:
{
    "event": "switchToProfile",
    "context": uniqueValue,
    "device": uniqueValue,
    "payload": {
        "profile": "ProfileName"
    }
}
Members
Description
event
switchToProfile
context
A value to Identify the plugin. This value should be set to the PluginUUID received during the registration procedure.
device
A value to identify 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 declared in its manifest.json file. If the profile field is missing or empty, the Stream Deck application will switch to the previously selected profile.
sendToPropertyInspector
The plugin can send a payload to the Property Inspector using the sendToPropertyInspector event:
{
 "action": "com.elgato.example.action1",
    "event": "sendToPropertyInspector",
    "context": uniqueValue,
    "payload": {<json data>}
}
Members
Description
action
The action's unique identifier.
event
sendToPropertyInspector
context
A value to identify 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:
{
  "action": "com.elgato.example.action1", 
  "event": "sendToPropertyInspector", 
  "context": uniqueValue, 
  "payload": {<json data>}
}
sendToPlugin
The Property Inspector can send a payload to the plugin using the sendToPlugin event:
{
    "action": "com.elgato.example.action1",
    "event": "sendToPlugin",
    "context": uniqueValue,
    "payload": {<json data>}
}
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
sendToPlugin
context
A value to Identify 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:
{
  "action": "com.elgato.example.action1", 
  "event": "sendToPlugin", 
  "context": uniqueValue, 
  "payload": {<json data>}
}

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.

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.
setFeedback	Dynamically change properties of items on the Stream Deck + touch display.
setFeedbackLayout	Dynamically change the current layout for the Stream Deck + touch display.
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.

Event	Description
sendToPlugin	Send a payload to the plugin.

Members	Description
event	setSettings
context	A value to Identify the instance's action or Property Inspector. This value is received by the Property Inspector as a parameter of the connectElgatoStreamDeckSocket function.
payload	A JSON object which is persistently saved for the action's instance.

Members	Description
event	getSettings
context	A value to Identify 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.

Members	Description
event	setGlobalSettings
context	A value to Identify 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.

Members	Description
event	getGlobalSettings
context	A value to Identify the plugin (inPluginUUID) or the Property Inspector (inPropertyInspectorUUID). This value is received during the Registration procedure.

Members	Description
event	openUrl
payload	A JSON object

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

Members	Description
event	logMessage
payload	A JSON object

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

Members	Description
event	setTitle
context	A value to Identify the instance's action you want to modify.
payload	A JSON object

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.
state	A 0-based integer value representing the state of an action with multiple states. If not specified, the title is set to all states.

Members	Description
event	setImage
context	A value to Identify the instance's action you want to modify.
payload	A JSON object

Payload	Description
image	The image to display encoded in base64 with the image format declared in the mime type (PNG, JPEG, BMP, ...). svg is also supported. If not provided, 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.
state	A 0-based integer value representing the state of an action with multiple states. If not specified, the image is set to all states.

Members	Description
event	setFeedback
context	A value to Identify the instance's action you want to modify.
payload	A JSON object

Payload	Description
key	The key is a name of the element in layout to be changed with given `value`
value	The value to be set in `key` named layout element

Payload	Description
layout	A predefined layout identifier or the relative path to a json file that contains a custom layout

Members	Description
event	showAlert
context	A value to identify the instance's action.

Members	Description
event	showOk
context	A value to identify the instance's action.

Members	Description
event	setState
context	A value to identify the instance's action.
payload	A JSON object

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

Members	Description
event	switchToProfile
context	A value to Identify the plugin. This value should be set to the PluginUUID received during the registration procedure.
device	A value to identify the device.
payload	A JSON object

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.

Members	Description
action	The action's unique identifier.
event	sendToPropertyInspector
context	A value to identify the instance's action.
payload	A JSON object that will be received by the Property Inspector.

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	sendToPlugin
context	A value to Identify 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.

Last modified 2mo ago