Slack - Serval Documentation

About Slack

The Slack integration connects a single Slack workspace to a Serval workspace. It powers Slack help desk surfaces—including channel tickets, DMs, @mentions, App Home, the AI assistant, the Create a Ticket shortcut, and slash commands—delivers approval requests by DM, and syncs the Slack workspace’s users and user groups 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 - once resource sync is on - user groups and their membership, 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

Capability	Description
Help desk in Slack	Create tickets from channel messages and DMs, respond via an @mention bot, browse the App Home tab, use Slack’s AI assistant thread surface, run the “Create a Ticket” message shortcut, or use a slash command named after your app.
Approval requests via DM	Serval opens a direct message with each approver to deliver approval requests (requires the `im:write` bot scope).
Channel management workflows	Create, rename, list, and search Slack channels - including public, private, private-plus-invite, and interest-group channel creation.
User management workflows	Manage Slack user access and workspace membership: add or remove users from channels, invite, deactivate, or remove users (the invite, deactivate, and remove workflows run against the separate Slack Admin integration), and look up users and user groups. Workflows that change membership default to requiring the workflow installer’s approval; read-only lookups run without approval.
Enterprise Grid admin workflows	Manage Slack using the Admin API for Enterprise Grid organizations - these run against the separate Slack Admin integration, documented on its own page.
User and user-group sync	Scheduled ingestion of workspace users, and of user groups with their membership. Turn on resource sync for the connection and Serval keeps each Slack user group current as a Serval group, so it can be selected in access policies and access-profile conditions; mentioning a synced group from Serval also renders as a proper group mention in Slack. Membership is managed in Slack - Serval reads it and never writes it back.
Full Slack Web API in workflows	A typed API request action covers the Slack Web API. Slack is method-based rather than REST - you supply the method name (for example `chat.postMessage` or `users.lookupByEmail`) - with cursor-based pagination supported. Organization-admin methods are the one exception: they go through the separate Slack Admin integration.
Incident broadcasts	During major incidents, a workspace member posts status updates from Serval. Requesters on linked tickets see them in Slack channels and threads.

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.

GovSlack is available only on fully self-hosted deployments, using your own GovSlack app. It supports messaging, ticketing, and workflow actions; Slack Admin/SCIM and knowledge ingestion are unavailable. Follow the GovSlack setup guide before connecting.

Get your credentials

There are two ways to connect, and only one of them needs any setup on Slack’s side.

Serval's Slack app (recommended)
Your own Slack app (white-label)

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.

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

Serval's Slack app (recommended)
Your own Slack app (white-label)

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.”).

Authorize in Slack

You’re redirected to Slack’s authorization screen. Make sure the correct workspace is selected (top-right) and click Allow. Configure channels in Serval after connecting.

Name your app

App Name - pre-filled with “Serval”. Placeholder: “My Company IT”. Helper text: “This appears in Slack when your app sends messages.” If you clear the field, the connected integration is labeled “Custom App”. The name is also slugified into your slash command (lowercase letters, numbers, underscores, and hyphens; up to 32 characters; falls back to “serval”).

Review Bot Scopes (optional)

The Bot Scopes picker is pre-seeded with the canonical defaults and has a Reset to defaults link. The field’s own advice: “Deselect any scope your Slack app isn’t configured with (e.g., Slack Connect scopes if your workspace restricts shared-channel invitations) to avoid being blocked during install.” You can also add custom scopes that aren’t in the suggestion list. An entry containing characters Slack scope names don’t use is rejected with: Invalid Slack bot scope “<scope>”. Use Slack scope names like channels:read or files:write.

Create the app in Slack

Use Copy & Go to Slack and follow the provider-side steps above, then return and click I have my credentials.

Enter your credentials

Client ID (required) - placeholder “1234567890.1234567890”.
Client Secret (required, masked) - placeholder “Enter your client secret”. Used only during the OAuth exchange and never stored.
Signing Secret (required, masked) - placeholder “Enter your signing secret”. Stored encrypted for webhook signature verification.

The Connect button stays disabled until all three fields are filled in.

Authorize in Slack

Click Connect. You’re redirected to Slack - make sure the correct workspace is selected (top-right), then click Allow. Complete this within 10 minutes of submitting the form. The connected integration is displayed as <Workspace Name> (<App Name>).

