Homey Apps SDK
📖 Apps SDK Reference🌍 Web API🛠 Developer Tools
  • Welcome to the Apps SDK documentation 👋
  • The Basics
    • Getting Started
      • Homey CLI
    • App
      • Manifest
      • Internationalization
      • Permissions
      • Persistent Storage
    • Drivers & Devices
      • Pairing
        • System Views
          • Devices List
          • Add Devices
          • OAuth2 Login
          • Credentials Login
          • Pincode
          • Loading
          • Done
        • Custom Views
      • Capabilities
      • Energy
      • Settings
      • Best practices
        • Lights
        • Window coverings
        • Battery status
    • Flow
      • Arguments
      • Tokens
    • Widgets
      • Settings
      • Styling
      • Debugging
  • Wireless
    • Wi-Fi
      • Discovery
    • Bluetooth LE
    • Z-Wave
    • Zigbee
    • 433 MHz
    • Infrared
    • Matter
  • Cloud
    • OAuth2
    • Webhooks
  • App Store
    • Publishing
    • Guidelines
    • Verified Developer
    • Updating
  • Advanced
    • Custom Views
      • App Settings
      • Custom Pairing Views
      • HTML & CSS Styling
    • Web API
    • Images
    • LED Ring
    • Homey Compose
  • Guides
    • Homey Cloud
    • Breaking Changes
    • Tools
      • Bluetooth LE
      • Zigbee
      • TypeScript
    • Using ESM in Homey Apps
  • Upgrade Guides
    • Homey v6.0.0
    • Upgrading to SDK v3
      • Zigbee Apps
    • Device Capabilities
Powered by GitBook
On this page
  • Local Tokens
  • Tokens for Advanced Flow
  • Global Tokens
  • Image Tokens

Was this helpful?

  1. The Basics
  2. Flow

Tokens

Flow Tokens allow users to pass information between different Flow cards when creating their Flows.

PreviousArgumentsNextWidgets

Last updated 2 years ago

Was this helpful?

Tokens are typed variables that can be used throughout a Flow. A token is either:

  • Local — Attached to a Flow's trigger card, for example the name of the user that came home.

  • Global — Available anywhere, for example the current time.

Both tokens can be used in a Flow card's argument, such as a textfield.

In the User Interface, tokens are called Tags.

Local Tokens

When triggering a Flow, some information might be useful to use in that Flow. For example, when it starts raining, the mm/hour could be a token.

Tokens have a pre-defined type, which can be either string, number, boolean or image.

Users can use Flow Tokens in compatible Flow Arguments, such as a text field for string tokens. This way, the user can make advanced flows with variables. To add tokens to a Flow card, just add a property tokens to your Flow card manifest.

/.homeycompose/flow/triggers/rain_start.json
{
  "title": { "en": "It starts raining" },
  "tokens": [
    {
      "name": "mm_per_hour",
      "type": "number",
      "title": { "en": "mm/h" },
      "example": 5
    },
    {
      "name": "city",
      "type": "string",
      "title": { "en": "City" },
      "example": { "en": "Amsterdam" }
    }
  ]
}

And when firing your trigger, add them as second argument:

/app.js
const Homey = require('homey');
const RainApi = require('rain-api');

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

    RainApi.on('raining', (city, amount) => {
      const tokens = {
        mm_per_hour: amount,
        city: city
      };

      rainStartTrigger.trigger(tokens)
        .then(this.log)
        .catch(this.error);
    });
  }
}

module.exports = App;

Tokens for Advanced Flow

{
  "title": {
    "en": "Make it stop raining"
  },
  "hint": {
    "en": "Hires a shaman to do a sunny dance. Might cost some money."
  },
  "tokens": [
    {
      "name": "shamanName",
      "type": "text",
      "title": {
        "en": "Name of the Shaman"
      }
    },
    {
      "name": "shamanCost",
      "type": "number",
      "title": {
        "en": "Cost of the Shaman (€)"
      }
    }
  ]
}
/app.js
    const stopRainingAction = this.homey.flow.getActionCard('stop_raining');
    stopRainingAction.registerRunListener(async (args, state) => {
      await RainApi.makeItStopRaining();
      
      // Return the Tokens for Advanced Flow
      return {
        shamanName: 'Alumbrada',
        shamanCost: 10,
      };
    });

When specifying a tokens array in your Then-card's JSON, that card will not be visible when creating & editing a standard Flow.

Global Tokens

A token can also be registered globally, so they can be used in any Flow. This means the token can be used without requiring the app to trigger the Flow. For example a weather app could expose the current temperature as a global token.

By default a device's capability are registered as global tokens.

/app.js
const Homey = require('homey');

class App extends Homey.App {
  async onInit() {
    const myToken = await this.homey.flow.createToken("my_token", {
      type: "number",
      title: "My Token",
    });

    await myToken.setValue(23.5);
  }
}

module.exports = App;

Image Tokens

Certain applications might want to share images between Flows, e.g. a webcam that made a snapshot, or a Chromecast that wants to cast an image. A token with type image can be used here.

/app.js
const Homey = require('homey');

class App extends Homey.App {
  async onInit() {
    const myImage = await this.homey.images.createImage();
    myImage.setPath(path.join(__dirname, "assets", "images", "kitten.jpg"));

    // create a token & register it
    const myImageToken = await this.homey.flow.createToken("my_token", {
      type: "image",
      title: "My Image Token",
    });

    await myImageToken.setValue(myImage);

    // listen for a Flow action
    const myActionCard = this.homey.flow.getActionCard("image_action");

    myActionCard.registerRunListener(async (args, state) => {
      // get the contents of the image
      const imageStream = await args.droptoken.getStream();
      this.log(`saving ${imageStream.contentType} to: ${imageStream.filename}`);

      // save the image
      const targetFile = fs.createWriteStream(
        path.join(__dirname, "userdata", filename)
      );
      imageStream.pipe(targetFile);
      return true;
    });

    const myTriggerCard = this.homey.flow.getTriggerCard("image_trigger");

    // pass the image to the trigger call
    await myTriggerCard.trigger({ my_image: myImage });
  }
}

module.exports = App;

A Flow card can also have adroptoken field, droptokens are Flow Arguments that require the input to be a token. You can read more about droptokens in the .

A Then-card can optionally return tokens in an . Similar to a When-card, specify the tokens property as an array, and return an object in the run-listener of your Flow card.

Advanced Flow
Flow Arguments documentation