Skip to main content

​
About Slack

The Slack integration connects a single Slack workspace to your Serval team. It powers Serval’s Slack help desk surfaces (tickets from channel messages and DMs, an @mention bot, an App Home tab, an AI assistant thread surface, a “Create a Ticket” message shortcut, and a slash command), delivers approval requests by direct message, and keeps your workspace’s users and user groups synced into Serval. A separate Slack Admin integration (Enterprise Grid org-admin, user tokens) is documented on its own page and is not covered here. Authentication: Slack-app OAuth v2 install with bot scopes - either Serval’s managed Slack app (one click, recommended) or your own white-label Slack app created from a Serval-generated manifest. Data sync: Scheduled background syncs ingest workspace users and user groups on Serval’s standard sync schedule; a manual sync from the UI forces a full re-sync. Workflow calls to Slack run on demand through Serval’s proxy, and rate-limited responses are retried automatically with exponential backoff.

​
What the Slack integration enables

Anything defined in the Slack API can be accessed through Serval, with one exception: organization-admin methods require the separate Slack Admin integration. A few of the catalog workflows above - name-based channel and user lookups, and inviting, deactivating, or removing workspace members - also connect through that companion Slack Admin integration rather than this one.

​
Get your credentials

There are two ways to connect, and only one of them needs any setup on Slack’s side.
No provider-side setup and no credentials are required. Choose Use Serval’s Slack App - the option marked Recommended (“Connect instantly using Serval’s managed Slack application.”) - and Serval walks you through a standard Slack authorization screen. Skip ahead to Connect in Serval.
Because the app requests the incoming-webhook scope, Slack will ask you to pick a channel during authorization. This is expected - the chosen channel is saved with the integration, and channel behavior is configured in Serval after connecting.
On some self-hosted deployments this option is hidden (or returns the error “Slack OAuth is not configured in this environment”). In that case, use the Your own Slack app path instead.

​
Connect in Serval

1

Choose the recommended option

In the Slack connect dialog, select Use Serval’s Slack App - the option marked Recommended (“Connect instantly using Serval’s managed Slack application.”).
2

Authorize in Slack

You’re redirected to Slack’s authorization screen. Make sure the correct workspace is selected (top-right), choose a channel when prompted, and click Allow.

​
Configure Slack as your help desk

After connecting, you land on the Slack app configuration page in Serval. To use Serval in a channel, first add it to the channel in Slack, then set that channel’s mode in Serval.
1

Add Serval to a Slack channel

In the channel you want to use, type @Serval to mention the app and click Add them when prompted. The channel then appears on the Slack app configuration page in Serval.
2

Set the channel mode in Serval

Go to Integrations > Slack, find the channel you just added Serval to, and choose how Serval should operate in it. See Channel configuration modes for what each mode does.
3

Connect additional channels

Repeat for any other channels: add Serval with @Serval then Add them in Slack, then set that channel’s mode in Serval.
You can also enable Direct Messaging from the Slack app’s help desk settings for private support interactions. Channel-based support and DMs can run at the same time - channels give the team visibility, while DMs give users a private option for sensitive requests.
On Slack Enterprise Grid, Serval supports org-wide (enterprise-level) channels shared across the workspaces in your Grid organization. Add Serval to an org-wide channel the same way (@Serval, then Add them), and it appears on the Slack app configuration page to set a mode. Messages posted from any workspace in the org, not only the one Serval was installed in, are handled.
When first setting up, start a channel in Silent mode: Serval creates tickets without posting in the channel, so you can watch how tickets are created and routed before switching it to Help Desk mode to fully activate responses.

​
Channel configuration modes

Each Slack channel connected to Serval operates in one of these modes:

​
Configure Team Inbox channels

A Team Inbox is a private channel where support agents triage every escalated ticket for your team within Slack. Tickets from DMs, help desk channels, and the web all appear as threads in one place, so agents can respond and collaborate without switching to the Serval web interface.
Team Inbox is especially valuable when tickets come from DMs or other sources that individual support agents can’t otherwise see.
1

Create a private Slack channel

Create a private channel for the team’s inbox (for example it-inbox or finance-support-inbox) and invite only the support agents and managers who will handle tickets - not end users.
2

Add Serval to the channel

In the channel, type @Serval and click Add them, or connect the channel from the Slack app configuration page in Serval.
3

Set the mode to Team Inbox

In Integrations > Slack, find the channel and set its mode to Team Inbox. All escalated tickets for the team now sync into the channel automatically as threads.
Once configured, each ticket appears as a thread with its details and history. Reply in a thread to send your message to the end user, and use commands like @Serval assign to me to triage.
Team Inbox mode is egress-only. Messages posted directly to the channel (outside a ticket thread) do not create new tickets.

​
Resource sync

Serval supports resource sync for Slack user groups (Slack subteams - the @-mentionable groups in your workspace). This is a separate capability from the help desk and from workflows: it does not sync channels or DMs, only user groups.
1

Open the Slack app settings

In Serval, go to Integrations > Slack and open the app’s settings page.
2

Enable resource sync

Turn on Resource sync. Serval then ingests the workspace’s active user groups on its standard sync schedule; disabled groups are skipped. A manual sync from the UI forces a full re-sync.
Each synced group is cataloged in Serval with its name and @handle so the help desk agent and workflows can reference it - for example, when a reply needs to mention a Slack user group, Serval renders it as a proper group mention in Slack.
This is a catalog-only sync: Serval learns which groups exist and their handles, but it does not add or remove users from Slack groups through access requests (unlike Buildkite or OneLogin). Group membership stays managed in Slack.

