Skip to main content

Channels

A channel puts your agent in Slack, Telegram, Discord, GitHub, Linear, Pancake, Zalo, WhatsApp, Microsoft Teams, Google Chat, Twilio SMS, Messenger or Instagram. Messages that arrive there become agent turns, and the answer goes back to the same place.

  • A connection is one app install and holds its credentials, such as a Slack bot token.
  • A channel names one room the connection answers in, such as #product-eng.
  • A channel record is what a channel becomes after deploy. It can also route that room to a different agent and add rules for it.

Minimal example​

broods/index.ts
import {
defineAgent,
defineSlackChannel,
defineSlackConnection,
env,
} from "broods";

export const slack = defineSlackConnection({
botToken: env("SLACK_BOT_TOKEN"),
signingSecret: env("SLACK_SIGNING_SECRET"),
});

export const productEng = defineSlackChannel({
name: "product-eng",
connection: slack,
channelId: "C042PRODENG",
});

export const support = defineAgent({
name: "support",
// model, provider, ...
connections: [slack],
});

The agent lists the connection. The channel points at the connection. Nothing points back at a channel, so a channel can name its own connection's agent without a circular reference.

Run broods dev or broods deploy. The CLI syncs the referenced secrets, generates api.channels, and prints the webhook URL to register with the provider.

An agent can hold several connections of different providers. One connection belongs to one agent.

Supported channels​

ProviderReachesRequired connection fieldsCommands
Telegramprivate chats, groups, forum topicsbotToken, webhookSecretyes
Slackchannels, private groups, DMsbotToken, signingSecretyes
Discordguild channels and threadsbotToken, publicKeyyes
GitHubissues, pull requests, comment threadswebhookSecret, appId, privateKeyno
Linearissue comments that mention the agentapiKey, webhookSecret, userNameno
PancakePancake inbox messages and commentspageId, pageAccessToken, webhookSecretno
Zaloprivate chats and groupsbotToken, webhookSecretyes
WhatsAppcustomer chats with a business numberaccessToken, appSecret, phoneNumberId, verifyTokenyes
Teamspersonal chats, group chats, channelsappId, appPassword, appTenantIdyes
Google Chatdirect messages, @-mentions in spacescredentials, googleChatProjectNumber or endpointUrlyes
Twilio SMSSMS and MMS to a Twilio numberaccountSid, authTokenyes
Instagramprofessional account DMsaccessToken, accountId, appSecret, verifyTokenyes
MessengerFacebook Page DMsappSecret, pageAccessToken, verifyTokenyes

Store every secret with broods env set NAME and reference it with env("NAME"). Never inline a token.

Webhook URL​

There is one webhook URL per account and provider. It never names an agent. The account's agent whose credentials verify the request receives it.

StageURL
Production{BROODS_BASE_URL}/v1/webhooks/{accountId}/{channel}
Other stage{BROODS_BASE_URL}/v1/webhooks/{accountId}/dev/{endpointId}/{channel}

broods dev and broods deploy print the right one for the stage:

Channel telegram (telegram): https://gateway.broods.app/v1/webhooks/acct_.../telegram

The stage URL reaches only the stage it names. Use it when two stages share one bot, otherwise both stages compete for the same traffic. Providers that store one webhook per bot, such as Telegram, Zalo, WhatsApp, Teams and Google Chat, move all traffic to whichever URL you registered last. Twilio stores one per phone number or messaging service, so the URL you set last on each number wins for that number.

Where the agent listens​

A connection answers in the rooms declared as channels against it and nowhere else. Messages from an undeclared room are dropped silently.

Setting on the connectionEffect
a define*Channel per roomanswers in those rooms, with that room's rules
allowedChannelIds: ["id"]adds rooms with no rules of their own
allowedChannelIds: ["*"]answers in every room the app can see
allowedUserIds: ["id"]only these senders trigger the agent. Omitted or ["*"] is everyone

A connection that declares no channel and no allowedChannelIds fails broods dev, so it cannot go quiet in production. Direct-message bots cannot know chat ids in advance, so they set allowedChannelIds: ["*"] and gate people with allowedUserIds.

Chat commands​

Telegram, Slack, Discord, Zalo, WhatsApp, Teams, Google Chat, Twilio, Messenger and Instagram route these commands to Broods instead of the agent. GitHub, Linear and Pancake pass slash text to the agent as normal input.

CommandEffect
/new, /clearclear the conversation. Refused while a turn or queued message is active
/compact [instructions]summarize the history after the running turn, whatever session.autoCompaction says
/helplist commands
/steer <text>join the running turn at its next step. Starts a turn when idle
/queue <text>run the text as its own turn after the current one
/queue steer|followup|collect|rejectset the default mode for this conversation
/stop, /cancelstop the running turn after its current step

An ordinary message sent while the agent is busy steers the running turn. See Conversations.

When the deployment is full​

When every worker slot is busy and the run queue behind them is full, a new message is turned away before it is counted against the plan or recorded. Where the provider sends a delivery again after a server error, Broods answers 503 with Retry-After, and the message is admitted on the first retry that finds room; a retry that arrives while the queue is still full gets another 503. Everywhere else the chat is told the agent is busy, so the sender can try again.

ProviderA message the full queue turns away
Telegram, Slack messages, WhatsApp, Messenger, Instagram, Linear503, the provider sends it again
Discord, Slack slash commands and buttons, GitHub, Pancake, Zalo, Teams, Google Chat, Twilioacked, and the chat is told the agent is busy

An account out of budget hears its plan refusal instead, full queue or not.

Channel tools​

