Channels (chat frontends)

import { webhooks } from "@trigger.dev/sdk";
import { chat } from "@trigger.dev/sdk/ai";
import { slack, webhookSource } from "@trigger.dev/slack";
import { anthropic } from "@ai-sdk/anthropic";

const slackEvents = webhooks.endpoint.define({ id: "slack", source: webhookSource() });

export const supportAgent = chat.agent({
  id: "support-agent",
  channels: [slack({ id: "support-slack", endpoint: slackEvents, token: process.env.SLACK_BOT_TOKEN! })],
  run: async ({ messages, streamText }) =>
    streamText({ model: anthropic("claude-sonnet-4-5"), messages }),
});

​

Slack

​

Linear

​

Approvals and interactive controls

​

Any surface: chat.channels.custom

import { chat } from "@trigger.dev/sdk/ai";
import { webhooks } from "@trigger.dev/sdk";

const surface = webhooks.endpoint.define({
  id: "my-surface",
  source: webhooks.custom<MyEvent>({ /* verifier config */ }),
});

const mySurface = chat.channels.custom({
  id: "my-surface",
  endpoint: surface,
  key: "{event.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 }; // later sends in the same turn get it back as ctx.previousRef
  },
});

​

Stopping a turn from the channel

chat.channels.custom({
  // ...
  onControl: (e) => (e.text.trim() === "/stop" ? { kind: "stop" } : null),
});

​

Status and native streaming

• lifecycle(state, ctx) reports working when a turn starts (and every 50 minutes while it runs), waiting when it pauses on a human decision, idle when it ends for any reason, and closed on chat.close(). ctx.firstTurn and ctx.prompt are there to title a new conversation. Calls are serialized, so an older report never lands after a newer one.
• stream(ctx), with delivery: "stream", returns a per-turn transport { text(delta), progress?(event), end(outcome) }. The runtime feeds it the reply’s markdown deltas and tool progress, then calls end({ stopped, pending, errorText? }) once. Resolve { delivered: true } when the reply reached the surface, and the runtime does not post it again. Call ctx.opened(ref) once the surface has created the stream message: the ref is saved with the session while the turn runs, and if the worker dies mid-stream the next one calls the connector’s endInterruptedStream(ref, ctx) before it answers, so the old stream does not look like it is still being written.

​

Bound sessions

chat.channels.custom({
  id: "my-surface",
  endpoint: surface,
  key: "{event.conversationId}",
  inbound: (e) => ({ message: e.text, externalUserId: e.userId, externalMessageId: e.id }),
  bind: (e) => ({ conversationId: e.conversationId }),
  send: async (message, ctx) => {
    // ctx.event is absent on a bound turn; ctx.handle always carries what bind() returned
    const target = ctx.handle ?? { conversationId: ctx.event!.conversationId };
    return { ref: await postToMySurface(target, message.text, ctx.previousRef) };
  },
});

​

Files, buttons and steering

• download(url, { handle }) fetches files only the surface’s credentials can read. Have inbound return file parts on the surface’s URLs, and the streamText passed to run() asks each connector’s download for every file URL in the prompt (return null for URLs it doesn’t own). Downloads are cached for the run and the transcript keeps the URL. A file download throws on becomes a short note in that turn’s messages, and the turn still runs.
• toAction(event) maps a click on a control the agent posted to an action. It reaches onAction, validated against actionSchema, with the click itself as channel.event. Returning chat.turn(message) answers in the bound thread. Return null for anything else, such as a click answering a pending tool call, which onInteraction handles.
• With pendingMessages on the agent, a channel message that arrives while a turn is running goes through inbound and is offered to shouldInject like a browser message (its metadata.source is "channel"). Stops, clicks and empty messages are never offered.
• received(ctx) acknowledges a channel message that arrives while a turn is running, as soon as it arrives and whether or not pendingMessages folds it in, so its wording should be true either way: slack() reacts with 👀, linear() posts a thought. Stops, clicks and empty messages are not acknowledged.

​

Channels vs events

• events (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.