Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
indigo_2025.2_documentation:plugin_guide [2026/05/04 15:04] – [Request] davel17indigo_2025.2_documentation:plugin_guide [2026/05/04 23:49] (current) – [Plugin] davel17
Line 1557: Line 1557:
   * 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'')   * 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 ==== ==== 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): 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> </Action>
 </code> </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.+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.
  
 Here's how an action method is defined in your plugin: Here's how an action method is defined in your plugin:
Line 1640: 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. 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 ===== ===== 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]]. 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]].
  • /www/perceptive/wiki/data/attic/indigo_2025.2_documentation/plugin_guide.1777907088.txt.gz
  • Last modified: 2026/05/04 15:04
  • by davel17