Appearance
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:
- 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 wheninclude_private_channelsis on (see Config fields). New messages become conversation events in Corveil. An emptychannelslist does not poll history. - 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 andSLACK_SIGNING_SECRETempty returns 401 on every event. On a bring-your-own app it isPOST /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@corveilmentions enqueue achat-replyworker 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 thechannelsallowlist. The poller does not scrape@corveilout of channel history.
Credentials
| Credential | Official Corveil Slack app | Bring-your-own app |
|---|---|---|
slack_bot_token | yes — Add to Slack stores it. You do not paste an xoxb- token. | yes — Bot User OAuth Token (xoxb-…) |
slack_signing_secret | not 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(@corveilchat)im:history,im:write(DMs)groups:history(private-channel Events API / ingest; chat still requires@). Polling a private channel also needsinclude_private_channelsandgroups:read.groups:read(find a private channel by name for Slack Bot delivery; without it, use the channel ID), and list private channels forinclude_private_channelsingest. Without it, that poll fails with amissing_scopeerror 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
| Key | Official Corveil Slack app | Bring-your-own app |
|---|---|---|
channels | no — 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.
| Key | Default | Effect |
|---|---|---|
include_private_channels | false | Also 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_posts | false | Keep 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.
- Corvus → Sensors → Add sensor → Slack → Add to Slack (
GET /api/integrations/slack/install). The install stores theslack_bot_token. You do not paste anxoxb-token. - 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
@corveilchat only — noconversations.historyuntil names are added. - 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. - Finish Add sensor: choose Slack, select the credential named
Slack — {team}(orSlack (official app)when the workspace name is missing), and set Channels (optional) to names without#(for examplegeneral, 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. - 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
- 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.
- Under OAuth & Permissions, confirm the bot scopes listed above are present.
- Install the app to the workspace and copy the Bot User OAuth Token (
xoxb-…) and the Signing Secret from Basic Information. - Invite the bot to each channel you listed (
/invite @yourbot) — the bot can only read history for channels it's a member of. - 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:
- Event Subscriptions → enable → Request URL = that
webhook_url. - Under Subscribe to bot events, add:
app_mentionmessage.channelsmessage.groupsmessage.im
- Save. Slack sends a
url_verificationchallenge; Corveil echoes the challenge only when the source has a validslack_signing_secretwired in — without it the handler returns 401 and Slack will not accept the URL. - App Home → Messages tab → enable Allow users to send Slash commands and messages from the messages tab. Without this, Slack never delivers
message.imand 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:
- Corveil verifies the Slack request signature — the deployment secret on the official app, or the vaulted signing secret on a bring-your-own app.
- Corveil ACKs the mention with an 👀 reaction on the triggering message.
- Corveil enqueues a Crow worker run of kind
chat-reply. - 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,
@corveilgets the eyes and achat-replyrun, 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 @Corveilon the official app). Those channels resolve on the next poll. - For chat:
@corveil helloin an invited channel. You should see the eyes reaction, then a threaded reply once a Crow worker finishes thechat-replyrun. A later reply in that thread without@stays silent;@corveilagain 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 barestopalso 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.