Use agents, webhooks and the API in Chat

You can ask an agent in a channel, as you would in the assistant's panel. The agent's answer is a message of the channel, and everyone who reads the channel reads it.

1. In a channel, type @. After the users, the list offers the agents you may chat with, each marked Agent: the Assistant, and each agent your role may chat with (Chat with an agent), in Base Captain or on a machine.
2. Pick one, write your question and send it, for example "@Order check which open orders does Acme have?" Everyone in the channel sees your message, as any other.
3. While the agent works, you see that it is answering under your message, with Stop to end it. When it ends, the answer is posted in the channel, under the agent's name and picture, with the mark Agent. It is a message of the channel when you wrote a message of the channel, and a reply in the thread when you wrote a reply.

Who reads the answer, and who applies its cards

• In a private channel, a direct message or a group chat, its users read the agent's answer. To get an answer for yourself only, ask the agent in your own chat: the assistant's panel or the Chat page (Chat with an agent).
• The agent still works as you, the person who asked: your role decides what it reads and does, in the base, through an API token or through an AI client. Because everyone in the channel reads its answer, it keeps out what the channel's users may not read. A mention of an agent sends nobody a notification.
• Whatever the agent would write, an item, a change to the base, a message, a comment, comes as a card under its answer (See a change before it happens). Everyone who reads the channel sees the card, but only you, who asked, click Apply, and nothing happens before you do. Cancel tells the agent that you declined. The other users read "Only" and your name, then "can apply this", in place of the buttons.
• Nobody edits an agent's answer. You, who asked, and whoever moderates the channel delete it.

A machine agent in a channel

A machine agent answers in a channel too (Put an agent on a machine). It runs on its machine, as you, and whatever it would write, a new item or a change too, comes as a card. Its run ends at the card: when you click Apply, the change is made and the agent goes on with the result, and its answer comes then. It runs on its coding tool's own account. While its machine is offline, the mention is refused, with the reason under your message.

What the agent reads and remembers

• An agent in a channel reads only the thread that asks it: the message at its top and the replies up to yours. It never reads the channel's other messages or other threads, and what people wrote there is read as their words, not as orders it follows. Mention it again in the same thread and it goes on from its last answer, with the thread read again.
• An agent's message never starts another agent. An @ in it starts nothing and tells nobody.

The AI it uses, and when a mention is refused

• An agent in a channel uses the AI as a chat does: the assistant and the agents on Base Captain use the plan's AI (What AI your plan includes), and an agent on the Claude API or the OpenAI API uses the AI of its own service.
• When a mention is refused, because your role may not chat with that agent, the base keeps its data from AI, you already have an answer running or the limit is reached, the reason shows under your message.
• While the base keeps its data from AI, no agent answers in its channels (Keep your records away from AI).
• An agent may not judge people: no decisions about whom to hire, how a worker performs or who gets credit (Acceptable use).

An incoming webhook lets another service post messages in a channel, such as a shop that tells of each new order or a build server that tells of each build. Each webhook has a name and a URL. The service sends its message to the URL, and the message shows in the channel under the webhook's name, with the mark Bot. Only the channel's managers and the base's admins see a channel's webhooks and add, change and delete them.

1. Open the channel's settings and go to Webhooks.
2. Click Add webhook and give it a Name, such as "Deploys".
3. Copy the URL. Base Captain shows it only once: keep it in the other service. Anyone who has the URL can post in the channel.

The service sends a POST with the text of the message as JSON:

curl -X POST https://<your base>/api/hooks/channel/<token> \
  -H 'Content-Type: application/json' \
  -d '{"text": "Build 42 passed"}'

The webhook's text is Markdown, as a message you write. Its @ mentions do not notify anyone. The message counts as unread and notifies the users who get every message of the channel, as any other message. Nobody edits it; a moderator or a manager deletes it as they delete another user's message. Agents in the channel do not take its text as a request from a person.

Rename, change the URL or delete a webhook

• Rename changes the webhook's name for the next messages. The messages it posted before keep the old name.
• New URL gives the webhook a new URL, shown once. The old URL stops at once: use this when the URL gets out.
• Delete deletes the webhook. Its URL stops, and the messages it posted stay in the channel.

Incoming webhooks in Chat have these limits:

• A webhook's text is up to 10,000 characters, as a message you write.
• A webhook takes up to 60 messages a minute, as an automation's webhook does; past that, the service must wait for the next minute. Its calls count in the base's usage.
• A webhook posts also when Users can post new messages is off.
• In an archived channel, a webhook's messages are refused until the channel is restored.
• Direct messages and group chats have no webhooks.

