---
title: Slack & channels
description: Connect Slack to a project and control sessions from a channel.
---

A channel connects a chat platform to a project. A message in a connected
channel starts a [session](/docs/work/sessions). The agent replies in the
same thread.

## Live channels

Beeuni supports four channel platforms today:

- **Slack** — connect with one click through the Beeuni-managed app, or bring
  your own bot token.
- **[Microsoft Teams](/docs/connect/teams)** — connect with your organization's administrator approval, or bring your own Azure Bot.
- **[Telegram](/docs/connect/telegram)** — connect a BotFather bot and choose who can send it tasks.
- **Email** — an AgentMail-backed channel (experimental; enable it under
  [Settings → Feature flags](/docs/feature-flags)).

This page covers Slack.
Teams follows the same session, identity-linking, and credential rules.

## How a channel starts a session

The first message in a Slack thread or Teams conversation creates a session.
The thread keeps that session, even after the sandbox stops and resumes.

In a Slack channel, a later message reaches the session only when it mentions
the bot. Untagged replies are for the people in the thread. The agent reads
them the next time someone mentions it. In a direct message, every message goes
to the session.

A Slack workspace connected to more than one
project shows a project picker on the first mention.

## Identity linking

Beeuni links each chat sender to a Beeuni account before the agent runs for
them. Run `/beeuni login` in Slack and follow the link to sign in. Teams uses
the same requirement. An unlinked sender gets a prompt to link instead of a
session run.

A sign-in link works once and expires after 10 minutes. A Slack account that is
connected to one Beeuni account cannot be connected to another: run
`/beeuni logout` first. If your organization requires two-factor
authentication, complete it before linking your account.

Every action runs as the linked account of the person who took it, with that
account's project role. Account owners and admins count as project managers.

| Action | Who may do it |
|---|---|
| Mention the bot, in a new message or in its thread | A linked account with access to the project, within the channel's policy |
| Stop a run | The current prompt's sender, the session owner, or a project manager; each must have `project.session.stop` |
| Change the channel's project, agent, model or policy | A project manager; in a DM with the bot, any project member |
| Act on a review | A project manager |
| Approve or deny a connector call | A project manager, or the person who started the session |
| Approve someone into an `owner_approval` thread | The session owner |
| `link-bot` | A project manager |

## Where credentials live

A connected channel's bot token is a connector-scoped
[secret](/docs/project/secrets). It does not appear on the project's Secrets
page. Beeuni never injects it into a sandbox. Beeuni resolves the token
server-side when the agent sends or reads a chat message.

## Connect Slack

1. **Start the connection**

    From the CLI, run:

    ```
    beeuni channels connect
    ```

    On a host with the shared Slack app configured (Beeuni Cloud, for example),
    this prints a one-click install link. Open the link and pick the workspace.
    Click **Allow**. Add `--wait` to make the command poll until the install
    lands.

    From the dashboard, open the project's Channels page and connect Slack there
    instead. It uses the same install flow.

2. ### Use your own Slack app

    To use your own Slack app, run `beeuni channels manifest` to print an app
    manifest. Create the app at
    `api.slack.com/apps` from that manifest. Install the app to your workspace.
    Then run:

    ```
    beeuni channels connect --manual --bot-token xoxb-... --signing-secret ...
    ```

3. **Check the connection**

    ```
    beeuni channels status
    ```

    Run `beeuni channels disconnect` to remove the connection. See the
    [CLI reference](/docs/cli) for every flag.

Connecting Slack adds a `channel` [connector](/docs/connect/connectors) entry
to `beeuni.yaml` for you. You never write this entry by hand.

## Use Slack

Mention the bot with a task, in any channel it has joined, or open a direct
message. The thread keeps its session as described above. Mention the bot
again in a channel thread to follow up. A bare mention with
no task gets a reminder to add one instead of starting a session.

## What the agent can read

The agent reads Slack through the project's Slack
[connector](/docs/connect/connectors) (`beeuni_slack`, or the `slack` command
in the sandbox). Every project connected to the same Slack workspace uses the
same bot, so Beeuni keeps each read inside the project's own conversations:

| Conversation | Read |
|---|---|
| A channel or DM connected to this project | Allowed |
| A thread that a session of this project started or joined, in any channel | Allowed |
| A channel, DM or thread of another project | Refused |
| A conversation no project is connected to | Allowed only while no other project is connected to the workspace |

A refused read answers `403` with the reason `conversation_not_in_project` and
a message that names the conversation. To read a conversation that no project
is connected to, connect it first: run `/beeuni switch` in it and pick this
project.

- Channel history leaves out the messages of another project's thread.
- `get_history` and `get_thread` add `user_name` to each message whose author
  Slack can name, beside the `user` id. Up to 25 people are named per read;
  a name Slack does not return within 2 seconds is left out.
- `list_channels` lists every public channel, and the private channels and DMs
  the agent may read.
- `channel_info` answers for any public channel. A private channel or DM
  follows the table above.
- `file_info` answers when the file is shared in a conversation the agent may
  read, or in a thread of this project. `slack download` follows the same rule: a file shared only in another
  project's conversation answers `403`. A download stops at 50 MB and answers
  `413`.
- `search_messages` runs only while no other project is connected to the
  workspace, because a search cannot be limited to one project's
  conversations.
- `list_users`, `user_info` and `auth_test` read the workspace directory and are
  not limited.

