Slack Agent Template

This is a Slack Agent template built with Bolt for JavaScript (TypeScript) and the Nitro server framework.

Prerequisites

• Node.js 22+ - Download here
• Slack workspace - You need a workspace where you have permission to install apps
  • Create a new workspace here
  • Or use a Slack developer sandbox here
• Slack CLI - Installation guide
• ngrok - Download here

Installation

Clone and initialize Slack App

slack create --template https://github.com/vercel-partner-solutions/slack-agent-template.git

Create a Slack App

1. Open https://api.slack.com/apps/new and choose "From an app manifest"
2. Choose the workspace you want to install the application to
3. Copy the contents of manifest.json into the text box that says *Paste your manifest code here* (within the JSON tab) and click Next
4. Review the configuration and click Create
5. From the Basic Information tab, copy your Slack Signing Secret into your .env file under SLACK_SIGNING_SECRET
6. Open the Install App tab on the left menu. Click Install to <Workspace_Name> and Allow on the screen that follows
7. On the following screen, copy the Bot User OAuth Token into your .env file under SLACK_BOT_TOKEN

Environment Setup

1. Add your AI_GATEWAY_API_KEY to your .env file. You can get one here
2. (Optional) You can also use your VERCEL_OIDC_TOKEN to authenticate with the Vercel AI Gateway. More info here

Prepare for Local Development

1. In the terminal run slack app link
2. Select your Slack team in the terminal
3. Copy your App ID from the app you just created 4 Select Local when prompted
4. Open your config.json file under /.slack/config.json and update your manifest source to local

{
  "manifest": {
    "source": "local"
  },
  "project_id": "<project-id-added-by-slack-cli>"
}

1. Start your local server with automatic tunneling using the pnpm dev:tunnel command. You can also use the generic slack run command if you do not want automatic tunneling and manifest updates. If prompted, select the workspace you'd like to grant access to. Select yes when asked Update app settings with changes to the local manifest?

2. Open your Slack workspace and add your new Slack Agent to a channel. Your Slack Agent should respond whenever it's tagged in a message or sent a DM

Deploy to Vercel

1. Create a new Vercel project here or select Add new... and project from the Vercel dashboard
2. On the next screen, select Import next to your app repository but do not click Deploy
3. Create a new Slack app for Production. Open https://api.slack.com/apps/new and choose "From an app manifest"
4. Copy the contents of manifest.json into the text box that says *Paste your manifest code here* (within the JSON tab) and click Next and Create
5. From the Basic Information tab, copy your Slack Signing Secret into the Environment Variables dropdown on your new Vercel project window as SLACK_SIGNING_SECRET
6. On your Slack app window, open the Install App tab on the left menu. Click Install to <Workspace_Name> and Allow on the screen that follows. Copy the Bot User OAuth Token
7. Open your new Vercel project window and paste this value as SLACK_BOT_TOKEN in the environment variables dropdown
8. Click Deploy
9. Once the deployment is complete, click Continue to Dashboard
10. Copy your production domain URL, seen under Domains on the Overview tab
11. Open your Slack app settings and click App Manifest
12. Update the url and request_url fields of your App Manifest to the production domain. Make sure the /api/events path is preserved
13. At the top of the page, you will be prompted to verify the new URL
14. Your production app is now deployed and ready

Project Structure

manifest.json

manifest.json is a configuration for Slack apps. With a manifest, you can create an app with a pre-defined configuration, or adjust the configuration of an existing app.

/server/app.ts

/app.ts is the entry point of the application. This file is kept minimal and primarily serves to route inbound requests.

/server/listeners

Every incoming request is routed to a "listener". Inside this directory, we group each listener based on the Slack Platform feature used, so /listeners/shortcuts handles incoming Shortcuts requests, /listeners/views handles View submissions and so on.

/server

This is your nitro server directory. Inside you have an api folder that contains a events.post.ts file. This matches the request URL's defined in your manifest.json file. Nitro uses file based routing for incoming requests. You can learn more about this here.