feat(slack): @trigger.dev/slack channel provider

Ship Slack as a real chat frontend for agents. `slack({ token, ... })` (from the new @trigger.dev/slack package) verifies inbound Slack events, routes a thread's messages to a durable session, runs them as turns, and posts the reply back with chat.postMessage then chat.update.

Package boundary: the branded provider ships as its own package and is imported by name (chat.agent({ channels: [slack({...})] })), keeping Slack-specific HTTP + token handling out of the core SDK and setting the pattern for future providers. The SDK keeps the channels vocabulary (the channels option, the connector shape, chat.channels.custom); the inbound-only chat.channels.slack stub moves into the package.

slack() supplies: the Slack v0 HMAC verifier + the url_verification handshake, a per-thread key with a {thread_ts || ts} fallback so thread-starting messages don't drop, the real chat.postMessage/update egress (bot token, re-resolve on auth failure, surfaced not_in_channel), and a mandatory self-message filter (drops bot posts + their message_changed edits, and dedupes app_mention) so the agent never replies to itself. token accepts a string or an event-keyed resolver for multi-workspace.

Unreleased feature, so no released-API impact.

Author: ericallam

.changeset/webhook-channels.md

@@ -0,0 +1,12 @@
+---
+"@trigger.dev/core": patch
+"@trigger.dev/sdk": patch
+"@trigger.dev/slack": patch
+"trigger.dev": patch
+---
+
+Add channels: chat frontends for agents. A `chat.agent` can now take `channels: [...]` alongside `events: [...]`. A channel is a bidirectional chat surface (Slack, etc.): a verified inbound event is routed to a durable per-key session and run as a turn (via the connector's `inbound()` mapper), and the agent's reply is posted back to the surface (`outbound()` + `send()`), so a thread is a real conversation with the agent. Egress runs in-run; "final" mode posts an ack placeholder at turn start and edits it to the answer at turn complete.
+
+`chat.channels.custom({ source, key, inbound, outbound, send, ack, filter, delivery })` is the generic connector (bring your own source and egress). The new `@trigger.dev/slack` package ships `slack({ token, ... })`: the Slack Events API verifier, the `url_verification` handshake, a per-thread session key (with a `thread_ts || ts` fallback for thread starts), the real `chat.postMessage`/`chat.update` egress, and a mandatory self-message filter so the bot never replies to its own posts.
+
+Two supporting engine capabilities landed generically: session key templates gain a first-non-empty fallback operator (`{a || b}`), and verifier artifacts can declare a synchronous handshake (used for Slack `url_verification`, reusable for Discord PING).

docs/docs.json

@@ -59,7 +59,8 @@
               "webhooks/connect",
               "webhooks/deliveries",
               "webhooks/filters",
-              "webhooks/session-routing"
+              "webhooks/session-routing",
+              "webhooks/channels"
             ]
           },
           {

docs/webhooks/channels.mdx

@@ -0,0 +1,88 @@
+---
+title: "Channels (chat frontends)"
+description: "Point Slack (or any chat surface) at an agent: messages become turns and replies post back."
+sidebarTitle: "Channels"
+---
+
+A [session route](/webhooks/session-routing) delivers a verified event to an agent as an [action](/ai-chat/actions): the agent reacts, and the response is a side effect. A **channel** is the other half: the webhook IS the chat surface. Inbound messages become **turns** (the normal `run()` loop), and the agent's reply is posted **back** to the surface. A Slack thread becomes a real conversation with the agent, exactly like the browser chat, just a different frontend.
+
+List channels on a [`chat.agent`](/ai-chat/overview) alongside (or instead of) `events`:
+
+```ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { slack } from "@trigger.dev/slack";
+
+export const supportAgent = chat.agent({
+  id: "support-agent",
+  channels: [slack({ id: "support-slack", token: process.env.SLACK_BOT_TOKEN! })],
+  run: async ({ messages }) => streamText({ model: anthropic("claude-sonnet-4-5"), messages }),
+});
+```
+
+The `run()` loop is unchanged: the agent does not know or care that it is talking to Slack. One verified Slack message in a thread is routed to a durable [session](/ai-chat/sessions) keyed to that thread, run as a turn, and the reply is posted into the thread.
+
+## Slack
+
+`slack()` (from `@trigger.dev/slack`) is a channel connector: it verifies inbound Slack events, maps a message to the turn, and posts the reply back with `chat.postMessage` / `chat.update`.
+
+<Steps>
+  <Step title="Create a Slack app">
+    Create an app at [api.slack.com/apps](https://api.slack.com/apps). Add the `chat:write` bot scope and install it to your workspace to get a bot token (`xoxb-...`).
+  </Step>
+  <Step title="Deploy the agent + connect the endpoint">
+    Deploying registers a hosted [ingress endpoint](/webhooks/connect) for the channel. Set its signing secret to your Slack app's **Signing Secret**, and pass the bot token as `token`.
+  </Step>
+  <Step title="Subscribe to events">
+    In the app's **Event Subscriptions**, set the request URL to the endpoint's ingress URL. Slack sends a one-time `url_verification` handshake, which the endpoint answers automatically. Subscribe the bot to `message.channels`, then invite the bot to the channel (`/invite @yourapp`).
+  </Step>
+</Steps>
+
+By default `slack()` keys one session per thread, strips the leading bot mention from the message, posts an "on it..." placeholder while the agent works, and edits it to the answer. Override any of that:
+
+```ts
+slack({
+  id: "support-slack",
+  token: process.env.SLACK_BOT_TOKEN!,
+  // ignore anything but questions (composed with the built-in self-message guard)
+  filter: "event.event.text contains '?'",
+  inbound: (e) => e.event?.text ?? "",
+  outbound: (reply) => ({ text: reply.text }),
+  ack: (e) => ({ text: "thinking..." }), // pass `null` to post only the final answer
+});
+```
+
+<Note>
+  `slack()` always drops the bot's own messages (and their edits) before they reach the agent, so the
+  agent never replies to itself. A multi-workspace app can pass a `token` resolver keyed on the event's
+  team instead of a single string.
+</Note>
+
+## Any surface: `chat.channels.custom`
+
+For a surface without a preset, `chat.channels.custom` is the generic connector. You supply the [source](/webhooks/sources) to verify, the session `key`, the `inbound` map, and the egress `send`:
+
+```ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { webhooks } from "@trigger.dev/sdk";
+
+const mySurface = chat.channels.custom({
+  id: "my-surface",
+  source: webhooks.custom<MyEvent>({ /* verifier config */ }),
+  key: "{body.conversationId}",
+  inbound: (e) => e.text,
+  outbound: (reply) => (reply.text ? { text: reply.text } : null), // null posts nothing
+  send: async (message, ctx) => {
+    const ref = await postToMySurface(ctx.event, message.text, ctx.previousRef);
+    return { ref }; // an existing ref means edit-in-place on the next turn
+  },
+});
+```
+
+`send` is called to post the reply. `ctx.previousRef` is the ref you returned last time, so streaming or a follow-up edits the same message instead of posting a new one. Return `null` from `outbound` to stay silent (a tool-only turn, say).
+
+## Channels vs events
+
+Both are inbound surfaces on a `chat.agent`, and an agent can list both:
+
+- [`events`](/webhooks/session-routing) (`chat.event`): the webhook is a signal. Delivered to `onAction`; the agent acts, no reply is sent back.
+- `channels` (`slack`, `chat.channels.custom`): the webhook is a chat frontend. Delivered as a turn to `run()`; the reply is posted back.

internal-packages/webhook-engine/src/engine/filter/filter.test.ts

@@ -171,3 +171,31 @@ describe("quantifiers", () => {
     );
   });
 });