Writes follow their own rule, below.

## What the agent can post

Posting, sending a file, editing, deleting, reacting, joining a channel and
binding a thread follow one rule: the agent never acts inside another
project's channel or thread.

| Target | Write |
|---|---|
| A channel of this project, or a thread one of its sessions started or joined | Allowed |
| A channel no project is connected to | Allowed. A new message starts this project's thread, so a reply that mentions the bot comes back to the session |
| A direct message with a person | Allowed, also when that person's DM with the bot runs another project |
| A channel or group DM of another project | Refused |
| A thread of another project, in any conversation | Refused: no reply, edit, delete or reaction |

A refused write answers `403` with the reason `conversation_not_in_project`
and a message that names the conversation. `slack send --file` and
`slack bind-thread` follow the same rule.

`channel` must be the conversation or user id, such as `C0123ABCD` or
`U0123ABCD`, not a channel name. Slack posts to a name, and a name cannot be
checked against the rule. If Slack still posts a message anywhere but the
conversation that was checked, Beeuni deletes the message and refuses the post.

To post in a channel that another project runs, run `/beeuni switch` in it and
pick this project, or post from that project.

## Control a session with slash commands

Type these as `/beeuni <command>` in Slack, or as plain text in a DM. Slash
commands do not run inside the Assistant DM pane, so Beeuni parses the same
words from plain text there.

| Command | What it does |
|---|---|
| `login`, `logout` | Link or unlink your Slack identity |
| `switch`, `unbind` | Rebind or unbind this channel from its project |
| `projects` | List projects you can bind to |
| `sessions` | List recent sessions started in this workspace |
| `whoami` | Show the channel panel: project, agent, model, policy, and your linked identity |
| `models` | Pick the model for this channel — see [Models and keys](#models-and-keys) |
| `agent <name>`, `model <id>` | Set the agent or model this channel uses |
| `policy <mode>` | Set who can start sessions here |
| `help` | List all commands |

`policy` accepts `project_open` (default — any project member who mentions
the bot gets a session), `owner_approval`, or `owner_only`. This is a
per-resource setting on one channel, not a role. It grants no permission the
role verdict denies — see
[Accounts & access](/docs/accounts#per-feature-access-settings).

## Models and keys

`/beeuni models` lists every model you can run here, as the web picker does:
Beeuni models, and models you reach through a provider API key or a ChatGPT
subscription. Each model shows how it is billed. Long lists use a searchable
dropdown. Pick one, or type `/beeuni model <id>`; `/beeuni model default`
goes back to the project default.

Which keys count depends on the conversation:

- **A DM with the bot** — your own keys and ChatGPT subscription, plus keys
  shared with the project. Its sessions are private to you.
- **A channel or group DM** — only keys shared with the whole project. Pick a
  model that runs on your own keys in a DM instead.

A model uses the provider keys available to you and switches between them
when a key reaches a rate limit. The channel's model starts every new thread; a
thread keeps the model it started with. A model a thread can no longer run is
replaced for that message instead of failing it. See
[Provider keys and member access](/docs/project/models#provider-keys-and-member-access).

A follow-up with an image runs on a model that can read images. When no available
model supports images, the agent says it cannot see the
image and asks for the text, instead of guessing.

## Channel and people names

Slack sends ids, such as `C0123ABCD` and `U0123ABCD`. Beeuni shows the names
people read in Slack and keeps the ids for operations.

| Where | What it shows |
|---|---|
| The Channels page, `beeuni channels bindings` | `#channel` for a public or private channel, the person for a DM, the members for a group DM |
| A Slack message in a session | The sender's name and `#channel` |
| A `slack send` reply in a session | `#channel`, or the person of a DM |
| The session title | Mentions as Slack shows them: `@Beeuni`, not `<@U0123ABCD>` |
| The agent's prompt | Names beside ids: `Sam Rivera (U0123ABCD)`, `#general (C0123ABCD)` |
| The agent's plan steps in Slack | A person as `@Sam Rivera`, a channel as `#general`. A step never notifies anyone |
| An approval card in Slack | A channel parameter as a channel link, which Slack names by your own access. A user parameter with the person's name |

A channel that Slack cannot find reads **Unavailable channel** and keeps its
id. This happens when the channel was deleted or the bot was removed from it.
A name that Slack does not return within 2 seconds is left out of that
message. The prompt then carries the ids alone, and the turn does not wait.

## Approvals

When an agent needs a human decision before it proceeds, it files a review item.
If the session was started from this thread, a review card appears here with:
the title, a summary, a risk level, and **Approve**, **Request changes** and
**Deny**.

**Request changes** opens a box for what should change. Whatever you type is
stored with the decision and passed to the agent with it, so it does not have to
ask you a second time. It is optional — send it empty and the agent is told to
ask. Approve and Deny stay one click.

Acting on a review needs a linked Beeuni account with write access to the
project.

## Stopping a run

While the agent works, its live message carries a **Stop** button. This stops
the running task. If the task remains active, the next message in the thread
joins that task instead of starting a new reply.

Only the current prompt's sender, the session owner, or someone who manages the project can stop the run. Each also needs `project.session.stop`. Approval to join a session alone does not grant stop access. The stopped reply names who stopped it when that identity is available.

## What does not work

- Slash commands do not fire inside the Assistant DM pane. Type
  `/beeuni <command>` as plain text there instead.