Differences

This shows you the differences between two versions of the page.

--- indigo_2025.2_documentation:plugin_guide [2026/04/07 18:27] – created - external edit 127.0.0.1
+++ indigo_2025.2_documentation:plugin_guide [2026/05/04 23:49] (current) – [Plugin] davel17
@@ Line 1555: / Line 1555: @@
   * The recommended approach is to use an API key: the request must contain an "Authorization" HTTP header, the value of which is "Bearer API_KEY_HERE", where you substitute an API key that is generated from the [[https://www.indigodomo.com/account/authorizations|Authorizations page]] in the user's Indigo Account. This is also how OAuth is used to authenticate when using a external service like Alexa or Google Home.
-  * If for some reason you can't include the header, you may pass the API key as an additional GET argument on the URL (''?other=args&api-key=KEYHERE'')
+  * If for some reason you can't include the header, you may pass the API key as an additional GET argument on the URL (''https://myreflector.indigodomo.net/message/PLUGINID/actionId/?other=args&api-key=KEYHERE'')
+Plugin API scripting can be a great way to add useful features to your plugin. For example, you could create a path for an external script to communicate with your plugin to provide status information or fire a trigger. We have provided a complete example below.
 ==== Request ====
 As a reminder, here's how you specify an action in Actions.xml that is used only via an API (from another plugin such as the IWS plugin):
@@ Line 1565: / Line 1566: @@
 </Action>
 </code>
+Notice that the ''uiPath="hidden"'' attribute will keep the action from displaying in the Indigo UI, but it will still be callable by your users using the URL structure shown above. Using the hidden attribute is optional but it is recommended for actions that are meant to be used solely as an API (otherwise, they will appear in Indigo's list of available actions.
-And here's how an action method is defined in your plugin:
+Here's how an action method is defined in your plugin:
 <code>def handle_some_action(self, action, dev=None, callerWaitingForResult=None):
@@ Line 1639: / Line 1641: @@
 For long-running actions, one pattern would be to reply immediately with some kind of acknowledgement of the incoming message, then handle the processing asynchronously. As this approach would complete the HTTP request/response loop, if your caller needs some kind of status after processing you would need to handle that yourself.
+=== Examples ===
+Here is a generic example that includes all the necessary parts of a plugin API interaction.
+== Plugin ==
+Your plugin needs to define an Indigo Action to receive the data.
+<code>
+<Action id="handle_message" uiPath="hidden">
+    <Name>some message</Name>
+    <CallbackMethod>handle_some_action</CallbackMethod>
+</Action>
+</code>
+Your plugin needs to define a callback method to do something.
+<code>
+def handle_some_action(self, action, dev=None, callerWaitingForResult=None):
+    some_value = action.props["someKey"]  # this is from the incoming API request
+    some_other_value = action.props["someOtherKey"]
+    # the reply must be valid JSON or an indigoDict() object
+    reply = indigo.Dict()
+    reply["content"] = some_other_value * 2
+    reply["status_code"] = 200
+    return some_result
+</code>
+== The Request ==
+The caller needs to construct a valid request.
+<code>
+import httpx
+MY_API_KEY = "abcd1234efgh"  # obtained through the user's Indigo account
+MY_REFLECTOR = "someReflectorID"  # the name of the user's server machine on their Indigo account
+PLUGIN_ID = "com.something.myPlugin"
+ACTION_ID = "handle_message"  # The ID from Actions.xml (not an Action object ID number)
+# The payload must be valid JSON. The API does not support binary encoding and payloads should be of a reasonable size.
+payload = {
+    "someKey": 1,
+    "someOtherKey": 2,
+    "field3": 3,
+}
+my_url = "https://MY_REFLECTOR.indigodomo.net/message/PLUGIN_ID/ACTION_ID/?other=payload&api-key=MY_API_KEY"
+response = httpx.get(my_url, verify=False)
+print(f"{response.status_code}")
+print(f"{response.text}")
+</code>
+''my_url'' will contain the response of a successful call (if the action returns a response) or an error if the call was unsuccessful (error codes above). Using the above example, the resonse will include ''24,691,356'' or "someOtherKey" * 2.
 ===== Event and Message Flow =====
 Under some circumstances, the Indigo Server will send callbacks to your plugin based on events that take place. For example, if your plugin devices expose features like Turn On, Turn Off or Status Request, Indigo will send a callback to your plugin so you can take actions on these events. There are many different callbacks that can occur which are documented extensively in the [[https://github.com/IndigoDomotics/IndigoSDK/releases/tag/v2025.1|SDK]].