+
+// The @trigger.dev/slack self-message loop guard: route only human message events, drop the bot's own
+// posts (bot_id present) and their edits (message_changed). Proves the loop is closed.
+describe("slack self-message guard", () => {
+  const GUARD =
+    "event.event.type == 'message' && event.event.bot_id == null && event.event.subtype not in ['message_changed','message_deleted','bot_message']";
+  const ev = (event: Record<string, unknown>): Partial<FilterContext> => ({ event: { event } });
+
+  it("routes a human message in a thread", () => {
+    expect(evaluateFilter(parseFilter(GUARD), ctx(ev({ type: "message", channel: "C1", ts: "1" }))).match).toBe(true);
+  });
+
+  it("drops the bot's own post (bot_id present)", () => {
+    expect(
+      evaluateFilter(parseFilter(GUARD), ctx(ev({ type: "message", bot_id: "B123", text: "reply" }))).match
+    ).toBe(false);
+  });
+
+  it("drops an edit re-delivery (message_changed subtype)", () => {
+    expect(
+      evaluateFilter(parseFilter(GUARD), ctx(ev({ type: "message", subtype: "message_changed" }))).match
+    ).toBe(false);
+  });
+
+  it("drops an app_mention duplicate (dedupes to the message event)", () => {
+    expect(evaluateFilter(parseFilter(GUARD), ctx(ev({ type: "app_mention", text: "hey" }))).match).toBe(false);
+  });
+});