​
Verifying the connection

After connecting, Serval runs five health checks:
  • Test Slack Connection - verifies the integration is connected and the OAuth token is valid. Success: “Successfully authenticated with Slack workspace [workspace name]”. Failure: “Unable to authenticate with Slack. Please verify the app is still installed and its OAuth token has not been revoked.”
  • List Slack Users - checks Serval can read users from the workspace. Success: “Successfully listed Slack users (sample size: [number])”. Failure: “Unable to list Slack users. Please verify the app has the users:read scope and has not been removed from the workspace.”
  • List Slack Channels - checks Serval can read public and private channels. Success: “Successfully listed Slack channels (sample size: [number])”. Failure: “Unable to list Slack channels. Please verify the app has the channels:read and groups:read scopes and has not been removed from the workspace.”
  • List Slack Scopes - reports the OAuth scopes actually granted to the token. Success: “Successfully read Slack token scopes ([number] granted)”. Failure: “Unable to read Slack token scopes. Please verify the app is still installed and its OAuth token has not been revoked.”
  • Send Approval Requests via Slack - checks the token has the im:write scope needed to open DMs for approval requests. Success: “Slack app has the im:write scope required to send approval requests.” Failure: “Slack approval requests cannot be sent because the app is missing the im:write scope.” If the check itself can’t reach Slack, you’ll instead see: “Unable to verify Slack approval request permissions. Please verify the app is still installed and its OAuth token has not been revoked.”
If the connection test is green but approval requests never arrive, run List Slack Scopes to see what the token was actually granted - the most common cause is a custom app installed without im:write. Fix the scopes in your Slack app and reconnect so a new token is issued.

​
Gotchas and troubleshooting

Slack blocks the install if Serval requests scopes your Slack app isn’t actually configured with - the scopes requested at install time must all be present on your app. To change scopes on a custom app: adjust the Bot Scopes picker in Serval (which regenerates the manifest), update the app at api.slack.com with the new manifest (or matching scope edits), then reconnect so a token with the new grants is issued. Use the List Slack Scopes health check to see what the current token actually has.
The default scope set includes the conversations.connect scopes for shared channels. If your workspace restricts shared-channel invitations, deselect those scopes in the Bot Scopes picker before installing. Note that a non-default selection replaces the canonical scope list wholesale (extra scopes you add are layered on top).
Your Slack workspace has app approval turned on, so installing any new app - Serval’s managed app or a custom app created from the manifest - requires a one-time approval by a Slack Workspace Owner, Workspace Admin, or App Manager. On Enterprise Grid, app management may instead be controlled at the organization level by org admins. This gate is entirely on Slack’s side; your Serval permissions have no bearing on it. Approvals are also per-workspace: approval in a sandbox workspace does not carry over to production.To resolve it, submit the approval request on Slack’s screen - the admin is notified via Slackbot and can approve under Settings & administration > Manage apps > Requested apps (Enterprise Grid: admin.slack.com > Apps > Requests) - or have the approving admin run the connect flow themselves. After approval, restart the connect flow from Serval; the earlier attempt does not resume. On the custom-app path that means re-entering your Client ID, Client Secret, and Signing Secret (the Client Secret is never stored) and completing the authorization within the 10-minute window, or the callback rejects with “Invalid state”.
Custom-app credentials travel in a signed token that expires 10 minutes after you submit the form. If you take longer than that to finish the Slack authorization, the callback rejects with “Invalid state”. Re-open the connect dialog, resubmit your credentials, and complete the authorization promptly. For security, the Client Secret is used only during the exchange and is never stored; only the access token and Signing Secret are stored, encrypted.
Expected. Because the app requests the incoming-webhook scope, Slack shows a channel selector on the authorization screen. The selected channel’s id and name are saved with the integration, and channel behavior is configured in Serval after connecting.
A Serval team can only have one Slack integration per workspace - either the managed app or a custom app, not both. To switch approaches, disconnect the existing integration first.
Deployments without Serval-operated Slack credentials (for example, some self-hosted environments) can’t use the managed one-click install - the connect dialog hides that option, or the attempt fails with “Slack OAuth is not configured in this environment”. Use the Use Your Own Slack App flow instead.
Even on Enterprise Grid, the integration connects a single workspace, not the whole organization - workspace-scoped actions like sending messages require a workspace connection, and the app is not org-deployed. Organization-level admin workflows require the separate Slack Admin integration, which uses different scopes and user tokens instead of bot tokens - see the Slack Admin docs page.
The manifest is generated server-side so the webhook, interactivity, slash-command, and OAuth redirect URLs always match your exact Serval deployment. Copy it fresh from the connect dialog every time - never from documentation, a teammate, or another environment. Serval refuses to generate a manifest with an unreachable webhook address rather than emit a broken one.
The default set is exactly 33 bot scopes: app_mentions:read, channels:history, channels:join, channels:manage, channels:read, channels:write.invites, chat:write, chat:write.customize, commands, conversations.connect:manage, conversations.connect:read, conversations.connect:write, files:read, files:write, groups:history, groups:read, groups:write, im:history, im:read, im:write, incoming-webhook, metadata.message:read, mpim:history, mpim:read, reactions:read, reactions:write, team:read, usergroups:read, usergroups:write, users:read, users:read.email, users.profile:read, and assistant:write. No user-level scopes are requested for regular Slack installs. See Slack’s permission scopes reference for what each scope grants.
Need help? Contact support@serval.com for assistance with your Slack integration.