Automation

Configure the automation engine and template variables.

Overview

The automation engine allows you to create rules that trigger actions based on streaming events. Rules are evaluated in real-time and can execute chat commands, overlay updates, or API calls.

Permissions

Automations use six dedicated permissions:

Permission	Description
automations:read	View automations and their configuration
automations:create	Create new automations
automations:edit	Edit automation metadata, nodes, edges
automations:delete	Delete automations
automations:execute	Manually trigger and start/stop automations
automations:history	View execution history and debug logs

Template Variables

The template engine supports 60+ variables across multiple categories. Variables are wrapped in {{doubleCurlyBraces}} and resolved at execution time.

For the full variable reference, see:

• User guide: Automation Templates
• Developer guide: Automation Template Engine

Quick Reference

Category	Example	Permission
Channel	{{channelName}}, {{platform}}	None
Bot	{{botName}}, {{commandPrefix}}	None
Time	{{date}}, {{time}}, {{timezone}}	None
User	{{username}}, {{displayName}}	chat:userinfo
Stream	{{streamTitle}}, {{category}}, {{viewerCount}}	events:read
Events	{{followerName}}, {{cheerAmount}}, {{subTier}}	events:read
Spotify	{{songName}}, {{songArtist}}, {{isPlaying}}	spotify:read

Rule Configuration

Rules consist of:

1. Trigger -- The event type that activates the rule
2. Conditions -- Optional filters (minimum amount, specific platform, etc.)
3. Actions -- What to do when triggered (send message, update overlay, etc.)

REST API

All automation endpoints are under /v1/automations. See the REST API reference for full details.

Method	Path	Permission
GET	/v1/automations	automations:read
POST	/v1/automations	automations:create
GET	/v1/automations/{id}	automations:read
PATCH	/v1/automations/{id}	automations:edit
DELETE	/v1/automations/{id}	automations:delete
PUT	/v1/automations/{id}/nodes	automations:edit
PUT	/v1/automations/{id}/edges	automations:edit

Extension Node Integration

The automation engine supports extension-provided nodes alongside built-in nodes. Extension nodes use the ext:{short_id} prefix in automation_nodes.node_type.

Dispatch flow

When the executor encounters a node_type starting with ext::

1. Look up extension_installs by short_id
2. Load automation_node_configs for schemas and node type
3. For action nodes: call dispatcher.execute_extension_node(), collect output
4. For logic nodes: call dispatcher.execute_extension_node(), parse branch, follow output handle
5. For trigger nodes: skip (triggers are entry points, not walked during execution)

The dispatcher communicates with the Automation Worker via sync HTTP using system key authentication.

Automation Worker

The Automation Worker (apps/automation-worker/) is a standalone Actix Web service on port 8091 that executes extension node handlers in V8 isolates. Same architecture as the Bot Module Worker.

Endpoint	Method	Timeout	Purpose
/execute/action	POST	5s	Execute an action node handler
/execute/logic	POST	2s	Execute a logic node handler
/execute/trigger/poll	POST	5s	Poll a trigger handler
/webhooks/\{extension_id\}/\{install_id\}	POST	1s	Receive external webhook
/health	GET	--	Health check

Trigger registration

When an automation with an extension trigger is enabled:

• Webhook: API generates webhook URL + 64-char hex secret, stores in automation_webhook_registrations
• Polling: Worker starts poll loop at poll_interval_seconds (10-300)
• On disable: triggers deregistered, polling stops

Database tables

Table	Purpose
automation_node_configs	Extension node metadata (schemas, trigger mode, icon, color)
automation_webhook_registrations	Webhook URL registrations with secrets

Feature flag

feature:automation_node_extensions (category: feature) gates store installation and the Builder toolbar section. Free tier: disabled. Pro tier: enabled.