packages/slack/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@trigger.dev/slack",
+  "version": "4.5.0-rc.7",
+  "description": "Slack chat frontend (channel) for trigger.dev agents",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/triggerdotdev/trigger.dev",
+    "directory": "packages/slack"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "tshy": {
+    "selfLink": false,
+    "main": true,
+    "module": true,
+    "project": "./tsconfig.src.json",
+    "exports": {
+      "./package.json": "./package.json",
+      ".": "./src/index.ts"
+    },
+    "sourceDialects": [
+      "@triggerdotdev/source"
+    ]
+  },
+  "scripts": {
+    "clean": "rimraf dist .tshy .tshy-build .turbo",
+    "build": "tshy && pnpm run update-version",
+    "dev": "tshy --watch",
+    "typecheck": "tsc --noEmit -p tsconfig.src.json",
+    "test": "vitest",
+    "update-version": "tsx ../../scripts/updateVersion.ts",
+    "check-exports": "attw --pack ."
+  },
+  "dependencies": {
+    "@trigger.dev/core": "workspace:4.5.0-rc.7"
+  },
+  "peerDependencies": {
+    "@trigger.dev/sdk": "workspace:^4.5.0-rc.7"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.15.4",
+    "@trigger.dev/sdk": "workspace:4.5.0-rc.7",
+    "rimraf": "6.0.1",
+    "tshy": "^3.0.2",
+    "tsx": "4.17.0",
+    "vitest": "^2.1.9"
+  },
+  "engines": {
+    "node": ">=18.20.0"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "@triggerdotdev/source": "./src/index.ts",
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/index.d.ts",
+        "default": "./dist/commonjs/index.js"
+      }
+    }
+  },
+  "main": "./dist/commonjs/index.js",
+  "types": "./dist/commonjs/index.d.ts",
+  "module": "./dist/esm/index.js"
+}

packages/slack/src/index.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it, vi } from "vitest";
+import { slack, type SlackMessageEvent } from "./index.js";
+
+const messageEvent = (over: Partial<NonNullable<SlackMessageEvent["event"]>> = {}): SlackMessageEvent => ({
+  type: "event_callback",
+  event: { type: "message", channel: "C9", ts: "1699999999.0001", text: "hi", ...over },
+});
+
+describe("slack channel", () => {
+  it("default inbound strips a leading bot mention", () => {
+    const c = slack({ id: "s1", token: "xoxb-t" });
+    expect(c.inbound(messageEvent({ text: "<@U123> hello there" }))).toBe("hello there");
+    expect(c.inbound(messageEvent({ text: "plain" }))).toBe("plain");
+  });
+
+  it("composes the self-message guard with a user filter", () => {
+    const guardOnly = slack({ id: "s2", token: "t" });
+    expect(guardOnly.filter).toContain("event.event.type == 'message'");
+    expect(guardOnly.filter).toContain("event.event.bot_id == null");
+    expect(guardOnly.filter).toContain("message_changed");
+
+    const withUser = slack({ id: "s3", token: "t", filter: "event.event.channel == 'C1'" });
+    expect(withUser.filter).toContain("&& (event.event.channel == 'C1')");
+  });
+
+  it("keys one session per thread with a thread_ts||ts fallback", () => {
+    const c = slack({ id: "s4", token: "t" });
+    expect(c.key).toBe("{body.team_id}:{body.event.channel}:{body.event.thread_ts || body.event.ts}");
+  });
+
+  it("send posts then edits, threading the ref and using the bot token", async () => {
+    const calls: Array<{ url: string; body: Record<string, unknown>; auth: unknown }> = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (url: string, init: { body: string; headers: Record<string, string> }) => {
+        calls.push({ url, body: JSON.parse(init.body), auth: init.headers.authorization });
+        return { json: async () => ({ ok: true, ts: "1700000000.0001" }) };
+      })
+    );
+
+    const c = slack({ id: "s5", token: "xoxb-secret", apiBaseUrl: "https://mock.slack" });
+    const event = messageEvent();
+
+    const ackRes = await c.send!({ text: "on it..." }, {
+      event,
+      deliveryId: "d1",
+      mode: "final",
+      final: false,
+    });
+    expect(ackRes.ref).toBe("1700000000.0001");
+    expect(calls[0]?.url).toBe("https://mock.slack/chat.postMessage");
+    expect(calls[0]?.auth).toBe("Bearer xoxb-secret");
+    expect(calls[0]?.body.channel).toBe("C9");
+    expect(calls[0]?.body.thread_ts).toBe("1699999999.0001");
+
+    await c.send!({ text: "done" }, {
+      event,
+      deliveryId: "d1",
+      previousRef: ackRes.ref,
+      mode: "final",
+      final: true,
+    });
+    expect(calls[1]?.url).toBe("https://mock.slack/chat.update");
+    expect(calls[1]?.body.ts).toBe("1700000000.0001");
+    expect(calls[1]?.body.text).toBe("done");
+
+    vi.unstubAllGlobals();
+  });
+
+  it("send throws when the bot is not in the channel", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({ json: async () => ({ ok: false, error: "not_in_channel" }) }))
+    );
+    const c = slack({ id: "s6", token: "t", apiBaseUrl: "https://mock.slack" });
+    await expect(
+      c.send!({ text: "x" }, { event: messageEvent(), deliveryId: "d", mode: "final", final: true })
+    ).rejects.toThrow(/not_in_channel/);
+    vi.unstubAllGlobals();
+  });
+});