From 71cc89bcf791b75717aba37551f7f7bb93924137 Mon Sep 17 00:00:00 2001
From: Wouter <33957974+wjtje@users.noreply.github.com>
Date: Tue, 4 Feb 2025 13:41:38 +0100
Subject: [PATCH] Added documentation about the shelly.script_event event type
 (#36992)

* Added documentation about the shell.script_event

* Added missing comma to improve the flow of the text

* Updated documentation about the new script event entity

* Added an example script which uses events

* Moved the script entity to the correct location in the shelly documentation

Signed-off-by: wjtje <33957974+wjtje@users.noreply.github.com>

---------

Signed-off-by: wjtje <33957974+wjtje@users.noreply.github.com>
---
 source/_integrations/shelly.markdown | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/source/_integrations/shelly.markdown b/source/_integrations/shelly.markdown
index 4f601660591..183424766a6 100644
--- a/source/_integrations/shelly.markdown
+++ b/source/_integrations/shelly.markdown
@@ -154,6 +154,24 @@ If the **BUTTON TYPE** of the switch connected to the device is set to `momentar
 
 If the **Input Mode** of the switch connected to the device is set to `Button`, the integration creates an event entity for this switch. You can use this entity in your automations.
 
+Each script which generates events using [Shelly.emitEvent()](https://shelly-api-docs.shelly.cloud/gen2/Scripts/ShellyScriptLanguageFeatures#shellyemitevent) also gets an corresponding event entity. This entity is disabled by default. After changing a script, it's required to manually reload the device before new event types show up.
+
+For example, the following script will emit an event every time an input (button or switch) on the device is changed.
+
+```javascript
+// Example shelly script
+function eventHandler(event, userdata) {
+  if (
+    typeof event.component === "string" &&
+    event.component.substring(0, 5) === "input"
+  ) {
+    let id = Number(event.component.substring(6));
+    Shelly.emitEvent("input_event", { id: id });
+  }
+}
+Shelly.addEventHandler(eventHandler);
+```
+
 ## Events
 
 If the **BUTTON TYPE** of the switch connected to the device is set to `momentary` or `detached switch`, integration fires events under the type `shelly.click` when the switch is used. You can use these events in your automations.