Slack Bolt with Nitro Template

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

Before getting started, make sure you have a development workspace where you have permissions to install apps. You can use a developer sandbox or create a workspace

Getting Started

Clone and install dependencies

git clone https://github.com/vercel-partner-solutions/slack-agent-template && cd slack-agent-template && pnpm install

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 use
3. Copy the contents of manifest.json into the text box that says "Paste your manifest code here" (JSON tab) and click Next
4. Review the configuration and click Create
5. On the Install App tab, click Install to <Workspace_Name>.
   • You will be redirected to the App Configuration dashboard
6. Copy the Bot User OAuth Token into your environment as SLACK_BOT_TOKEN
7. On the Basic Information tab, copy your Signing Secret into your environment as SLACK_SIGNING_SECRET

Environment Setup

1. Add your AI_GATEWAY_API_KEY to your .env file. You can get one here
2. Add your NGROK_AUTH_TOKEN to your .env file. You can get one here
3. In the terminal run slack app link
4. If prompted update the manifest source to remote select yes
5. Copy your App ID from the app you just created
6. Select Local when prompted
7. Open .slack/config.json and update your manifest source to local

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

8. Start your local server using slack run. If prompted, select the workspace you'd like to grant access to

• Select yes if asked "Update app settings with changes to the local manifest?"

9. 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 Slack app for production following the steps from above
2. Create a new Vercel project here and select this repo
3. Copy the Bot User OAuth Token into your Vercel environment variables as SLACK_BOT_TOKEN
4. On the Basic Information tab, copy your Signing Secret into your Vercel environment variables as SLACK_SIGNING_SECRET
5. When your deployment has finished, open your App Manifest from the Slack App Dashboard
6. Update the manifest so all the request_url and url fields use https://<your-app-domain>/api/slack/events
7. Click save and you will be prompted to verify the URL
8. 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
   • Note: Make sure you add the production app, not the local app we setup earlier
9. Your app will now automatically build and deploy whenever you commit to your repo. More information here

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.