Connect Slack with your own app

Ringo Work installs into Slack two ways:

• Managed (recommended) — one click in onboarding. Nothing to configure; the shared Ringo app is installed into your workspace.
• Your own app (BYOA) — bring your own Slack app so the bot uses your name, icon and branding. This guide covers that setup.

Shortcut: onboarding's Connect Slack → Your own app tab has a Create Slack app button that opens Slack with everything below already filled in (via an app manifest) — you just pick a workspace and confirm. Use this guide only if you prefer to set the app up by hand, or to see what the manifest configures.

You'll create a Slack app, point it at Ringo's URLs, add the bot scopes, then paste three credentials into onboarding: Client ID, Client Secret, and Signing Secret.

Why the Signing Secret? Slack signs every incoming event (mentions, button clicks) with your app's signing secret. Ringo verifies that signature to know the request is really from your app — without it the bot installs and learns but won't reply to mentions.

1. Create the app

1. Go to api.slack.com/apps → Create New App → From scratch.
2. Name it (this is your bot's name) and pick your workspace.
3. (Optional) Give the bot a profile picture: Basic Information → Display Information → App icon & Preview. Use your own logo, or download the Ringo icon (1200×1200 PNG). Slack requires a square image between 512px and 2000px.

2. OAuth & Permissions

Redirect URL — add exactly:

https://api-production-a0e5.up.railway.app/api/integrations/callback/slack

Bot Token Scopes — add:

app_mentions:read   channels:history   channels:read     channels:join
groups:history      groups:read        im:history        im:read
mpim:history        mpim:read          files:read        chat:write
chat:write.customize                   reactions:read    reactions:write
emoji:read          users:read         users:read.email

reactions:write lets Ringo drop a 👀 reaction on your message while it's thinking (and clear it when it replies). reactions:read and emoji:read let Ringo see emoji reactions on messages and understand your workspace's custom emoji (e.g. a custom "done" stamp) — status reactions like these are a real signal about what's finished. files:read lets Ringo read shared images, documents, and videos so it can answer questions about their contents. chat:write.customize lets each agent post under its own name and icon when your project runs more than one agent.

User Token Scopes — add:

search:read

search:read powers Ringo's workspace search (Slack's own indexed search over messages and files — full history, not just recent days). It is granted by whoever clicks Connect, but Ringo only ever surfaces results from channels the bot itself is a member of. If your app was installed before this scope existed, re-run Connect once to grant it — until then Ringo falls back to scanning recent history only.

3. Event Subscriptions

Enable events and set the Request URL:

https://api-production-a0e5.up.railway.app/api/slack/events

Slack verifies this URL instantly (Ringo echoes the challenge). Under Subscribe to bot events, add:

app_mention        message.channels       message.groups       message.im
message.mpim       reaction_added         reaction_removed
member_joined_channel                    member_left_channel
channel_created    channel_rename         channel_archive      channel_unarchive
team_join          user_change

4. Interactivity & Shortcuts

Turn on Interactivity and set the Request URL:

https://api-production-a0e5.up.railway.app/api/slack/interactions

5. Copy your credentials

From Basic Information → App Credentials, copy:

• Client ID
• Client Secret
• Signing Secret

Paste all three into onboarding's Connect Slack → Your own app tab and click Connect with your app. You'll be sent to Slack to install the app, then Ringo starts learning your workspace and boots your dedicated agent — same as the managed flow, but with your branding.

Notes

• You can connect multiple workspaces to one project — repeat the install from Integrations after onboarding.
• One Slack workspace maps to exactly one Ringo project.
• Changing scopes later requires re-installing the app to the workspace.