Skip to content

Slack Sensor ​

On a deployment with Slack OAuth configured and slack_byo_app off — the flag default, including corveil.com — Add sensor → Slack installs the official Corveil Slack app. You do not create a Slack app or paste a bot token. A bring-your-own app (slack_byo_app on, or Slack OAuth unset) is its own section. POST /api/sensors creates the sensor in both modes.

What it does ​

Two paths on one source:

  1. Ingest — polls the channels you list via conversations.history. These are public channels by default; private channels the bot is a member of are polled too when include_private_channels is on (see Config fields). New messages become conversation events in Corveil. An empty channels list does not poll history.
  2. Chat — a separate Events API path. On the official Corveil Slack app that is POST /webhooks/slack, verified with the deployment signing secret (SLACK_SIGNING_SECRET). Slack OAuth (client id and secret) is enough to show Add to Slack; it does not verify events. Hosted corveil.com has the signing secret. A self-hosted deploy with OAuth set and SLACK_SIGNING_SECRET empty returns 401 on every event. On a bring-your-own app it is POST /webhooks/slack/{token}, verified with the vaulted signing secret. Two refusals never enqueue a run: a channel shared with another organization (Slack Connect) while Answer in Slack Connect channels is off (the default), and an organization that is out of AU. Each gets a thread notice instead — see Chat. Otherwise @corveil mentions enqueue a chat-reply worker run; Corveil posts a threaded reply. A later reply in that channel thread without @ is ignored — @ again to continue. Members can also DM the bot directly: a first DM starts a session the same way an @ does in a channel, and further DM messages stay follow-ups without another @. DMs do not use the channels allowlist. The poller does not scrape @corveil out of channel history.

Credentials ​

CredentialOfficial Corveil Slack appBring-your-own app
slack_bot_tokenyes — Add to Slack stores it. You do not paste an xoxb- token.yes — Bot User OAuth Token (xoxb-…)
slack_signing_secretnot used. The form shows Events verification is handled by the Corveil Slack app. Events are verified with the deployment secret.yes for chat — Signing Secret from the Slack app Basic Information page — not the bot token

The bot token needs these scopes. The official app requests them when you Add to Slack. A bring-your-own app must add them, and must reinstall after adding files:read, files:write or groups:read so the existing token picks them up. A workspace that installed the official app before groups:read was added keeps working; reinstall it to send to a private channel by name.

  • channels:history, channels:read, users:read, users:read.email (ingest)
  • app_mentions:read, chat:write, reactions:write (@corveil chat)
  • im:history, im:write (DMs)
  • groups:history (private-channel Events API / ingest; chat still requires @). Polling a private channel also needs include_private_channels and groups:read.
  • groups:read (find a private channel by name for Slack Bot delivery; without it, use the channel ID), and list private channels for include_private_channels ingest. Without it, that poll fails with a missing_scope error naming the scope. It doesn't fall back to public channels only.
  • files:read (download hosted images/files so chat-reply can see them)
  • files:write (attach generated images to thread replies)

Config fields ​

KeyOfficial Corveil Slack appBring-your-own app
channelsno — label Channels (optional). Comma-separated names without #, e.g. general, engineering. Used for ingesting channel messages, not for installing the bot. Invite @Corveil in Slack first; list a channel here only if you want its history ingested. Leave empty to use @corveil only (no conversations.history until names are added).yes — label Channels. Comma-separated names without the leading #. Invite the bot to each channel first. Applies to ingest polling only — DMs bypass this allowlist.

Advanced (API / CLI only) ​

These three keys are optional and off by default. They are not on the form in either mode; set them through the API or the corveil CLI. PUT /api/sensors/{id} replaces the whole config, so send channels with them. The Edit form keeps keys it doesn't show.