On a channel turn the agent gets these tools automatically. Do not add them to config.tools. Hide any of them per room with denyTools on a channel record.

ToolUse
send-updatepost a progress note before the turn ends. Always available
send-messagemessage a chat that has messaged the agent, as a follow-up
send-imagessend pictures from workspace file_paths or from urls
send-filessend workspace documents such as PDFs and spreadsheets
send-stickersend a sticker
send-reactionsreact to a message

Tools other than send-update appear only where the provider supports them. The final reply is still delivered when the turn ends.

send-files and the file_paths argument of send-images need an attached workspace. A file leaves as a durable /v1/media/{ticket} link, and a file in a bare sandbox has no such link. An agent with sandboxes but no workspaces gets no send-files, and its send-images takes urls only.

ChannelPicturesDocumentsBatching
Telegramprovider fetches URLprovider fetches URLalbums of 2 to 10
Slackimage blocksuploadedone message, one upload
Discorduploadeduploadedone multipart message
Pancakeuploadeduploadedone per message
Zaloprovider fetches URLsent as linksone per message
WhatsAppuploaded or linkeduploaded or linkedone per message
Teamslinks in textlinks in texttext only
Google Chatlinks in textlinks in texttext only
Twilioprovider fetches URLsent as linksone per message
Instagramuploaded, or provider fetches URLuploaded, or provider fetches URLone per message
Messengersent as linkssent as linkstext only
GitHublinks in textlinks in texttext only
Linearlinks in textlinks in texttext only

Where a provider has no document endpoint, send-files posts the links as text and tells the model so. If a provider rejects pictures, send-images falls back to sending them as documents or links. A caption rides the first message only.

Inbound attachments​

Media sent to the agent is read while the turn runs.

ChannelWhat arrives
Telegramphotos, video, audio, voice notes, documents, video notes, static stickers
Slackevery file on a message, including voice clips
Discorduploads, voice messages, stickers
Pancakephotos and videos
Zalophotos, stickers, voice notes
WhatsApppictures, documents, audio, voice notes, video, stickers
Teamsfiles and pictures
Google Chatattachments
Instagrampictures, video, audio, files, story replies and mentions
Messengerpictures, video, audio, files
TwilioMMS pictures, audio and video
GitHubnone. A pasted image stays a markdown URL in the text
Linearnone. A pasted image stays a markdown URL in the text

The limits are 6 MB per picture, 25 MB for anything else, and 10 attachments per message. The media type comes from the bytes, not the provider's label. An attachment that cannot be read becomes a line of text saying so, and the rest of the message still arrives.

Pictures reach the model as pictures. A PDF, voice note or video goes over natively only when the model provider accepts that type. Otherwise the agent gets it as a workspace file to open with read or bash. Each message with attachments also carries a short note listing what arrived and where it was stored.

With a workspace attached, each file is saved under media/ in the default workspace. Without one, nothing is stored. The bytes reach the model on that turn, and later turns re-read the file through the provider, so the provider's retention decides how long it works. A Telegram file id lasts indefinitely, a Discord link expires within a day. Attach a workspace when media must outlive the provider, or when the agent must open files rather than look at them.

Voice transcription​

Audio the model cannot hear is transcribed on the way in. An agent whose chat provider ships speech-to-text needs no configuration. Any other agent names one in transcription, with that provider's key in provider:

export const support = defineAgent({
name: "support",
provider: {
anthropic: { apiKey: env("ANTHROPIC_API_KEY") },
openai: { apiKey: env("OPENAI_API_KEY") },
},
model: { provider: "anthropic", modelId: "claude-haiku-5-5" },
transcription: { provider: "openai" },
});
ProviderDefault model
OpenAIwhisper-1
Groqwhisper-large-v3-turbo
Mistralvoxtral-mini-latest
Fish Audiotranscribe-1
Google, Vertexnone. The recording is sent to the model directly

transcription.provider defaults to the chat provider, and transcription.modelId to the model in the table. The defaults accept ogg/opus, which Telegram, Discord and Zalo voice notes use. Cheaper models such as gpt-4o-mini-transcribe refuse ogg.

Fish Audio (fishaudio) only transcribes, so it is valid in provider and transcription.provider but not in model.provider.

A failed transcription never drops the message. The note names the cause, such as a busy provider, a refused format, a missing key for the transcription provider, or a provider with no speech-to-text.

Shared behavior​

  • Typing and reactions. An accepted message triggers a typing indicator and a reaction where the provider supports them. Telegram and Slack reactions are configurable with reactionEmoji. GitHub and Linear react with eyes. Zalo, Teams, Messenger and Instagram show typing only. WhatsApp shows typing and reacts only when the agent calls send-reactions. Pancake, Google Chat and Twilio do neither.
  • Edits. Editing a message never starts a run, on any channel. Send a new message to correct the agent.
  • Tool approval. Tools with needsApproval are denied on channel turns with Tool approval is only supported through the direct API. The model gets two more passes to answer without them; a third denial ends the turn with a message saying so. Keep approval-gated tools off channel agents.
  • Errors. If a turn fails, the room receives a short ⚠️ line with the error simplified, for example a quota or timeout message.
  • Deferred replies. When a turn finishes later, such as a background sandbox job, the result is pushed back into the same chat.
  • Trace links. Replies omit the dashboard trace link. Set trace: "enabled" on the connection to include it. Tracing itself is unaffected.
  • Credentials. A run only sees its own channel's credentials.

Runnable examples live in the packages/demos folder, under channel-* and multi-channel. For how a webhook turns into a run inside the platform, see Channels internals.