Quickstart guide for the beta Slack platform

You can get started with our next-generation platform right now by following the steps below. This will allow you to spin up a local development server and link it to a development app in your workspace. When you're ready to deploy your production code to Slack, an admin or owner on your workspace needs to accept the Slack Platform and Beta Service Terms here.

Step 1: Install the Slack CLI

$ deno --version
deno 1.24.* (release, x86_64-apple-darwin)
v8 10.*
typescript 4.*

$ slack version
Using slack v1.18.0

$ slack doctor

Step 2: Authorize the CLI

Run the following command to authorize your CLI to your workspace:

slack login

Your terminal window will output a string that looks like this:

  /slackauthticket ABC123defABC123defABC123defABC123defXYZ

Copy that whole string and paste it into any Slack channel or DM in the workspace you will be developing in. This activates a shortcut that will prompt you to approve access to the CLI.

After you approve access, you can verify that your CLI is setup and ready to go by running slack auth list in your terminal window:

$ slack auth list

[ACTIVE] myworkspace (Team ID: T1TK12345)
User ID: U1234567
Last update: 2022-05-24 12:00:00 Z

To change your active workspace authorization run slack login
$

You should see an entry for the workspace you just authorized with an ACTIVE label. If you don't, get a new authorization ticket with slack login and try again.

You are ready to create your first Slack app on our next generation platform when you see your workspace in the output of slack auth list with an ACTIVE label.

Step 3: Create a Slack app

Create a new Slack app with the command slack create <your-app-name>, which will give you a list of project templates to choose from:

$ slack create my-app

? Select a template to build from:

> Hello World
  A simple workflow that sends a greeting

  Scaffolded project
  A solid foundation to start building upon

  Blank starter project
  A, well.. blank project

Since this is all about getting started quickly, let's choose the "Hello World" template for an example of how we can use a Link trigger to send a greeting to a channel. (The rest of this quickstart guide will assume you are using this template.)

When you select the "Hello World" template, the CLI will scaffold an app project for you. Once it has finished, cd into your new project directory, and continue to the next step.

Step 4: Create a trigger for your app

Apps are comprised of three main components:

• Functions, where all your business logic lives
• Workflows, which wire up functions to fire off sequentially
• Triggers, which invoke a workflow

Before you can interact with your app, you need to create a trigger.

The "Hello World" template we used in the previous step contains a function, a workflow, and a "trigger file" that contains configuration for creating a specific trigger.

Create the trigger by running the following command in your terminal:

$ slack trigger create --trigger-def "triggers/greeting_trigger.ts"

Running this command will bring up the app selector prompt. Since this is your first time deploying this app, you'll be prompted to create a new app:

? Choose an app  [Use arrows to move, type to filter]
>  Create a new app

Select the option to create a new app (Enter), which will present an opportunity to install either a production or development version of your app:

? Choose a workspace for the app  [Use arrows to move, type to filter]
>  myworkspace  T012ABC1234
   App is not installed to this workspace

   myworkspace (dev)  T012ABC1234
   App is not installed to this workspace

Select the option that has (dev) appended to your workspace name. This will install a development version of your app to your workspace.

Once the above command runs successfully, you will see the following output:

📚 App Manifest
   Created app manifest for "my-app (dev)" in "myworkspace" workspace

⚠️  Outgoing domains
   No allowed outgoing domains are configured
   If your function makes network requests, you will need to allow the outgoing domains
   Learn more about upcoming changes to outgoing domains: https://api.slack.com/future/changelog

🏠 Workspace Install
   Installed "my-app (dev)" app to "myworkspace" workspace
   Finished in 1.5s

⚡ Trigger created
   Trigger ID:   Ft0123ABC456
   Trigger Type: shortcut
   Trigger Name: Send a greeting
   Shortcut URL: https://slack.com/shortcuts/Ft0123ABC456/XYZ123...

Everything is looking good! Don't worry about the outgoing domains message — the hello world app doesn't interact with any external domains.

Looking at the last section of output, take note of the Shortcut URL for our newly created trigger. We will need it for the next step!

Step 5: Run the app in local development mode

While building your app, you can see your changes propagated to your workspace in real-time by running slack run within your app's directory.

Executing slack run starts a local development server, syncing changes to your workspace's development version of your app. Be sure to select the workspace that the app is installed in.

Now grab the Shortcut URL you generated in the previous step and post it in a public channel in your Slack workspace. You will see the shortcut unfurl with a "run" button in the channel you posted it.

Execute the Send a greeting shortcut by clicking on the run button.

In the modal that appears, select a user, channel, and enter a greeting. When you click the "Send greeting" button, you should see your greeting appear in the channel you specified.

When you want to turn off the local development server, use Ctrl+c in the command prompt.

Step 6: Start building

At this point your CLI is fully authorized and ready to create new projects.

✨ The next step on your journey is to create a new app of your own!