KeyDefaultEffect
include_private_channelsfalseAlso list private channels, so a private channel the bot is a member of resolves by name. Needs groups:read and groups:history. Without the flag, a private channel in channels reports "not found" and the message names this key.
member_channel_prefix""Also ingest every channel the bot is a member of whose name starts with this prefix (lowercase, no #). The next poll picks up new matching channels. channels may then be empty. If nothing matches and channels is empty, the poll fails with an error naming the prefix.
ingest_own_postsfalseKeep this installation's own bot posts (top-level posts and thread replies) instead of dropping them, and mark them metadata.own_post = true. Leave it off on the official app, whose own posts are @corveil answers.

Official Corveil Slack app ​

Use this when Slack OAuth is configured and slack_byo_app is off.

  1. Corvus → Sensors → Add sensor → Slack → Add to Slack (GET /api/integrations/slack/install). The install stores the slack_bot_token. You do not paste an xoxb- token.
  2. The form shows Events verification is handled by the Corveil Slack app. It does not ask for a signing secret or a per-sensor webhook URL. Channels (optional) is an ingest allowlist. Empty means @corveil chat only — no conversations.history until names are added.
  3. After the redirect (?slack=connected), the Slack is connected modal opens: "The Corveil Slack app is installed. Two different steps come next — inviting the bot is not the same as listing channels here." In each Slack channel where you want @corveil, run /invite @Corveil. Slack only delivers events for channels the bot has joined.
  4. Finish Add sensor: choose Slack, select the credential named Slack — {team} (or Slack (official app) when the workspace name is missing), and set Channels (optional) to names without # (for example general, engineering) only if you want that history ingested. Save (POST /api/sensors), then Confirm bindings. Corveil does not ingest every channel the bot has joined.
  5. In an invited channel, send @corveil hello.
json
{
  "sensor_type": "slack",
  "name": "Acme Slack",
  "config": { "channels": "general, engineering" },
  "credentials": {
    "token": "<slack_bot_token credential id created by Add to Slack>"
  }
}

Omit channel names, or leave channels empty, for chat only. The create response may still mint a per-sensor webhook token; the form does not show it. Do not paste that URL into Slack Event Subscriptions — the official app already has one Request URL.

Bring-your-own Slack app ​

Use this when slack_byo_app is on, or when the deployment has Slack OAuth unset. The form asks for a signing secret, a required channel list, and (after create) the per-sensor webhook URL.

Provider-side setup ​

  1. Create a Slack app at api.slack.com/apps → Create New App → From scratch for your workspace. Add the bot scopes listed above, and the bot events listed under Wire-up.
  2. Under OAuth & Permissions, confirm the bot scopes listed above are present.
  3. Install the app to the workspace and copy the Bot User OAuth Token (xoxb-…) and the Signing Secret from Basic Information.
  4. Invite the bot to each channel you listed (/invite @yourbot) — the bot can only read history for channels it's a member of.
  5. If you later add chat scopes (app_mentions:read, chat:write, reactions:write, im:history, im:write, groups:history, groups:read, files:read, files:write), reinstall the app so Slack issues a token with the new scopes. Reinstall is only for scope changes — rotating the Request URL does not require it.

Store both secrets in the vault before creating the sensor:

bash
curl -sS -X POST https://your-corveil-host/api/credentials \
  -H "Authorization: Bearer <admin>" -H "Content-Type: application/json" \
  -d '{"type":"slack_bot_token","name":"acme-slack-bot","secret":"xoxb-..."}'

curl -sS -X POST https://your-corveil-host/api/credentials \
  -H "Authorization: Bearer <admin>" -H "Content-Type: application/json" \
  -d '{"type":"slack_signing_secret","name":"acme-slack-signing","secret":"..."}'

Wire-up ​

POST /api/sensors

json
{
  "sensor_type": "slack",
  "name": "Acme Slack",
  "config": { "channels": "general, engineering" },
  "credentials": {
    "token": "<slack_bot_token credential id>",
    "signing_secret": "<slack_signing_secret credential id>"
  }
}

The create response includes webhook_url once. Finish chat setup in the Slack app:

  1. Event Subscriptions → enable → Request URL = that webhook_url.
  2. Under Subscribe to bot events, add:
    • app_mention
    • message.channels
    • message.groups
    • message.im
  3. Save. Slack sends a url_verification challenge; Corveil echoes the challenge only when the source has a valid slack_signing_secret wired in — without it the handler returns 401 and Slack will not accept the URL.
  4. App Home → Messages tab → enable Allow users to send Slash commands and messages from the messages tab. Without this, Slack never delivers message.im and DMs are inert.

HTTPS required

Slack Event Subscriptions reject http:// Request URLs. Behind a TLS-terminating ALB, Corveil may mint an http:// URL from the inbound request unless UI_BASE_URL is set to your public https:// origin. Pin UI_BASE_URL on the Corveil deployment before copying the webhook URL into Slack.

If you lose the URL, do not recreate the source or the Slack app: Edit sensor → Get webhook URL (or POST /api/sensors/{id}/rotate-webhook) issues a new URL and immediately invalidates the previous one. Paste only the new Request URL — do not reinstall the Slack app.

Chat (@corveil and DMs) ​

When someone @corveils in a channel the bot is in, or DMs the bot (including further messages in that DM thread), and the message is allowed to run:

  1. Corveil verifies the Slack request signature — the deployment secret on the official app, or the vaulted signing secret on a bring-your-own app.
  2. Corveil ACKs the mention with an 👀 reaction on the triggering message.
  3. Corveil enqueues a Crow worker run of kind chat-reply.
  4. When the run completes, Corveil posts a short summary in that thread.

The eyes reaction means the event was accepted — not that a reply was posted. The thread stays silent after the eyes until a worker finishes the chat-reply run. Check Workforce → Runs for that run when a mention was accepted but never replied (still queued, failed, or no worker online). The worker sees the Slack thread, including hosted image and file attachments (downloaded after the ACK). Limits: 10 files per thread, images 5 MB (png/jpeg/gif/webp), documents 10 MB (text, JSON, PDF, DOCX). Secret-looking filenames (.env, .pem, id_rsa, …) are skipped. When the worker generates an image, Corveil attaches it to the thread reply (5 files/run, 5 MB, png/jpeg/gif/webp). A bring-your-own Slack app must reinstall so the bot token includes files:read and files:write.

When Corveil declines ​

Two cases get no 👀 reaction and no chat-reply run. Corveil posts a bot reply in the thread instead:

  • Slack Connect channel, switch off. In a channel Slack marks as shared with another organization, while Answer in Slack Connect channels is off (the default), the reply is: "This channel is shared with another organization, so I don't answer here: people outside yours could read the answer. An org admin can let me give limited answers here, without your organization's knowledge graph." An org admin turns this on at People & Access → Organization, card Slack Connect channels, switch Answer in Slack Connect channels. With the switch on, @corveil gets the eyes and a chat-reply run, but that run answers from the thread alone: it has no tools and no knowledge-graph access, and it treats messages from the other organization as untrusted.
  • Out of AU. When the organization is out of AU, the reply is: "This organization is out of AU, so I can't answer right now. Ask an org admin to buy an AU pack, upgrade the plan, or turn on overage." It ends with a link to the organization's billing page when the deployment knows its UI URL.

Verify ​

  • Run Test connection to confirm the bot token is valid and the scopes are present.
  • Once polling, new messages in the listed channels appear as conversation events. An empty Channels (optional) list on the official app stays chat-only and does not ingest history. If the sensor's last error says bot is not a member, invite the bot (/invite @Corveil on the official app). Those channels resolve on the next poll.
  • For chat: @corveil hello in an invited channel. You should see the eyes reaction, then a threaded reply once a Crow worker finishes the chat-reply run. A later reply in that thread without @ stays silent; @corveil again starts a new run in the same thread. In a DM, further messages without @ keep going. Channel stop is @corveil stop; in a DM, a bare stop also cancels.
  • In a Slack Connect channel with Answer in Slack Connect channels off, expect the shared-channel notice and no eyes. With it on, expect the eyes and a reply that does not use the knowledge graph.
  • When the organization is out of AU, expect the out-of-AU notice and no eyes.