Everything in Chat works with an API token too, as you, under your role (Use your base from a script with an API token). A channel is an item of the built-in table _channels, and its messages are its comments. In a base where your role is an external one, /api/chat/people and /api/chat/status answer 403.

Channels

• GET /api/tables/_channels/items lists the channels you may read.
• POST /api/tables/_channels/items makes a channel, and PUT and DELETE on /api/tables/_channels/items/<id> change and delete it. Only the channel's managers and the base's admins change or delete it.
• A channel's fields are name, description, private, default (an admin's only), users, which is set only when the channel is made, add_users, managers or users (who can add users), group_mentions, users or managers (who can use @channel and @here), post_messages and reply_messages (users can post new messages, users can reply to messages; both true at first) and archived.
• A channel also lists its managers and moderators, which change only through their own route, …/users/<user>/role under Users and roles of a channel.
• A channel also says whether it is direct; a direct message or a group chat is not made, changed or deleted this way.

Users and roles of a channel

• POST /api/channels/<id>/join and POST /api/channels/<id>/leave join a public channel and leave a channel you joined.
• POST /api/channels/<id>/users with {"users": ["<id>"], "roles": ["sales"]}, either or both, adds users, for the channel's managers and the base's admins, or for every user of the channel when add_users is users. It answers the channel's users and who was added.
• DELETE /api/channels/<id>/users/<user> removes one user, for who moderates the channel, and answers the channel's users.
• PUT /api/channels/<id>/users/<user>/role with {"role": "moderator"} (or manager, or user for no role) gives or takes a role, for the channel's managers and the base's admins, and answers the channel's managers and moderators.

Moderation

• GET /api/channels/<id>/log reads the moderation log, newest first, 100 entries at a time; add before=<time> for older ones.
• PUT /api/channels/<id>/bans/<user> with {"minutes": 1440, "reason": "Spam"} bans a user, for good when minutes is left out, and answers the ban and the channel's users.
• PUT /api/channels/<id>/timeouts/<user> with {"minutes": 10, "reason": "Calm down"} times a user out, up to 43200 minutes (30 days).
• DELETE on a ban or a timeout ends it before its time.
• GET /api/channels/<id>/bans lists the channel's active bans and timeouts. The routes of bans and timeouts are for who moderates the channel.
• GET /api/channels/bans lists your own, in every channel of the base, each with its channel, until (null for good) and reason.
• DELETE /api/tables/_channels/items/<id>/comments/<message> deletes a message. To delete another user's message as its moderator, send the reason: {"reason": "Off topic"}.

Direct messages, people and status

• POST /api/channels/direct, with users the ids of the other users, 1 to 8, answers the id of your conversation with exactly them, and created when it is new.
• GET /api/chat/people lists every user of the base's team, you included, each with its user id, whether it is active and its status, or null when it has none or its status ended.
• GET /api/chat/status reads your own status.
• PUT /api/chat/status with {"emoji": "📅", "text": "In a meeting", "until": "2026-10-10T15:00:00Z"} sets it, in place of the one you had; leave out until for a status with no end.
• DELETE /api/chat/status clears it.

Messages

