|
| 1 | +--- |
| 2 | +title: "Channels (chat frontends)" |
| 3 | +description: "Point Slack (or any chat surface) at an agent: messages become turns and replies post back." |
| 4 | +sidebarTitle: "Channels" |
| 5 | +--- |
| 6 | + |
| 7 | +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. |
| 8 | + |
| 9 | +List channels on a [`chat.agent`](/ai-chat/overview) alongside (or instead of) `events`: |
| 10 | + |
| 11 | +```ts |
| 12 | +import { chat } from "@trigger.dev/sdk/ai"; |
| 13 | +import { slack } from "@trigger.dev/slack"; |
| 14 | +import { streamText } from "ai"; |
| 15 | +import { anthropic } from "@ai-sdk/anthropic"; |
| 16 | + |
| 17 | +export const supportAgent = chat.agent({ |
| 18 | + id: "support-agent", |
| 19 | + channels: [slack({ id: "support-slack", token: process.env.SLACK_BOT_TOKEN! })], |
| 20 | + run: async ({ messages }) => streamText({ model: anthropic("claude-sonnet-4-5"), messages }), |
| 21 | +}); |
| 22 | +``` |
| 23 | + |
| 24 | +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. |
| 25 | + |
| 26 | +## Slack |
| 27 | + |
| 28 | +`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`. |
| 29 | + |
| 30 | +<Steps> |
| 31 | + <Step title="Create a Slack app"> |
| 32 | + Create an app at [api.slack.com/apps](https://api.slack.com/apps). Add the `chat:write` and `channels:history` bot scopes (`chat:write` posts replies; `channels:history` receives the `message.channels` events), then install it to your workspace to get a bot token (`xoxb-...`). If you add scopes after installing, reinstall the app to apply them. |
| 33 | + </Step> |
| 34 | + <Step title="Deploy the agent + connect the endpoint"> |
| 35 | + Deploying registers a hosted [endpoint](/webhooks/connect) for the channel. Set its signing secret to your Slack app's **Signing Secret**, and pass the bot token as `token`. |
| 36 | + </Step> |
| 37 | + <Step title="Subscribe to events"> |
| 38 | + In the app's **Event Subscriptions**, set the request URL to the endpoint's webhook 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`). |
| 39 | + </Step> |
| 40 | +</Steps> |
| 41 | + |
| 42 | +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: |
| 43 | + |
| 44 | +```ts |
| 45 | +slack({ |
| 46 | + id: "support-slack", |
| 47 | + token: process.env.SLACK_BOT_TOKEN!, |
| 48 | + // ignore anything but questions (composed with the built-in self-message guard) |
| 49 | + filter: "event.event.text contains '?'", |
| 50 | + inbound: (e) => e.event?.text ?? "", |
| 51 | + outbound: (reply) => ({ text: reply.text }), |
| 52 | + ack: (e) => ({ text: "thinking..." }), // pass `null` to post only the final answer |
| 53 | +}); |
| 54 | +``` |
| 55 | + |
| 56 | +<Note> |
| 57 | + `slack()` always drops the bot's own messages (and their edits) before they reach the agent, so the |
| 58 | + agent never replies to itself. A multi-workspace app can pass a `token` resolver keyed on the event's |
| 59 | + team instead of a single string. |
| 60 | +</Note> |
| 61 | + |
| 62 | +### Summoning with a mention |
| 63 | + |
| 64 | +By default `slack()` starts (or resumes) a session for every non-bot message in a subscribed channel. To make the agent respond only when it is @mentioned, pass `startOn` with the `mentions` helper. The first mention in a thread starts the session, and the agent then follows the rest of the thread without needing to be mentioned again. |
| 65 | + |
| 66 | +```ts |
| 67 | +import { slack, mentions } from "@trigger.dev/slack"; |
| 68 | + |
| 69 | +slack({ |
| 70 | + id: "support-slack", |
| 71 | + token: process.env.SLACK_BOT_TOKEN!, |
| 72 | + startOn: mentions("U012BOT"), // your bot's user id (pass several for multiple bots) |
| 73 | +}); |
| 74 | +``` |
| 75 | + |
| 76 | +### Reacting to messages |
| 77 | + |
| 78 | +`slack()` can add an emoji reaction to the triggering message to signal progress. Set `reactions` with any of `working`, `done`, and `error`: the connector adds `working` when the turn starts, swaps it to `done` when the turn finishes, and reacts with `error` if it fails. This needs the `reactions:write` scope. |
| 79 | + |
| 80 | +```ts |
| 81 | +slack({ |
| 82 | + id: "support-slack", |
| 83 | + token: process.env.SLACK_BOT_TOKEN!, |
| 84 | + reactions: { working: "eyes", done: "white_check_mark", error: "warning" }, |
| 85 | +}); |
| 86 | +``` |
| 87 | + |
| 88 | +### Options |
| 89 | + |
| 90 | +| Option | Type | Description | |
| 91 | +| --- | --- | --- | |
| 92 | +| `id` | `string` | Connector id, unique per agent. | |
| 93 | +| `token` | `string` or resolver | Bot token (`xoxb-...`), or a function of the event's team for multi-workspace apps. | |
| 94 | +| `key` | `string` | Session [key](/webhooks/session-routing) template. Defaults to one session per thread. | |
| 95 | +| `filter` | `string` | Extra [filter](/webhooks/filters), composed with the built-in self-message guard. | |
| 96 | +| `startOn` | `string` | Only start a session when the event matches (see `mentions`). Existing sessions always resume. | |
| 97 | +| `ack` | message, `null`, or function | Placeholder posted while the agent works. Pass `null` to post only the final answer. | |
| 98 | +| `reactions` | `{ working?, done?, error? }` | Lifecycle emoji reactions on the triggering message. | |
| 99 | +| `inbound` / `outbound` | functions | Map the Slack event to the turn, and the reply to a Slack message. | |
| 100 | +| `delivery` | `"final"` or `"stream"` | `"final"` (default) posts a placeholder and edits it to the answer. `"stream"` edits live as the reply streams. | |
| 101 | +| `apiBaseUrl` | `string` | Override the Slack Web API base, for testing against a mock. | |
| 102 | + |
| 103 | +## Approvals and interactive controls |
| 104 | + |
| 105 | +An agent on a channel can pause a turn to get a human decision, approving a refund or confirming a deletion, and resume once someone clicks a button in the thread. `slack()` renders Approve / Deny buttons for you and collapses them to the decision once clicked. See [human-in-the-loop](/webhooks/human-in-the-loop). |
| 106 | + |
| 107 | +## Any surface: `chat.channels.custom` |
| 108 | + |
| 109 | +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`: |
| 110 | + |
| 111 | +```ts |
| 112 | +import { chat } from "@trigger.dev/sdk/ai"; |
| 113 | +import { webhooks } from "@trigger.dev/sdk"; |
| 114 | + |
| 115 | +const mySurface = chat.channels.custom({ |
| 116 | + id: "my-surface", |
| 117 | + source: webhooks.custom<MyEvent>({ /* verifier config */ }), |
| 118 | + key: "{body.conversationId}", |
| 119 | + inbound: (e) => e.text, |
| 120 | + outbound: (reply) => (reply.text ? { text: reply.text } : null), // null posts nothing |
| 121 | + send: async (message, ctx) => { |
| 122 | + const ref = await postToMySurface(ctx.event, message.text, ctx.previousRef); |
| 123 | + return { ref }; // an existing ref means edit-in-place on the next turn |
| 124 | + }, |
| 125 | +}); |
| 126 | +``` |
| 127 | + |
| 128 | +`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). |
| 129 | + |
| 130 | +## Channels vs events |
| 131 | + |
| 132 | +Both are inbound surfaces on a `chat.agent`, and an agent can list both: |
| 133 | + |
| 134 | +- [`events`](/webhooks/session-routing) (`chat.event`): the webhook is a signal. Delivered to `onAction`; the agent acts, no reply is sent back. |
| 135 | +- `channels` (`slack`, `chat.channels.custom`): the webhook is a chat frontend. Delivered as a turn to `run()`; the reply is posted back. |
0 commit comments