When reconnecting later, any extra scopes you previously added are pre-merged back into the Bot Scopes picker - but scopes you previously deselected are not remembered, so deselect them again before reconnecting. Because the Client Secret is never stored, you’ll enter your credentials again on reconnect.

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.

Messages from bots, including messages sent by Slack workflows, don’t automatically create tickets or trigger the Help Desk Agent. No channel mode or setting enables this. See Messages from bots for alternatives.

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.

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 Types for what each mode does.

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.

Live agent chat in Portuguese

For tickets with live agent chat enabled and the start button shown, the Portuguese button reads 🎧 Abrir um chat when an agent is available. Active chats show 🎧 Encerrar chat, even when the start button is hidden in the ServiceNow connection settings.

Control tickets in Slack Home

Go to Settings > Notifications > Slack and use Show tickets in Slack Home to control whether open tickets in this Serval workspace appear in people’s Assigned to you and Requests you filed sections. Turning it off does not affect tickets in other Serval workspaces, approvals, quick actions, or Slack notification delivery. This setting also applies when another Serval workspace owns the Slack connection. If Slack Home is already open, revisit it to refresh the view.

Channel configuration modes

See Channel Types for the shared reference covering ticket creation, agent responses, triage modes, and Slack/Teams availability. Set the mode for each connected channel on this integration’s Help Desk page.

Hide workflow details from requesters

In Settings → Channels → Slack, turn on Hide workflow details to hide workflow names, workflow steps, and the View Workflow Run Request button in your workspace’s Slack ticket threads. Workflow progress uses a generic status instead. Approval waits still show a generic waiting status, and completed workflows use generic names in the ticket summary. Required forms remain available, including forms opened in a modal. The setting is off by default. It applies to new progress streams and subsequent workflow card updates. It does not erase historical messages or rewrite progress streams that were already running when you changed it. Approver notifications, access request cards, and workflow details in the Serval web app are unchanged. This setting applies to Slack; it does not change Microsoft Teams messages, or text explicitly sent by a workflow.

Configure Workspace Inbox channels

A Workspace Inbox is a private channel where support agents triage tickets for your workspace within Slack. See Workspace inbox modes to choose which tickets appear. 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.

Workspace Inbox is especially valuable when tickets come from DMs or other sources that individual support agents can’t otherwise see.

Create a private Slack channel

Create a private channel for the workspace’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.

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.

Set the mode to Workspace Inbox

In Integrations > Slack, find the channel and choose Workspace inbox for all workspace tickets or Workspace inbox on Escalation for only escalated tickets. Matching tickets 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.

Workspace 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) and their membership. This is a separate capability from the help desk and from workflows: it does not sync channels or DMs, only user groups.

Open the Slack app settings

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

Enable resource sync

Turn on Resource sync. Serval then ingests the workspace’s active user groups and their members on its standard sync schedule; disabled groups are skipped. A manual sync from the UI forces a full re-sync.

Each synced group becomes a Serval group whose members are the group’s full workspace members (guests, bots, and accounts without an email are skipped), so you can pick it wherever Serval accepts a group - as approvers in an access policy, or in an access-profile condition. It is also cataloged 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 read-only sync: Serval mirrors which groups exist and who is in them, 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

User sync fails with account_inactive

Slack reports account_inactive when the account or workspace associated with the connection is inactive. Serval stops the failed sync without retrying the same credentials or removing existing users. Restore a valid Slack connection, then run a manual sync or wait for the next scheduled sync.

Slack blocked the install with a scope error

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.

Install blocked in workspaces that restrict Slack Connect

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).

Slack says the app needs approval from an admin

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”.

"Invalid state" error after authorizing in Slack

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.

Slack asked me to pick a channel during authorization

Slack shows this selector when the app requests incoming-webhook. Serval’s default scopes do not include it; channel routing is configured in Serval after connecting.For a custom app created with an older manifest, first update Serval to a version with the current default scopes. Then open your Slack app’s settings, go to OAuth & Permissions > Scopes > Bot Token Scopes, and remove incoming-webhook. Also deselect it in Serval’s Bot Scopes picker if you use a custom scope list, then restart the connect flow. For Serval’s managed app, contact support if the selector still appears.Existing connections do not need to reconnect for this change. Removing the scope from the app configuration affects new grants; existing tokens retain their granted scopes.

