Triggers & Integrations

Triggers connect agents to external services. When an event arrives (a Slack message, an incoming SMS), the agent spins up a session, processes the event, and optionally delivers a response back to the source.

Supported Integrations

Provider	Trigger Events	Output Actions	Dashboard Setup
Slack	message, app_mention	message, thread_reply, file_upload	Yes
Twilio	incoming_message	sms, mms	Yes

GitHub and Linear appear in the dashboard but are not yet configurable (marked as 'Coming soon'). Use the API to configure them directly if needed.

Slack

Setup via Dashboard

1. Create a Slack app with Event Subscriptions and Bot Token Scopes (chat:write, files:read, files:write).
2. In the swarmlord dashboard, go to Integrations → Slack and enter your Bot Token and Signing Secret.
3. Click Setup — this creates a webhook URL.
4. Copy the webhook URL back into your Slack app's Event Subscriptions → Request URL.
5. Assign the agent to a channel — select which deployed agent handles messages in that channel.

Setup via Config

For CLI-based setup, add trigger and output configuration to swarmlord.jsonc:

{
    "name": "support-bot",
    "model": "anthropic/claude-haiku-4.5",

    "trigger": {
        "provider": "slack",
        "events": ["message", "app_mention"],
    },

    "promptTemplate": "A Slack message was received:\n\nFrom: {{event.user}}\nChannel: {{event.channel}}\nText: {{event.text}}\n\nRespond helpfully.",

    "outputs": [
        {
            "provider": "slack",
            "action": "thread_reply",
            "config": {
                "token": "{{secrets.SLACK_BOT_TOKEN}}",
                "channel": "{{event.channel}}",
                "thread_ts": "{{event.ts}}",
            },
            "template": "{{result}}",
        },
    ],

    "permission": { "*": "allow" },
}

How Slack Triggers Work

1. A user sends a message in a connected channel.
2. Slack posts the event to the webhook URL.
3. The server validates the X-Slack-Signature, parses the event, and resolves which agent handles this channel.
4. A session is created (thread-based — same Slack thread reuses the same session for multi-turn conversations).
5. The promptTemplate is rendered with event variables ({{event.user}}, {{event.text}}, etc.).
6. The agent runs and produces a response.
7. The output is delivered back as a Slack thread reply (or message, or file upload, depending on outputs config).

Slack Event Variables

Variable	Description
{{event.user}}	Slack user ID of the sender
{{event.channel}}	Channel ID
{{event.text}}	Message text
{{event.ts}}	Message timestamp (used for threading)
{{event.thread_ts}}	Thread timestamp (if replying in a thread)

Note: Additional event fields beyond those listed here may be available — the provider flattens the full Slack event payload into event.* variables.

Slack Output Actions

Action	Description
message	Post a new message to a channel
thread_reply	Reply in the same thread as the triggering message
file_upload	Upload a file to the channel

Twilio

Setup via Dashboard

1. Create a Twilio account and get a phone number.
2. In the dashboard, go to Integrations → Twilio and enter your Account SID and Auth Token.
3. Select a phone number and assign an agent to it.

The dashboard automatically configures Twilio's SMS webhook URL to point at the agent's trigger endpoint.

Setup via Config

{
    "name": "joke-writer",
    "model": "google/gemini-3-flash-preview",

    "trigger": {
        "provider": "twilio",
        "events": ["incoming_message"],
    },

    "promptTemplate": "Someone texted you:\n\nFrom: {{event.from}}\nMessage: {{event.body}}\n\nWrite them a joke in response. Just the joke — keep it short enough for a single SMS.",

    "outputs": [
        {
            "provider": "twilio",
            "action": "sms",
            "config": {
                "account_sid": "{{secrets.TWILIO_ACCOUNT_SID}}",
                "auth_token": "{{secrets.TWILIO_AUTH_TOKEN}}",
                "from": "{{secrets.TWILIO_PHONE_NUMBER}}",
                "to": "{{event.from}}",
            },
            "template": "{{result}}",
        },
    ],

    "tools": {
        "bash": false,
        "read": false,
        "write": false,
    },

    "permission": { "*": "deny" },
}

Twilio Event Variables

Variable	Description
{{event.from}}	Sender's phone number
{{event.to}}	Your Twilio number
{{event.body}}	SMS text content

Twilio Output Actions

Action	Description
sms	Send a text message
mms	Send a message with media attachment

Prompt Templates

The promptTemplate field defines the user message sent to the agent when a trigger fires. Use {{variable}} syntax to interpolate event data:

A Slack message was received:

From: {{event.user}}
Channel: {{event.channel}}
Text: {{event.text}}

Run a full audit on the site mentioned.

If promptTemplate is omitted, a provider-specific default is used.

WARNING

{{secrets.*}} references are not allowed in promptTemplate — secrets can only appear in outputs[].config values.

Outputs

Outputs define where agent results are delivered after a session completes. They're only valid when a trigger is configured.

"outputs": [
    {
        "provider": "slack",
        "action": "thread_reply",
        "config": {
            "token": "{{secrets.SLACK_BOT_TOKEN}}",
            "channel": "{{event.channel}}",
            "thread_ts": "{{event.ts}}",
        },
        "template": "{{result}}",
    },
],

Field	Description
provider	Output provider name (slack, twilio, webhook)
action	Provider-specific action (e.g. thread_reply, sms)
config	Provider credentials and routing. Supports {{secrets.*}} and {{event.*}} interpolation.
template	Response template. {{result}} is replaced with the agent's final text output.

Secrets in Outputs

Output config values can reference encrypted secrets stored via the CLI or dashboard:

"token": "{{secrets.SLACK_BOT_TOKEN}}"
"account_sid": "{{secrets.TWILIO_ACCOUNT_SID}}"

Set secrets with swarmlord secret put SLACK_BOT_TOKEN or via the dashboard Secrets page. They are resolved at runtime and passed directly to integrations — the LLM never has access to the raw values.

Schedules vs Triggers

	Trigger	Schedule
Activation	External event (webhook)	Cron expression
Input	Event payload → promptTemplate	Fixed prompt string
Output	Delivers to source (Slack, SMS)	No automatic output delivery
Sessions	Thread-based (Slack) or one-per-event	One session per cron tick
Use case	Chat bots, event responders	Monitoring, periodic reports

An agent can have either a trigger or a schedule, not both. Agents with neither are on-demand — used via the SDK only.