Slack Relay Agent — Swarm Alerts to Slack

#python #matrix #matrixswarm #ai

Overview

The SlackRelayAgent is a lightweight MatrixSwarm agent that forwards swarm alerts directly into a Slack channel using an Incoming Webhook. This gives operators real-time visibility into critical events without leaving their workspace.

Simple deployment
Works with existing hive.alert@cmd_send_alert_msg role
Validates responses so you know if Slack actually accepted the message

Agent Code

Directive Example

Keep the tags in, Phoenix Gui will automatically add the webhook from the vault.

{
"universal_id": "slack-it-out-1",
"name": "slack_relay",
"tags": {
"connection": { "proto": "slack" }
},

"service-manager": [
{
"role": ["hive.alert@cmd_send_alert_msg"],
"scope": ["parent", "any"]
}
]
}

Swarm Alert Routing — Example with Gatekeeper + Slack Relay

Say you’ve got the Gatekeeper agent watching your box, and you want to trigger an alert the moment someone SSHs in. Let’s walk through how that alert travels through the swarm — and lands in your Slack channel (or Telegram, or Discord).

1. Gatekeeper detects a trigger event

Gatekeeper watches auth.log. A user logs in via SSH. It fires a role-based alert:

pk = self.get_delivery_packet("standard.command.packet")
pk.set_data({
"handler": "hive.alert@cmd_send_alert_msg",
"content": {
"msg": "🚪 SSH login detected from 203.0.113.7",
"level": "info",
"origin": "gatekeeper"
}
})

2. Role discovery — get_nodes_by_role

Every Phoenix agent has access to this method:

self.get_nodes_by_role("hive.alert")

This dynamically discovers every agent offering alert relay services — Slack, Telegram, Discord, anything tagged with:

"service-manager": [{
"role": ["hive.alert@cmd_send_alert_msg"],
...
}]

Gatekeeper doesn't need to know what those agents are — it just queries and broadcasts.

3. Deliver the alert to each listener

Once Gatekeeper knows who’s listening, it sends a copy of the packet to each one:

for node in self.get_nodes_by_role("hive.alert"):
self.pass_packet(pk, node["universal_id"])

You can have one agent (SlackRelay) or multiple agents (Slack, Telegram, Discord) listening to this role — they’ll all receive it.

4. Slack Relay receives the alert

When the packet hits the slack_relay agent, here’s what happens:

It gets placed in the agent’s incoming/ folder (BootAgent handles this automatically).

The packet_listener() method loads and dispatches it.

It routes to the internal handler:

def cmd_send_alert_msg(self, content, packet, identity):
...

SlackRelay formats the message and POSTs it to your configured Incoming Webhook.

It checks the response. If Slack replies "ok", the message is confirmed delivered.

This Pattern Works Across All Channels

TelegramRelay and DiscordRelay work the exact same way.

Just assign them the same role (hive.alert@cmd_send_alert_msg) or different ones (hive.security, hive.signup, etc).

Agents can broadcast to all relays at once, or target specific ones.

Flexible Use Cases Use Case Pattern Send alerts to all relays at once Use shared role like hive.alert Send Slack-only alerts Assign slack.alert@cmd_send_alert_msg Route web signup events to Discord Assign hive.signup@cmd_send_alert_msg Relay only critical system failures to Telegram Assign hive.critical role