Trigger Nodes

Overview

Trigger nodes define how a flow is activated. They are standalone nodes (separate from the start node’s inline trigger) that provide richer configuration and can be mixed in flows.

MENTION

Fires when the agent is mentioned on a social platform.

{
  "type": "trigger",
  "data": {
    "type": "trigger",
    "triggerId": "mention-1",
    "name": "Twitter Mentions",
    "triggerType": "MENTION",
    "platform": "TWITTER",
    "config": {
      "mentionTypes": ["direct", "reply", "quote"],
      "replyToSelf": false,
      "keywords": ["help"],
      "excludeKeywords": ["spam"],
      "verifiedOnly": false,
      "minFollowers": 0
    },
    "rateLimit": {
      "maxExecutions": 60,
      "windowSeconds": 3600
    }
  }
}

Field	Type	Description
mentionTypes	array	direct, reply, quote
replyToSelf	boolean	Respond to own mentions (thread continuations)
keywords	string[]	Required keywords in mention
excludeKeywords	string[]	Exclude mentions with these words
verifiedOnly	boolean	Only verified accounts
minFollowers	number	Minimum follower count

KEYWORD

Fires when specific keywords are detected in platform messages.

{
  "triggerType": "KEYWORD",
  "config": {
    "keywords": ["help", "support", "question"],
    "matchMode": "any",
    "caseSensitive": false,
    "wholeWord": true,
    "excludeKeywords": ["test"]
  }
}

Field	Type	Description
keywords	string[]	Words to monitor
matchMode	any | all	Match any or all keywords
caseSensitive	boolean	Case-sensitive matching
wholeWord	boolean	Match whole words only

SCHEDULE

Fires on a cron schedule.

{
  "triggerType": "SCHEDULE",
  "config": {
    "cron": "0 9 * * *",
    "timezone": "America/New_York",
    "maxCatchUp": 3
  }
}

Common Cron Expressions

Expression	Schedule
* * * * *	Every minute
0 * * * *	Every hour
0 9 * * *	Daily at 9am
0 9 * * 1-5	Weekdays at 9am
0 0 * * 1	Every Monday midnight
0 0 1 * *	First of month
*/15 * * * *	Every 15 minutes

WEBHOOK

Fires when an HTTP request is received at the webhook URL.

{
  "triggerType": "WEBHOOK",
  "config": {
    "methods": ["POST"],
    "secretRef": "webhook_secret",
    "allowedIps": [],
    "contentType": "application/json",
    "pathPattern": "/hooks/my-agent"
  }
}

MANUAL

Fires when explicitly triggered by a user (chat UI or API call).

{
  "triggerType": "MANUAL",
  "config": {
    "requireConfirmation": false,
    "inputFields": [
      {
        "name": "topic",
        "type": "string",
        "label": "Research Topic",
        "required": true
      }
    ]
  }
}

Rate Limiting

All triggers support rate limiting:

{
  "rateLimit": {
    "maxExecutions": 100,
    "windowSeconds": 3600,
    "cooldownSeconds": 60,
    "perUser": {
      "maxExecutions": 10,
      "windowSeconds": 60
    }
  }
}

Trigger Payload

At runtime, triggers produce a standard payload:

{
  "triggerType": "MENTION",
  "messageId": "tweet-123",
  "platform": "TWITTER",
  "timestamp": "2024-01-01T12:00:00Z",
  "author": {
    "id": "user-456",
    "username": "johndoe",
    "displayName": "John Doe",
    "verified": true,
    "followerCount": 1500
  },
  "content": "@myagent help me with this question",
  "context": {
    "parentId": "tweet-100",
    "threadId": "thread-50",
    "replyToUsername": "janedoe"
  }
}