# Arguments

Flow card arguments are passed as an input to your Flow card, users can pick the argument values when creating or editing a Flow.

Arguments must have a `type` that determines how they are shown. For example, a `dropdown` argument allows a user to pick one value from a predefined set of options, whereas a `text` argument shows an input field.

{% hint style="info" %}
Don't overuse arguments! In our experience, Flow cards with just one or two arguments are the most popular.
{% endhint %}

## Argument Types

The following are all available argument types that you can use in your Flow cards and the options that you can use with those types.

### Text

`"type": "text"`

Regular text input. Text, Number and Boolean tokens can be dropped in this field as well.

![](https://998911913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPk9cn4V7WnnKt7fbry%2Fuploads%2Fgit-blob-c6df971c9556e1e7862c63bf82d995b457613711%2FText.png?alt=media)

**Attributes**

| Name        | Type                                                                                       | Description                | Example                                             |
| ----------- | ------------------------------------------------------------------------------------------ | -------------------------- | --------------------------------------------------- |
| placeholder | [translation object](https://apps.developer.homey.app/the-basics/app/internationalization) | Text to show without input | `{ "en": "Hello, World!", "nl": "Hallo, Wereld!" }` |
| title       | [translation object](https://apps.developer.homey.app/the-basics/app/internationalization) | Text shown above argument  | `{ "en": "Sentence", nl": "Zin" }`                  |

**Example**

{% code title="/.homeycompose/flow/actions/greet.json" %}

```javascript
{
  "title": { "en": "Say a greeting" },
  "titleFormatted": { "en": "Say [[sentence]]" },
  "args": [
    {
      "type": "text",
      "name": "sentence",
      "title": { "en": "Sentence" },
      "placeholder": { "en": "Hello!" }
    }
  ]
}
```

{% endcode %}

### Autocomplete

`"type": "autocomplete"`

This is the same as a text input, but with an additional autocomplete popup. The returned value when the card is run, is one of the objects provided in the autocomplete array. In order to provide autocomplete results you need to register an autocomplete listener for the Flow card with [`FlowCard#registerArgumentAutocompleteListener()`](https://apps-sdk-v3.developer.homey.app/FlowCard.html#registerArgumentAutocompleteListener) or [`FlowCard#register_argument_autocomplete_listener()`](https://python-apps-sdk-v3.developer.homey.app/flow_card.html#homey.flow_card.FlowCard.register_argument_autocomplete_listener)

![](https://998911913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPk9cn4V7WnnKt7fbry%2Fuploads%2Fgit-blob-2768db29f0ea72fb4061f0a436b72a992db6fd8f%2FAutocomplete.png?alt=media)

**Attributes**

| Name        | Type                                                                                       | Description                | Example                                      |
| ----------- | ------------------------------------------------------------------------------------------ | -------------------------- | -------------------------------------------- |
| placeholder | [translation object](https://apps.developer.homey.app/the-basics/app/internationalization) | Text to show without input | `{ "en": "YouTube", "nl": "Dumpert" }`       |
| title       | [translation object](https://apps.developer.homey.app/the-basics/app/internationalization) | Text shown above argument  | `{ "en": "Application", nl": "Applicatie" }` |

**Example**

{% code title="/.homeycompose/flow/actions/play\_artist.json" %}

```javascript
{
  "title": { "en": "Play an Artist" },
  "titleFormatted": { "en": "Play an Artist [[artist]]" },
  "args": [
    {
      "type": "autocomplete",
      "name": "artist",
      "title": { "en": "Artist" },
      "placeholder": { "en": "Ludwig van Beethoven" }
    }
  ]
}
```

{% endcode %}

{% tabs %}
{% tab title="JavaScript" %}
{% code title="/app.js" %}

```javascript
const Homey = require('homey');

class App extends Homey.App {
  async onInit() {
    const launchAppCard = this.homey.flow.getActionCard("play_artist");

    launchAppCard.registerArgumentAutocompleteListener(
      "artist",
      async (query, args) => {
        const results = [
          {
            name: "Wolfgang Amadeus Mozart",
            description: "Joannes Chrysostomus Wolfgangus Theophilus Mozart",
            icon: "https://path.to/icon.svg",
            // For images that are not svg use:
            // image: 'https://path.to/icon.png',

            // You can freely add additional properties
            // that you can access in registerRunListener
            id: "...",
          },
        ];

        // filter based on the query
        return results.filter((result) => {
           return result.name.toLowerCase().includes(query.toLowerCase());
        });
      }
    );
  }
}

module.exports = App;
```

{% endcode %}
{% endtab %}

{% tab title="TypeScript" %}
{% code title="/app.mts" %}

```mts
import Homey, { type FlowCard } from "homey";

export default class App extends Homey.App {
  async onInit(): Promise<void> {
    const launchAppCard = this.homey.flow.getActionCard("play_artist");

    launchAppCard.registerArgumentAutocompleteListener(
      "artist",
      async (query: string, args): Promise<FlowCard.ArgumentAutocompleteResults> => {
        const results = [
          {
            name: "Wolfgang Amadeus Mozart",
            description: "Joannes Chrysostomus Wolfgangus Theophilus Mozart",
            icon: "https://path.to/icon.svg",
            // For images that are not svg use:
            // image: 'https://path.to/icon.png',

            // You can freely add additional properties
            // that you can access in registerRunListener
            id: "...",
          },
        ];

        // filter based on the query
        return results.filter(result => {
          return result.name.toLowerCase().includes(query.toLowerCase());
        });
      },
    );
  }
}

```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code title="/app.py" %}

```python
from homey import app
from homey.flow_card import ArgumentAutocompleteResult


class App(app.App):
    async def on_init(self) -> None:
        launch_app_card = self.homey.flow.get_action_card("play_artist")

        async def autocomplete_listener(
            query, **card_args
        ) -> list[ArgumentAutocompleteResult]:
            results: list[ArgumentAutocompleteResult] = [
                {
                    "name": "Wolfgang Amadeus Mozart",
                    "description": "Joannes Chrysostomus Wolfgangus Theophilus Mozart",
                    "icon": "https://path.to/icon.svg",
                    # For images that are not svg use:
                    # image: 'https://path.to/icon.png',
                    "data": {
                        # You can freely add additional properties here
                        # that you can access in registerRunListener
                        "id": "...",
                    },
                },
            ]

            return [
                result for result in results if query.lower() in result["name"].lower()
            ]

        launch_app_card.register_argument_autocomplete_listener(
            "artist", autocomplete_listener
        )


homey_export = App

```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
If you don't filter based on the query, it will cause the autocomplete results to appear unresponsive. The easiest way to filter the results is to compare `name` and `query` in lowercase as shown above.
{% endhint %}

### Number

`"type": "number"`

Regular text input. Tokens can be dropped in this field as well.

![](https://998911913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPk9cn4V7WnnKt7fbry%2Fuploads%2Fgit-blob-ad93946450b374d9341db6fa28f5157342c596ab%2FNumber.png?alt=media)

**Attributes**

| Name        | Type                                                                                       | Description                | Example                                                    |
| ----------- | ------------------------------------------------------------------------------------------ | -------------------------- | ---------------------------------------------------------- |
| min         | `number`                                                                                   | Minimum input value        | 40                                                         |
| max         | `number`                                                                                   | Maximum input value        | 90                                                         |
| step        | `number`                                                                                   | Step size                  | 10                                                         |
| placeholder | [translation object](https://apps.developer.homey.app/the-basics/app/internationalization) | Text to show without input | `{ "en": "In degree celsius", "nl": "In graden celsius" }` |
| title       | [translation object](https://apps.developer.homey.app/the-basics/app/internationalization) | Text shown above argument  | `{ "en": "Temperature", nl": "Temperatuur" }`              |

**Example**

{% code title="/.homeycompose/flow/actions/wash\_clothes.json" %}

```javascript
{
  "title": { "en": "Wash clothes" },
  "titleFormatted": { "en": "Wash clothes at [[temperature]] degrees celsius" },
  "args": [
    {
      "type": "number",
      "name": "temperature",
      "title": { "en": "Temperature" },
      "placeholder": { "en": "In degree celsius" },
      "min": 40,
      "max": 90,
      "step": 10
    }
  ]
}
```

{% endcode %}

### Range

`"type": "range"`

A slider with a minimum and maximum value.

![](https://998911913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPk9cn4V7WnnKt7fbry%2Fuploads%2Fgit-blob-d11304505d4d3c3c7ec05c100180313e85a6fc2d%2FRange.png?alt=media)

**Attributes**

| Name            | Type                                                                                       | Description                                      | Example                                     |
| --------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------ | ------------------------------------------- |
| min             | `number`                                                                                   | Minimum input value                              | 0                                           |
| max             | `number`                                                                                   | Maximum input value                              | 1                                           |
| step            | `number`                                                                                   | Step size                                        | 0.01                                        |
| label           | `string`                                                                                   | The units after the number                       | %                                           |
| labelMultiplier | `number`                                                                                   | Number is shown after multiplying by this factor | 100                                         |
| labelDecimals   | `number`                                                                                   | Number of decimals to round to                   | 2                                           |
| title           | [translation object](https://apps.developer.homey.app/the-basics/app/internationalization) | Text shown above argument                        | `{ "en": "Brightness", nl": "Helderheid" }` |

**Example**

{% code title="/.homeycompose/flow/actions/set\_brightness.json" %}

```javascript
{
  "title": { "en": "Set brightness" },
  "titleFormatted": { "en": "Set brightness to [[brightness]]" },
  "args": [
    {
      "type": "range",
      "name": "brightness",
      "title": { "en": "Brightness" },
      "min": 0,
      "max": 1,
      "step": 0.01,
      "label": "%",
      "labelMultiplier": 100,
      "labelDecimals": 2
    }
  ]
}
```

{% endcode %}

### Date

`"type": "date"`

Date input (presented in `dd-mm-yyyy`)

![](https://998911913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPk9cn4V7WnnKt7fbry%2Fuploads%2Fgit-blob-f18268da90244c97fcea1156c2261263642482a6%2FDate.png?alt=media)

**Attributes**

| Name        | Type                                                                                       | Description                | Example                                         |
| ----------- | ------------------------------------------------------------------------------------------ | -------------------------- | ----------------------------------------------- |
| placeholder | [translation object](https://apps.developer.homey.app/the-basics/app/internationalization) | Text to show without input | `{ "en": "When to ..", "nl": "Wanneer te .." }` |
| title       | [translation object](https://apps.developer.homey.app/the-basics/app/internationalization) | Text shown above argument  | `{ "en": "Birthday", nl": "Verjaardag" }`       |

**Example**

{% code title="/.homeycompose/flow/actions/birthday\_surprise.json" %}

```javascript
{
  "title": { "en": "Birthday surprise" },
  "titleFormatted": { "en": "Surprise you on [[birthday]]" },
  "args": [
    {
      "type": "date",
      "name": "birthday",
      "title": { "en": "Birthday" },
      "placeholder": { "en": "18-05-1994" }
    }
  ]
}
```

{% endcode %}

### Time

`"type": "time"`

Time input (presented in `HH:mm`)

![](https://998911913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPk9cn4V7WnnKt7fbry%2Fuploads%2Fgit-blob-7641821abfcf711a7843208da04cc00c98d6e28d%2FTime.png?alt=media)

**Attributes**

| Name        | Type                                                                                       | Description                | Example                                         |
| ----------- | ------------------------------------------------------------------------------------------ | -------------------------- | ----------------------------------------------- |
| placeholder | [translation object](https://apps.developer.homey.app/the-basics/app/internationalization) | Text to show without input | `{ "en": "When to ..", "nl": "Wanneer te .." }` |
| title       | [translation object](https://apps.developer.homey.app/the-basics/app/internationalization) | Text shown above argument  | `{ "en": "Time", nl": "Tijd" }`                 |

**Example**

{% code title="/.homeycompose/flow/actions/activate\_alarm.json" %}

```javascript
{
  "title": { "en": "Activate the alarm" },
  "titleFormatted": { "en": "Activate the alarm at [[activationtime]]" },
  "args": [
    {
      "type": "time",
      "name": "activationtime",
      "title": { "en": "Time" },
      "placeholder": { "en": "13:37" }
    }
  ]
}
```

{% endcode %}

### Dropdown

`"type": "dropdown"`

A dropdown list with pre-defined values

![](https://998911913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPk9cn4V7WnnKt7fbry%2Fuploads%2Fgit-blob-20cc81062a9a589f76a18325c98f529ac55dd263%2FDropdown.png?alt=media)

**Attributes**

| Name   | Type                                                                                       | Description                 | Example                                                |
| ------ | ------------------------------------------------------------------------------------------ | --------------------------- | ------------------------------------------------------ |
| values | `array`                                                                                    | An array of possible values | `[ { "id": "value1", "title": { "en": "Value 1" } } ]` |
| title  | [translation object](https://apps.developer.homey.app/the-basics/app/internationalization) | Text shown above argument   | `{ "en": "My title", nl": "Mijn titel" }`              |

**Example**

{% code title="/.homeycompose/flow/triggers/rain\_start.json" %}

```javascript
{
  "title": { "en": "It is going to rain in..." },
  "titleFormatted": { "en": "It is going to rain in [[when]]" },
  "args": [
    {
      "type": "dropdown",
      "name": "when",
      "title": { "en": "When it will rain" },
      "values": [
        { "id": "5", "title": { "en": "5 minutes" } },
        { "id": "10", "title": { "en": "10 minutes" } },
        { "id": "15", "title": { "en": "15 minutes" } }
      ]
    }
  ]
}
```

{% endcode %}

### Multiselect

`"type": "multiselect"`

A multiselect list with pre-defined values

![](https://998911913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPk9cn4V7WnnKt7fbry%2Fuploads%2Fgit-blob-887701e115922f6e67c3043d4d8cdcce5a52a433%2FMultiselect.png?alt=media)

**Attributes**

| Name        | Type                                                                                       | Description                                                           | Example                                                |
| ----------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------ |
| values      | `array`                                                                                    | An array of possible values                                           | `[ { "id": "value1", "title": { "en": "Value 1" } } ]` |
| title       | [translation object](https://apps.developer.homey.app/the-basics/app/internationalization) | Text shown above argument                                             | `{ "en": "My title", nl": "Mijn titel" }`              |
| conjunction | `string`                                                                                   | The conjunction of the argument in the preview for users (and or or). | `or`                                                   |

**Example**

{% code title="/.homeycompose/flow/conditions/today\_is\_a\_day.json" %}

```javascript
{
  "title": {
    "en": "Today is a"
  },
  "titleFormatted": {
    "en": "Today is a [[days]]"
  },
  "args": [
    {
      "title": {
        "en": "Day"
      },
      "name": "days",
      "type": "multiselect",
      "conjunction": "or",
      "values": [
        { "id": "mon", "title": { "en": "Monday" } },
        { "id": "tue", "title": { "en": "Tuesday" } },
        { "id": "wed", "title": { "en": "Wednesday" } },
        { "id": "thu", "title": { "en": "Thursday" } },
        { "id": "fri", "title": { "en": "Friday" } },
        { "id": "sat", "title": { "en": "Saturday" } },
        { "id": "sun", "title": { "en": "Sunday" } }
      ]
    }
  ]
}

```

{% endcode %}

### Checkbox

`"type": "checkbox"`

A dropdown list with a true and false option that supports boolean tokens.

![](https://998911913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPk9cn4V7WnnKt7fbry%2Fuploads%2Fgit-blob-8eb28777b219631a945d0aebc5cf9b019b132c60%2FLogic%20Card%20\(2\).png?alt=media)

**Attributes**

<table data-header-hidden><thead><tr><th>Name</th><th width="225">Type</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>Name</td><td>Type</td><td>Description</td><td>Example</td></tr><tr><td>title</td><td><a href="../app/internationalization">translation object</a></td><td>Text shown above argument</td><td><code>{ "en": "My title", nl": "Mijn titel" }</code></td></tr></tbody></table>

**Example**

{% code title="/.homeycompose/flow/triggers/rain\_start.json" %}

```javascript
{
  "title": { "en": "Set enabled to..." },
  "titleFormatted": { "en": "Set enabled to [[enabled]]" },
  "args": [
    {
      "type": "checkbox",
      "name": "enabled",
      "title": { "en": "Enabled" }
    }
  ]
}
```

{% endcode %}

### Color

`"type": "color"`

A color picker that returns a HEX color, e.g. `#FF0000`.

![](https://998911913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPk9cn4V7WnnKt7fbry%2Fuploads%2Fgit-blob-33da59a336cdcbb967100e247a686908a1345fb0%2FColor.png?alt=media)

**Example**

{% code title="/.homeycompose/flow/actions/set\_tile\_color.json" %}

```javascript
{
  "title": { "en": "Set tile color" },
  "titleFormatted": { "en": "Set tile color to [[background]]" },
  "args": [
    {
      "type": "color",
      "name": "background"
    }
  ]
}
```

{% endcode %}

### Droptoken

A droptoken is a special Flow card Argument that only allows the user to enter a [Flow Token](https://apps.developer.homey.app/the-basics/flow/tokens) or Homey Logic variable. You can add a droptoken to your Flow card by specifying, for example, `"droptoken": ["number"]`. You can use the any of the following types: `string`, `number`, `boolean` or `image`. A Flow card can only have a single droptoken but you can specify multiple allowed types.

{% hint style="info" %}
Droptokens are possibly null. Make sure to verify the droptoken exists before using it.
{% endhint %}

![](https://998911913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPk9cn4V7WnnKt7fbry%2Fuploads%2Fgit-blob-380a4e7c1656eb17535807724ab31b14f55d0ac0%2FDroptoken.png?alt=media)

**Example**

{% code title="/.homeycompose/flow/conditions/equal.json" %}

```javascript
{
  "title": { "en": "Is equal" },
  "titleFormatted": { "en": "[[droptoken]] equals [[value]]" },
  "droptoken": ["number"],
  "args": [
    {
      "type": "number",
      "name": "value"
    }
  ]
}
```

{% endcode %}

### Device

`"type": "device"`

When you add a device argument to your flow card, and provide a `driver_id` filter, e.g. `"filter": "driver_id=yourdriverid"`, the Flow card will only be displayed for devices that belong to that specific driver.

If the device was already there because the device's class is a supported device class (e.g. `light`), your cards will be appended to the existing stack of cards. An example would be a Light driver that has a 'disco' mode, next to on/off, dim and color.

If the card has more than one device fields, the other fields will behave like an autocomplete-like argument, which show devices paired in your app.

See the [Flow guide Device cards section](https://apps.developer.homey.app/the-basics/flow/..#device-cards) for more information about device arguments and filters.

**Example**

{% code title="/.homeycompose/flow/actions/my\_action.json" overflow="wrap" %}

```javascript
{
  "title": {
    "en": "I will show up under all devices with a driver id of mydriver and with the custom capability id mycustomcapability."
  },
  "args": [
    {
      "type": "device",
      "name": "device",
      "title": { "en": "Device" },
      "filter": "driver_id=mydriver&capabilities=mycustomcapability"
    }
  ]
}
```

{% endcode %}

## Optional arguments

By default all Flow card arguments are required however if you want to allow an argument to be optional you can set the `required` property to `false`.

{% hint style="warning" %}
If an argument is not required and is not provided by the user it may be `undefined` in your Flow card run handler.
{% endhint %}

**Example**

{% code title="/.homeycompose/flow/actions/post\_data.json" %}

```javascript
{
  "title": { "en": "Post data to URL" },
  "titleFormatted": { "en": "Post [[data]] to [[url]]" },
  "args": [
    {
      "type": "text",
      "name": "url",
      "title": { "en": "URL" },
      "placeholder": { "en": "https://example.com" }
    }
    {
      "type": "text",
      "name": "data",
      "required": false,
      "title": { "en": "Body" },
      "placeholder": { "en": "message" }
    }
  ]
}
```

{% endcode %}

## Action Card duration

If you are creating an Action Flow card, a card for the *...then* column, you can set the `duration` property. This property allows users to choose a duration for the action. If a user provides this argument to the Flow card, it will be passed to the card handler as an argument named `duration` in milliseconds.

{% hint style="warning" %}
`"duration": true` has precedence over an argument with `"name": "duration"` as they are both provided as arguments to the same handler. You should not create a Flow card with the `duration` property and an argument named `"duration".`
{% endhint %}

**Example**

{% code title="/.homeycompose/flow/actions/run\_animation.json" %}

```javascript
{
  "title": { "en": "Run animation" },
  "titleFormatted": { "en": "Run animation [[animation]]" },
  "duration": true,
  "args": [
    {
      "type": "dropdown",
      "name": "animation",
      "title": { "en": "Animation" },
      "values": [
        { "id": "rainbow", "title": { "en": "Rainbow" } },
        { "id": "kitt", "title": { "en": "KITT" } },
        { "id": "pulse", "title": { "en": "Pulse" } }
      ]
    }
  ]
}
```

{% endcode %}

{% tabs %}
{% tab title="JavaScript" %}
{% code title="/app.js" %}

```javascript
const Homey = require('homey');

class App extends Homey.App {
  async onInit() {
    const runAnimationAction = this.homey.flow.getActionCard("run_animation");

    runAnimationAction.registerRunListener(async (args, state) => {
      if (args.duration != null) {
        // do something with the duration
        // (e.g. run an animation for duration milliseconds)
      }
    });
  }
}

module.exports = App;
```

{% endcode %}
{% endtab %}

{% tab title="TypeScript" %}
{% code title="/app.mts" %}

```mts
import Homey from "homey";

type RunAnimationArgs = {
  duration: number;
};

export default class App extends Homey.App {
  async onInit(): Promise<void> {
    const runAnimationAction = this.homey.flow.getActionCard("run_animation");

    runAnimationAction.registerRunListener(async (args: RunAnimationArgs, state) => {
      if (args.duration != null) {
        // do something with the duration
        // (e.g. run an animation for duration milliseconds)
      }
    });
  }
}

```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code title="/app.py" %}

```python
from homey import app


class App(app.App):
    async def on_init(self) -> None:
        run_animation_action = self.homey.flow.get_action_card("run_animation")

        async def run_listener(card_arguments, **trigger_kwargs) -> None:
            if card_arguments.get("duration") is not None:
                # do something with the duration
                # (e.g. run an animation for duration milliseconds)
                ...

        run_animation_action.register_run_listener(run_listener)


homey_export = App

```

{% endcode %}
{% endtab %}
{% endtabs %}

## Subscribing to argument changes

It might be useful to know when a trigger has changed. For example a Twitter app may have a Flow card that triggers a Flow when a specific hashtag is tweeted. In order to implement this behaviour the app needs to know what hashtags to search for. By subscribing to argument changes the app knows when the argument values have changed and update the list of hashtags it is looking for.

{% tabs %}
{% tab title="JavaScript" %}
{% code title="/app.js" %}

```javascript
const Homey = require('homey');

class App extends Homey.App {
  async onInit() {
    const myTrigger = this.homey.flow.getTriggerCard("my_trigger");

    myTrigger.on("update", () => {
      this.log("update");

      myTrigger.getArgumentValues().then((args) => {
        // args is [{ "my_arg": "user_value" }]
      });
    });
  }
}

module.exports = App;
```

{% endcode %}
{% endtab %}

{% tab title="TypeScript" %}
{% code title="/app.mts" %}

```mts
import Homey from "homey";

type FlowCardArguments = {
  my_arg: string;
};

export default class App extends Homey.App {
  async onInit(): Promise<void> {
    const myTrigger = this.homey.flow.getTriggerCard("my_trigger");

    myTrigger.on("update", () => {
      this.log("update");

      myTrigger.getArgumentValues().then((args: FlowCardArguments[]) => {
        // args is [{ "my_arg": "user_value" }]
      });
    });
  }
}

```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code title="/app.py" %}

```python
import asyncio

from homey import app


class App(app.App):
    async def on_init(self) -> None:
        my_trigger = self.homey.flow.get_trigger_card("my_trigger")

        async def handle_updated_argument_values():
            args = await my_trigger.get_argument_values()
            # args is ({"my_arg": "user_value"},)

        def on_update():
            self.log("update")
            asyncio.create_task(handle_updated_argument_values())

        my_trigger.on_update(on_update)


homey_export = App

```

{% endcode %}
{% endtab %}
{% endtabs %}

## Flow State

When a Flow is triggered and the Flow Trigger card has arguments, your app needs to validate that the current state matches with the arguments the user chose for the Flow. This listener is executed for each Flow that uses this Flow Trigger card.

For example, a `rain_start` Flow Trigger card can have a `location` argument so that the Flow is only triggered when it is raining in the place the user has selected.

{% code title="/.homeycompose/flow/triggers/rain\_start.json" %}

```javascript
{
  "title": { "en": "It starts raining" },
  "tokens": [
    {
      "name": "mm_per_hour",
      "type": "number",
      "title": { "en": "mm/h" },
      "placeholder": { "en": "5" }
    }
  ],
  "args": [
    {
      "name": "location",
      "type": "text"
    }
  ]
}
```

{% endcode %}

{% tabs %}
{% tab title="JavaScript" %}
{% code title="/app.js" %}

```javascript
const Homey = require('homey');
const RainApi = require('rain-api');

class App extends Homey.App {
  async onInit() {
    const rainStartTrigger = this.homey.flow.getTriggerCard("rain_start");

    rainStartTrigger.registerRunListener(async (args, state) => {
      // args is the user input,
      // for example { 'location': 'New York' }
      // state is the parameter passed in trigger()
      // for example { 'location': 'Amsterdam' }

      // If true, this flow should run
      return args.location === state.location;
    });

    RainApi.on('raining', (city, amount) => {
      const tokens = { mm_per_hour: amount }; // for example 3
      const state = { location: city }; // for example "Amsterdam"

      // trigger the card
      rainStartTrigger.trigger(tokens, state)
        .then(this.log)
        .catch(this.error);
    });
  }
}

module.exports = App;
```

{% endcode %}
{% endtab %}

{% tab title="TypeScript" %}
{% code title="/app.mts" %}

```mts
import Homey from "homey";
import RainApi from "rain-api";

type RainStartArguments = {
  location: string;
};

type RainStartState = {
  location: string;
};

export default class App extends Homey.App {
  async onInit(): Promise<void> {
    const rainStartTrigger = this.homey.flow.getTriggerCard("rain_start");

    rainStartTrigger.registerRunListener(async (args: RainStartArguments, state: RainStartState) => {
      // args is the user input,
      // for example { 'location': 'New York' }
      // state is the parameter passed in trigger()
      // for example { 'location': 'Amsterdam' }

      // If true, this flow should run
      return args.location === state.location;
    });

    RainApi.on("raining", (city: string, amount: number) => {
      const tokens = { mm_per_hour: amount }; // for example 3
      const state = { location: city }; // for example "Amsterdam"

      // trigger the card
      rainStartTrigger.trigger(tokens, state).then(this.log).catch(this.error);
    });
  }
}

```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code title="/app.py" %}

```python
import asyncio

from homey import app

from rain_api import RainApi


class App(app.App):
    async def on_init(self) -> None:
        rain_start_trigger = self.homey.flow.get_trigger_card("rain_start")

        async def run_listener(card_arguments, **trigger_kwargs) -> bool:
            # card_arguments is the user input
            # for example {"location": "New York"}
            # trigger_kwargs are the parameters passed in trigger()
            # for example {"location": "Amsterdam"}
            return card_arguments.get("location") == trigger_kwargs.get("location")

        rain_start_trigger.register_run_listener(run_listener)

        async def on_raining(city: str, amount: float) -> None:
            tokens = {"mm_per_hour": amount}  # for example 3
            try:
                self.log(
                    await rain_start_trigger.trigger(
                        tokens,
                        location=city,  # for example "Amsterdam"
                    )
                )
            except Exception as e:
                self.error(e)

        RainApi.on("raining", on_raining)


homey_export = App

```

{% endcode %}
{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apps.developer.homey.app/the-basics/flow/arguments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.