> ## Documentation Index
> Fetch the complete documentation index at: https://support.humanizing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IoT Trigger: Connect External Systems to Your Flow

> Pause your Plural flow and wait for an inbound HTTP request from an external device or service before continuing, with Auth Token security.

The IoT Trigger element pauses your flow at a specific point and waits for an external HTTP request to arrive before continuing. This lets you connect any internet-enabled device or service to your Plural flow — a smart coffee machine that signals when coffee is ready, a backend system that sends a visitor's name, a barcode scanner, or a custom integration that provides real-time data. When the trigger fires, the flow resumes and any data sent in the request body is available as flow variables.

## Add an IoT Trigger element

Right-click on an empty area of your canvas and select **IoT Trigger**. Click the element to open the sidebar where you find the generated URLs and authentication token.

## Sidebar reference

<ParamField path="Generated URL (Live URL)" type="string">
  The production endpoint your external system calls to trigger your real robot or Avatar. Use this URL in live deployments.
</ParamField>

<ParamField path="Test URL" type="string">
  A separate endpoint for development and testing. Calls to the Test URL are displayed in the **Test window** but do not trigger live devices.
</ParamField>

<ParamField path="Copy Auth Token" type="string">
  Copies the authorization token to your clipboard. Include this token in every request as the `Authorization` header value: `Token <YOUR_TOKEN>`.
</ParamField>

<ParamField path="Add transformation rule" type="object">
  Map a field from the incoming JSON request body to a Plural flow variable. Enter the JSON parameter name on the left and the target variable name on the right.
</ParamField>

<ParamField path="Show test window" type="button">
  Opens a live debug window that displays all incoming messages sent to the Test URL. You can also send test trigger messages directly from this window.
</ParamField>

## Trigger the IoT element via HTTP

Structure your HTTP request as follows:

```http theme={null}
POST <Generated URL or Test URL>
Authorization: Token <YOUR_TOKEN>
Content-Type: application/json

{
  "goToLocation": "Meetingroom"
}
```

<Steps>
  <Step title="Copy the URL">
    Click **Copy Live URL** (for production) or note the **Test URL** (for testing) in the IoT Trigger sidebar.
  </Step>

  <Step title="Copy the Auth Token">
    Click **Copy Auth Token** to copy your token to the clipboard.
  </Step>

  <Step title="Add the Authorization header">
    In your HTTP client (Postman, cURL, your backend code), add a header named `Authorization` with the value `Token <your_token>`.
  </Step>

  <Step title="Send a JSON body (optional)">
    Add any data you want to pass into the flow as a JSON body, for example `{ "goToLocation": "Meetingroom" }`.
  </Step>

  <Step title="Send the request">
    Submit the request. If you used the Test URL, the incoming payload appears in the **Show test window** panel in Plural.
  </Step>
</Steps>

## Authenticate without an Authorization header

If your system cannot set custom HTTP headers, pass the auth token as a URL query parameter instead:

```
https://dev.plural.io/api/robots/message/ebff59e1-...?auth=YOUR_AUTH
```

## Map request body fields to variables

Use the **Add transformation rule** panel to extract values from the request body and store them in Plural variables:

1. Enter the JSON parameter name from your request body (for example, `goToLocation`).
2. Enter the Plural variable name to store it in (for example, `desiredLocation`).

The variable is then available throughout the rest of your flow as `#ATTRI/desiredLocation`.

## Target a specific Avatar session

By default, triggering the IoT element fires on **all active Avatar sessions** running that project. To target a specific session:

<Steps>
  <Step title="Get the session ID">
    Retrieve the active session ID from your flow. Display it on a Media Designer slide or pass it to your backend at flow start using a Custom API Request element. The session ID changes with each new flow run.
  </Step>

  <Step title="Append the session parameter to the URL">
    Add `?session=<active_session_id>` to the webhook URL:

    ```
    https://dev.plural.io/api/robots/message/2357c733-...?session=<active_session_id>
    ```
  </Step>
</Steps>

Calling the URL without a `session` parameter triggers all active Avatar sessions. Calling it with an incorrect session ID triggers nothing.

## Debug with the test window

<Steps>
  <Step title="Open the test window">
    Click **Show test window** in the IoT Trigger sidebar.
  </Step>

  <Step title="Send a request to the Test URL">
    Use Postman, cURL, or any HTTP client to send a request to the **Test URL** (not the Live URL).
  </Step>

  <Step title="Inspect the log">
    The test window displays the full payload of each incoming message, including any variables set by transformation rules. This is especially useful when debugging [Plural Automation](/en/elements/plural-automation) frames.
  </Step>
</Steps>

<Note>
  The IoT Trigger operates independently from Human Detection triggers. Adding it to a flow does not interfere with proximity or face detection logic.
</Note>

## Use in Plural Automation

When placed inside a [Plural Automation](/en/elements/plural-automation) frame, the IoT Trigger acts as the entry point that starts the automation when called from an Avatar frame or an external system. See the [Plural Automation](/en/elements/plural-automation) page for a complete walkthrough.

## Multilingual automation

To run a Knowledge Base or other language-sensitive element in an automation frame in the user's current language, append `?lang=#ATTRI/LanguageISO2` to the IoT Trigger URL in your API call:

```
https://dev.plural.io/api/robots/message/<trigger_id>?lang=#ATTRI/LanguageISO2
```

You can also specify a language directly:

```
https://dev.plural.io/api/robots/message/<trigger_id>?lang=en
```