> ## Documentation Index
> Fetch the complete documentation index at: https://keystroke.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# External channels

> Connect agents to Slack channels with the Keystroke Slack App or a custom Slack app.

External channels let people talk to agents in apps like Slack. Slack is the only external channel supported today.

## Slack connection kinds

In the web app, **Apps → Connect Slack** offers three options. The CLI mirrors them with `keystroke connect slack --kind <kind>` (no `--kind` opens the same chooser):

| UI label                   | CLI command                       | Catalog slug                                                   | Identity                         | Use when                                                                                                                     |
| -------------------------- | --------------------------------- | -------------------------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Keystroke Slack App**    | `connect slack --kind keystroke`  | `slackbot`                                                     | Acts as **@Keystroke**           | Bot tools **and** External Channels — bind an agent to a specific Slack channel                                              |
| **Custom Slack App**       | `channels setup <agent> --custom` | `slack-app:<handle>` (credential instance is still `slackbot`) | Acts as **your bot** (`@handle`) | Give one agent its own name, avatar, and handle; gateway mentions/DMs **and** the same `@keystrokehq/slackbot/actions` tools |
| **Personal Slack Account** | `connect slack --kind personal`   | `slack`                                                        | Acts as the **installing user**  | Posts as that person — **not** for External Channels                                                                         |

<Note>
  **The Keystroke Slack App and the `slackbot` catalog slug are the same thing.** The Apps page and
  chooser say "Keystroke Slack App"; `keystroke credentials list` and imports like
  `@keystrokehq/slackbot/actions` show the underlying catalog slug `slackbot`. `keystroke connect
      slackbot` still works and opens the same dialog as `connect slack --kind keystroke`.
</Note>

<Note>
  **Custom Slack App tools use the same package and credential key.** Keystroke and custom installs
  both materialize `slackbot` credentials; the OAuth connection behind the instance (gateway `slack`
  vs `slack-app:<handle>`) is what changes the bot identity. Import
  `@keystrokehq/slackbot/actions` for either. Existing custom apps may need a reinstall to pick up
  scopes such as `chat:write.public` or `users:read.email`.
</Note>

For channel-specific bindings as **@Keystroke**, connect the **Keystroke Slack App**
(`--kind keystroke`). For a dedicated agent identity, use the Custom Slack App flow. A Personal
Slack Account connection does **not** register a gateway workspace
(`keystroke channels accounts --platform slack` stays empty).

## Example requests

Ask your coding agent which agent to put in Slack and how it should respond.

> "Put our support agent in the #support channel and have it reply only when mentioned."

> "Connect the data analyst agent to #data so the team can ask questions there."

> "Give Delbert its own Slack handle so it can be mentioned in any channel."

## Connect agents to Slack (web)

Each agent's detail page has an **External Channels** panel (right side).

<Steps>
  <Step title="Open the agent">
    Go to **Agents** and select your agent. Open the **External Channels** panel (configure rail).
  </Step>

  <Step title="Choose Keystroke app or custom app">
    Click **Connect**. Pick **Use the Keystroke Slack App** (channel bindings as @Keystroke) or **Create your own Slack App** (one agent ↔ one custom bot identity).
  </Step>

  <Step title="Keystroke path — add a channel">
    If the Keystroke Slack App isn't connected yet, complete OAuth first. Then **Add to a Slack Channel** to create a channel (default `#agent-slug`) or pick an existing one.
  </Step>

  <Step title="Custom path — wizard">
    Follow the custom app wizard (name + handle → Slack manifest → paste Client ID / Secret / Signing Secret → install). The agent binds to the whole app automatically.
  </Step>

  <Step title="Message the agent">
    Message the bound channel (Keystroke) or mention the custom bot. Review runs in **History** by filtering **Type** to **Agent**.
  </Step>
</Steps>

Coding agents can deep-link into these flows with `?rail=configure&slack=keystroke` or `slack=custom` on the agent URL (or `keystroke channels setup <slug> --custom`).

## Channel access and credentials

Once an agent is bound to a Slack channel (or custom app), anyone who can message it uses the **agent's** tools and credentials — not their own. Only bind agents to channels whose members you trust with everything the agent can do.

## Manage Slack from the CLI

Prefer the happy path for the Keystroke Slack App:

```bash theme={null}
keystroke connect slack --kind keystroke              # opens the OAuth flow in a browser
keystroke connect slack --kind keystroke --print-url  # headless: print the URL to share with the user
keystroke connect slack --kind keystroke --wait       # wait for the user to finish OAuth
```

(On a local machine that has never authenticated, run `keystroke auth login` first. Hosted sessions are already authenticated and must use `--print-url`, since they cannot open a browser.)

Verify the gateway workspace registered before binding:

```bash theme={null}
keystroke channels accounts --platform slack
# If empty, connect the Keystroke Slack App (above), then:

keystroke channels setup support --channel support
keystroke channels list support
```

`channels setup` creates the Slack channel when needed (or binds an existing one with the same name), then binds the agent with **Mentions + follow-ups** (same default as the web UI).

For a **custom @handle**, open the agent wizard (user finishes in the browser):

```bash theme={null}
keystroke channels setup support --custom
```

### Advanced primitives

Reply behavior matches the External Channels UI:

| `--replies`                            | UI label              | Behavior                                         |
| -------------------------------------- | --------------------- | ------------------------------------------------ |
| `mentions-followups` (default on bind) | Mentions + follow-ups | @mention to start; keep listening in that thread |
| `mentions`                             | Mentions only         | Only responds when @mentioned                    |

```bash theme={null}
keystroke channels platforms list
keystroke channels directory --platform slack --account <team-id>
keystroke channels bind support --platform slack --account <team-id> --channel <channel-id>
keystroke channels bind support --platform slack --account <team-id> --channel <channel-id> --replies mentions
keystroke channels unbind support <binding-id>
keystroke channels update-binding support <binding-id> --replies mentions
```

The agent positional takes the **slug** from `defineAgent({ slug })` after deploy (or the platform agent id). See the [CLI reference](/docs/cli#channels).

Connecting the Keystroke Slack App registers the gateway for your organization; you don't need to add Slack to `keystroke.config.ts`.

## Other external channels

Additional external channels listed below will be added over the coming weeks. You can request specific channels by contacting us at [team@keystroke.ai](mailto:team@keystroke.ai) and we will add them promptly.

* Microsoft Teams
* Telegram
* WhatsApp
* Linear
* Discord
* Google Chat

## Next steps

<CardGroup cols={2}>
  <Card title="Run agents" href="/docs/learn/agents/run-agents">
    Prompt the same agent directly while testing channel behavior.
  </Card>

  <Card title="Agent runs" href="/docs/learn/logs/agent-runs">
    Inspect Slack-started agent sessions in History.
  </Card>

  <Card title="Credentials" href="/docs/learn/credentials/connect-credentials">
    Connect OAuth credentials used by tools and integrations.
  </Card>

  <Card title="Build agents" href="/docs/learn/agents/build-agents">
    Tune the agent prompt and tools for channel use.
  </Card>
</CardGroup>