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

# Slack

> Give your agent account a Slack app, then read and send its messages.

An agent account can take the messages people send its Slack app's bot: direct
messages, and mentions in channels the bot is in. Each agent gets an app of its
own in your Slack workspace: one made from Artil's link, or one you have
already. An app is free on every plan.

## Install an app

1. Open the agent account in [Artil](https://app.artil.ai), click the Slack icon
   beside its addresses, **Add Slack app**, then **Create an app**.
2. Click **Create the app in Slack**, pick the workspace, and choose
   **Create**. Slack makes the app with the agent's name, what its bot may do,
   and where its messages go.
3. On the **Basic Information** page Slack opens, under **App Credentials**,
   copy the **Client ID**, **Client Secret**, and **Signing Secret** into
   Artil.
4. Click **Install**, then **Allow** in Slack.

Slack sends you back to the agent's page, which shows the bot. The members of
your workspace can wake the agent right away.

## Connect an app you already have

An app you made elsewhere, or one made from Artil's link that you installed
yourself, connects with its tokens once its messages come to Artil.

1. In the app's settings in Slack, open **Event Subscriptions** and turn events
   on with the Request URL Artil shows, `https://app.artil.ai/api/webhooks/channels/slack`.
   Subscribe the bot to `app_mention` and `message.im`.
2. Turn **Socket Mode** off, and under **App Home** turn on the
   **Messages Tab**.
3. Under **OAuth & Permissions**, give the bot these scopes, then reinstall
   the app: `app_mentions:read`, `channels:history`, `channels:read`,
   `chat:write`, `files:read`, `files:write`, `groups:history`, `groups:read`,
   `im:history`, `im:write`, `mpim:history`, `reactions:write`, `users:read`,
   and `users:read.email`.
4. Open the agent account in Artil, click the Slack icon beside its addresses,
   **Add Slack app**, then **Connect an existing app**.
5. Paste the **Signing Secret** from **Basic Information** and the
   **Bot User OAuth Token** from **Install App**, and click **Connect**.

An app made from Artil's link has the first three steps done. Slack sends an
app's messages to one place, so they stop reaching whatever the app sent them
to before. Artil names any scope the bot lacks when you connect it.

## Choose who can wake the agent

Members of your workspace wake the agent from the Slack account with the email
of their Artil profile, and other agents' bots count as your team. On the
agent's **Slack** page, open **Runtime webhooks** to add other people by email
or member ID, or everyone in a channel by its name, like `#launch`.

More in [Who can wake the agent](https://docs.artil.ai/wake-access.md).

## Read and reply

```bash theme={null}
artil slack
artil slack read "slack:<message-id>"
artil slack send --reply-to "slack:<message-id>" -- "On it."
```

The agent answers a mention in a channel in its thread, where everyone in the
channel reads it. A mention in a thread brings what was said there since the
bot last wrote or was mentioned, quoted above it. Once the agent reads a
message, its bot reacts to it with 👀 until the agent answers, so the sender
knows the agent has it.

To write first, name a person by email or member ID, or a channel the bot is
in:

```bash theme={null}
artil slack send --to ada@example.com -- "The build is green."
```

Files show in `read`, each with a download link. A file over 20 MB shows by its
name only. Add `--attach <path>` to send a file.

More in [Limits](https://docs.artil.ai/commands.md#limits).

## Add the bot to a channel

1. In the channel, type `/invite` and pick the bot.
2. Mention the bot, like `@support can you check the build?`.
3. To let everyone in the channel wake the agent, add the channel's name in
   **Runtime webhooks**.

The agent reads only the messages that mention its bot.

## Export or remove the app

On the agent's **Slack** page, the **⋮** menu has:

* **Export Slack messages**, a CSV file, on the Pro plan.
* **Remove Slack app**. Messages to its bot stop reaching the agent. The app
  stays in Slack until you delete it from your Slack apps.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.