Slack
Connect a Slack app to a project and your assistant answers questions in Slack. People mention the app in a channel, or send it a direct message, and the answer arrives in a thread under the question, followed by the sources it came from. Follow-up messages in the same thread continue the same conversation.
Slack answers questions only. If the assistant proposes an action, such as sending an email or updating a record, the action is refused in Slack. Use a channel with an approval flow for actions.
Before you start
- An administrator must turn on the Slack channel for the deployment with
ENABLE_SLACK=true. The API process then starts the Slack workers. Slack events are queued in Redis, so Redis must be available. - You need permission to create apps in the Slack workspace.
1. Create the Slack channel in Pragence
In the console, open the project's Playground & channels, go to
Channels, select Slack and choose Create Slack channel. The panel
shows the request URL to give Slack and the fields for the app's credentials.
You can also create a channel of type slack through the channels API. Its
config holds the app's credentials:
| Key | Required | Value |
|---|---|---|
bot_token | Yes | The app's Bot User OAuth Token (xoxb-…). |
signing_secret | Yes | The app's Signing Secret, from Basic Information. |
app_id | No | Accept events only from this app (A…). |
team_id | No | Accept events only from this workspace (T…). |
Credentials are write-only. The console and the API never return a stored token or secret; they only report which ones are set. Leave a field blank to keep the saved value.
On a self-hosted deployment you can store ${ENV_VAR} placeholders instead of
the raw values, for example "bot_token": "${ACME_SLACK_BOT_TOKEN}".
Placeholders are references, not secrets, so they stay visible.
The console shows the request URL with a copy button. If you use the API, note the organization ID and the new channel's ID. The URL is:
https://<your-api-host>/webhooks/slack/<org_id>/<channel_id>2. Create the Slack app
Create an app at api.slack.com/apps and add these Bot Token Scopes under OAuth & Permissions:
app_mentions:read, to receive mentions in channelschat:write, to post answersim:history, to receive direct messages
Under App Home, allow users to send messages from the Messages tab if you want direct messages to work.
Install the app to the workspace and copy the Bot User OAuth Token and Signing Secret into the channel config from step 1.
3. Subscribe to events
Under Event Subscriptions, turn events on and paste the request URL. Slack sends a verification request; Pragence answers it only when the request is signed with this channel's signing secret, so save the channel config first.
Subscribe to these bot events:
app_mentionmessage.im
Invite the app to the channels where people should be able to mention it.
How requests are checked
- Every request must carry a valid
X-Slack-Signaturemade with the channel's signing secret and a timestamp from the last five minutes. Anything else is rejected with403, the same response as an unknown channel. - Messages from bots, including the app's own replies, and edits or deletions are ignored.
- Slack retries events it doesn't see acknowledged within three seconds.
Pragence de-duplicates events by
event_id, and records each reply, so a retried event is never answered twice. - If a reply times out after it was sent, Pragence doesn't resend it, because Slack offers no way to post a message exactly once. The event is logged as uncertain for review.
Answers and sources
Answers use the project's entry agent, or the agent pinned with
target_agent_key, and the same sources and permissions as other channels.
Sources are listed under the answer, linked when the source has a URL. If
nothing in the knowledge base supports an answer, the assistant says it can't
answer reliably. A deployment can set ALLOW_GENERAL_KNOWLEDGE_FALLBACK=true
to answer from general knowledge instead, labelled and without sources.