Can't add a second Slack integration for the same workspace

A Serval workspace can have only one integration for each Slack workspace: either the managed app or a custom app. To switch approaches, disconnect the existing integration first.

Managed option missing, or "Slack OAuth is not configured in this environment"

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.

Enterprise Grid: install is workspace-scoped, and admin actions don't work

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.

A reused or hand-edited manifest produces a broken app

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.

Which bot scopes does Serval request by default?

The default bot scopes are: 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, 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.

Configure existing helpdesk channels through the API

You can activate an existing Slack channel or change its helpdesk mode from an external API client or a Serval workflow. The channel must already appear in Add another channel in your Slack integration. Inviting the bot alone does not guarantee that Serval has discovered the channel.

Call GET /v2/teams/{team_id}/connected-channels. You can filter by serviceInstanceId to select the Slack integration instance. Disabled channels are included; direct messages and deleted connections are excluded.
Find the entry whose serviceChannelId matches your Slack channel ID.
Call PUT /v2/teams/{team_id}/connected-channels/{id}/mode, using the entry’s Serval id, with this body:

{
  "mode": "CONNECTED_SERVICE_MODE_FULL_ASSIST"
}

This enables Help desk (Always respond), matching the channel picker. The response contains the resulting channel in data. Repeating the same mode succeeds without another change. Use CONNECTED_SERVICE_MODE_DISABLED to disable the channel. External clients use Serval API authentication. Scoped Serval API keys need channels:read for listing and channels:write for updates, plus access to the requested workspace. These are Serval scopes, not Slack OAuth scopes. A write-only key can update a connection whose ID you already know. Serval workflows use their existing workspace-bound credentials. With serval imported from the Serval SDK, the API calls look like this:

const channels = await serval.apiRequest({
  method: "GET",
  path: "/v2/teams/{team_id}/connected-channels",
  pathParams: { team_id: teamId },
  query: { serviceInstanceId },
}, undefined);

const channel = (channels.data ?? []).find(
  (entry) => entry.serviceChannelId === slackChannelId,
);
if (!channel?.id) {
  throw new Error("Channel is not available in this workspace's connected channels.");
}

await serval.apiRequest({
  method: "PUT",
  path: "/v2/teams/{team_id}/connected-channels/{id}/mode",
  pathParams: { team_id: teamId, id: channel.id },
  body: { mode: "CONNECTED_SERVICE_MODE_FULL_ASSIST" },
}, undefined);

The API supports these existing Slack modes:

Mode value suffix	Integration setting
`DISABLED`	Disabled
`FULL_ASSIST`	Help desk (Always respond)
`ASSISTANT`	Help desk (When relevant)
`TICKET_ONLY`	Silent
`ON_DEMAND`	On demand
`TEAM_ONLY`	Workspace only
`TEAM_INBOX_ALL`	Workspace inbox
`TEAM_INBOX`	Workspace inbox on Escalation
`REDIRECT_TO_DM`	Redirect to DM; requires direct messages enabled for the workspace

Prefix each value with CONNECTED_SERVICE_MODE_. The mode must be explicit. DM, SILENT_ASSIST, UNSPECIFIED, and unknown values cannot be set. Existing redirect messages are preserved. The API does not create connections, invite the bot, or configure direct messages, phone senders, or email intake.

​About Slack

​What the Slack integration enables

​Get your credentials

​Connect in Serval

​Configure Slack as your help desk

​Live agent chat in Portuguese

​Control tickets in Slack Home

​Channel configuration modes

​Hide workflow details from requesters

​Configure Workspace Inbox channels

​Resource sync

​Verifying the connection

​Gotchas and troubleshooting

​Configure existing helpdesk channels through the API

About Slack

What the Slack integration enables

Get your credentials

Connect in Serval

Configure Slack as your help desk

Live agent chat in Portuguese

Control tickets in Slack Home

Channel configuration modes

Hide workflow details from requesters

Configure Workspace Inbox channels

Resource sync

Verifying the connection

Gotchas and troubleshooting

Configure existing helpdesk channels through the API