Skip to main content
Plural Automation is a dedicated server-side frame that runs independently of your Avatar or robot frame. While your Avatar frame handles the conversation the user sees, the Automation frame executes logic, API calls, and Knowledge Base queries in the background — similar to how tools like Microsoft Power Automate or Pipedream run server-side workflows. The two frames communicate with each other using the IoT Trigger element or the Robot-to-Robot Command element. Use Plural Automation to offload heavy processing (such as chaining multiple API calls or running a Knowledge Base query) from the Avatar frame, keeping the user-facing conversation fast and responsive.
Working with Plural Automation is recommended for users comfortable with API calls and basic scripting. Familiarity with automation tools such as Microsoft Power Automate or Pipedream is helpful.
Plural Automation frames only run when your account has GOs available. Keep your GO balance topped up to avoid automation failures.

​
Create a Plural Automation frame

1

Click the + symbol

In the upper-left corner of the Plural canvas, click the + symbol to open the frame creation menu.
2

Select Plural Automation

Choose Plural Automation from the menu. A new, separate frame appears on the canvas alongside your existing Avatar or robot frame.
3

Add elements to the Automation frame

Right-click on the white area of the Automation frame and add elements as usual — Custom Script, Custom API Request, Knowledge Base, Set User Attributes & Variables, and so on.

​
Communication methods between frames

There are two ways for your Avatar frame and your Automation frame to exchange control and data.

​
Method 1 — IoT Trigger

Add an IoT Trigger element to the Automation frame as its entry point. When your Avatar frame calls the IoT Trigger’s URL (using a Custom API Request element), the Automation frame wakes up, runs its logic, and can return variables back to the Avatar frame.

​
Example: Avatar frame calls an Automation IoT Trigger

In this example, the Automation frame has an IoT Trigger that, when called, sets a variable (answer = "Hello Avatar") and returns it to the Avatar frame.
1

Get the IoT Trigger URLs and token

Click the IoT Trigger element in the Automation frame to open its sidebar. Copy the Live URL, Test URL, and Auth Token using the sidebar buttons.
2

Configure the API Call in the Avatar frame

Open the Custom API Request element in your Avatar frame. Paste the IoT Trigger URL as the request URL and set the method to POST.
3

Add the Authorization header

In the Custom API Request sidebar, go to Header Assignments and add:
  • Name: Authorization
  • Value: Token <your_auth_token>
4

Pass the language parameter (if using Knowledge Base)

Append ?lang=#ATTRI/LanguageISO2 to the URL so the Automation frame knows which language to use:
https://dev.plural.io/api/robots/message/<trigger_id>?lang=#ATTRI/LanguageISO2
5

Retrieve the response variable

In the IoT Trigger sidebar of the Automation frame, open the Output tab and check the variable that the automation returns (for example, answer).In the Custom API Request sidebar of the Avatar frame, click Test Request to inspect the response JSON, then switch to the Attributes tab and map the JSON path to a variable name:
  • JSON path: $.answer
  • Variable name: automationAnswer
You can now use #ATTRI/automationAnswer in any downstream Avatar frame element.

​
Method 2 — Robot-to-Robot Command

Add a Robot-to-Robot Command element to your Avatar frame and connect its output directly to an element in the Automation frame. This creates a direct in-Plural connection without needing HTTP calls.
  • Use the Input tab of the Robot-to-Robot Command element to pass a variable from the Avatar frame to the Automation frame.
  • Use the Output tab to receive a variable back from the Automation frame into the Avatar frame once the automation completes.

​
Handling multilingual automation

The only element in an Automation frame that currently requires an explicit language parameter is the Knowledge Base. All other elements are language-agnostic. When calling an Automation frame from a Custom API Request element in your Avatar frame, always include the language suffix on the URL: 
https://dev.plural.io/api/robots/message/<trigger_id>?lang=#ATTRI/LanguageISO2
  • #ATTRI/LanguageISO2 — automatically passes the current project language at runtime.
  • You can also hard-code a specific language: ?lang=en for English or ?lang=de for German. Use the ISO 639-1 two-letter language code.

​
Debugging with the IoT Trigger test window

1

Switch the API call to the Test URL

In your Avatar frame’s Custom API Request element, replace the Live URL with the Test URL from the IoT Trigger sidebar.
2

Open the test window

In the Automation frame, click the IoT Trigger element and then click Show Test Window.
3

Trigger the flow

Run your Avatar flow as normal. When the Custom API Request fires, the Test Window displays the full execution log of the Automation frame, including variable values at each step, errors, and API call results.
4

Restore the Live URL when finished

Remember to switch the API call URL back to the Live URL before publishing to production.
Leave the Test Window open while iterating on your automation logic. Every triggered run appends its logs to the window, so you can compare runs side by side.

​
Passing variables between frames

Variables set inside an Automation frame are not automatically available in the Avatar frame. You must explicitly pass them back through the IoT Trigger’s Output tab or the Robot-to-Robot Command’s Output tab. Similarly, variables from the Avatar frame are not automatically visible in the Automation frame. Pass them in the request body of the Custom API Request call, then use a transformation rule on the IoT Trigger to map them to Automation frame variables.

​
Architecture overview

Avatar Frame                         Automation Frame
────────────────────────────         ──────────────────────────────
Save User Input (UserQuery)
        ↓
Custom API Request ─────────────────→ IoT Trigger
  POST <Live URL>                             ↓
  Body: { "query": "#ATTRI/UserQuery" }  Set Variable (answer)
  Header: Authorization: Token …                 ↓
        ↓                            (returns answer variable)
Map response → #ATTRI/answer
        ↓
Robot Says: #ATTRI/answer