Pragence

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:

KeyRequiredValue
bot_tokenYesThe app's Bot User OAuth Token (xoxb-…).
signing_secretYesThe app's Signing Secret, from Basic Information.
app_idNoAccept events only from this app (A…).
team_idNoAccept 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 channels
  • chat:write, to post answers
  • im: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_mention
  • message.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-Signature made with the channel's signing secret and a timestamp from the last five minutes. Anything else is rejected with 403, 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.

On this page