• GET /api/tables/_channels/items/<id>/comments reads the latest 200 messages, oldest first, each with its number of replies; add before=<time> for older ones, or parent=<message id> for one thread's replies.
• Each message has its previews: the cards of the items it links to (Show an item's card from its link), each with the item's table, id, label, href and up to three fields, as you may read them, and [] for none.
• POST /api/tables/_channels/items/<id>/comments sends a message, with text, files, mentions, groups (channel, here or role: and a role's key, such as role:sales, with @channel, @here or @Sales in the text), agents (the keys of the agents it asks, at most five, assistant for the assistant) and, for a reply, parent.
• Each message answers its agents and, for an agent's answer, the agent it came from: only an agent's run sets agent, and a message sent with it is refused. Nobody edits a message that has an agent: PATCH answers 400.
• GET, PATCH and DELETE on /api/tables/_channels/items/<id>/comments/<message id> read one message, edit your own, or delete your own. Each message carries its reactions, and a removed user's its author as removed user.
• PUT /api/tables/_channels/items/<id>/comments/<message id>/reactions with {"emoji": "👍", "on": true} adds your reaction, and "on": false takes it away.
• GET /api/tables/_channels/items/<id>/mentions?q= lists who and what you may mention: the people, then the groups and the roles, then the agents.

Agents in a channel

• POST /api/assistant/mentions with {"channel": "<id>", "message": "<message id>"} starts the agents of a message you sent, and answers which ones started and which were refused, with the reason. The web does this for you; with a token you make the call yourself.
• GET /api/assistant/mentions?channel=<id> reads your own mentions in the channel with their refusals, and the cards of every agent's answer posted in it, whoever asked. The agent posts its answer itself: it is a message of the channel, read with the channel's messages.
• POST /api/assistant/cards/<id> applies or cancels a card, for the person who asked only.
• POST /api/assistant/listen with the same body tells the assistant of a message you sent that mentions no agent. Where the assistant or an agent is present (in a public channel, in a thread where it answered your mention, or in a chat where a user added it), it may answer in the chat or stay silent. The call answers 204 and nothing more. The web does this for you; with a token you make the call yourself, or the assistant does not hear the message.
• PUT /api/assistant/listen/chats/<id> adds the assistant to a private channel, a group chat or a direct message, and DELETE removes it; with ?agent=<key> both do the same for an agent of the base. GET /api/assistant/mentions?channel=<id> answers listens, whether it is present, agents, the agents added there, and heard, the answers nobody asked for; POST /api/assistant/listen/not-needed with channel and message removes one of those.

Pins, bookmarks and webhooks

• GET /api/channels/<id>/pins lists the channel's pinned messages, the newest pin first; PUT and DELETE on /api/channels/<id>/pins/<message id> pin and unpin a message. Each message carries its pinned: who pinned it and when, or null.
• GET /api/channels/<id>/bookmarks lists the channel's bookmarks; POST on it with {"title": "Price list", "url": "/products"} adds one, and PUT and DELETE on /api/channels/<id>/bookmarks/<bookmark id> change and delete it, for the channel's managers and the base's admins.
• GET /api/channels/<id>/webhooks lists the channel's webhooks; POST on it with {"name": "Deploys"} makes one and answers its url, once.
• PUT on /api/channels/<id>/webhooks/<webhook id> with {"name": "CI"} renames a webhook, POST on …/<webhook id>/url gives it a new url and stops the old one, and DELETE deletes it. The routes of webhooks are for the channel's managers and the base's admins.
• A webhook's message carries its author as {"id": null, "name": "Deploys", "kind": "bot"}.

Unread messages, notifications and keywords

• GET /api/channels/unread gives your unread count per channel and in all.
• POST /api/channels/<id>/read marks a channel read, and POST /api/channels/<id>/unread with {"message": "<message id>"} marks a message and the later ones unread.
• The unread count also lists in notify the channels whose notifications are not the usual ones; PUT /api/channels/<id>/notify with {"notify": "all"}, "mentions" or "none" sets them.
• PUT /api/me/settings with {"chat_keywords": "refund, invoice"} sets your keywords in the base.

Import from Slack

POST /api/channels/import, for the users who build the base, imports a Slack export zip uploaded first with POST /api/files, and answers the import's background job.

The tools of the assistant and AI clients

The assistant and the AI clients that reach the base through Base Captain's MCP server use the tools list_channels, read_channel, send_message, edit_message, delete_message, react_message, pin_message, set_bookmark, delete_bookmark, set_webhook, new_webhook_url, delete_webhook, set_channel_notifications, mark_unread, join_channel, leave_channel, add_channel_users, remove_channel_user, set_channel_role, read_channel_log, ban_channel_user, timeout_channel_user, end_channel_ban, list_channel_bans, create_channel and, for the users who build the base, import_slack. As on the Chat page:

• list_channels lists your channels, direct messages and group chats, each with your role in it and your own ban or timeout there;
• delete_message takes a reason, required for another user's message;
• read_channel gives the channel's pinned messages and bookmarks too, each message with its previews, and its webhooks to its managers and the base's admins;
• update_item turns post_messages, reply_messages and archived on and off;
• set_webhook makes a webhook and gives its URL, or renames one; new_webhook_url gives a new URL and stops the old one; delete_webhook deletes a webhook;
• find_users on a channel lists the groups and the roles too, and send_message and edit_message take them in their groups;
• create_channel takes group_mentions, and the preferences tool sets your chat_keywords;
• start_direct_message starts a direct message or a group chat with users named by name or email address, and answers its id, which send_message and the other channel tools then take;
• get_status tells whether a user of the base's team is active and reads their status, your own when no user is given;
• set_status sets your status, with an emoji, a text and an until, which is never when it is left out; clear_status clears it.

No tool changes how long messages are kept: that is in Settings, Chat only. The tools rename and delete a channel as they do any item, for the channel's managers and the base's admins only.

Agents through the tools

An agent's message carries its name and the mark Agent. An AI client asks agents with send_message and its agents, and reads the cards of their answers with list_answers; the answers themselves are messages of the channel, which read_channel gives. The assistant reads them too; it does not ask an agent in a channel itself. An agent answering a mention reads only its thread: it has none of the tools that read a channel or your answers.