Our future generation platform is in closed beta. Please request to participate. During the beta, expect some rough edges, broken windows overlooking blue sky vistas, and regularly scheduled changes.

Frequently asked questions & errata

Our next-generation platform evolves regularly and you can expect new "releases" every two weeks or so. Occasionally, we get so excited about features we know are coming around the bend that we might document them early and confuse the heck out of folks. For this, and other reasons, we put together this FAQ and errata reference.

FAQ

Some of these questions we've seen frequently asked internally or by alpha and beta developers but to tell you the truth most FAQs are made up of questions you imagine people having. If we're missing a glory of gotchas, please do let us know.

How do I set up my developer environment?

First, make sure you've applied and been granted access to the future generation platform private beta. The workspace you use when applying will become the workspace enabled for the beta.

After receiving beta approval, download the latest version of the slack CLI and install it.

Using a combination of your favorite text editor, the slack CLI tool, and the included future generation SDK, you will program in TypeScript for a Deno-based runtime.

Our getting started tutorial tutorial will walk you through the entire process in detail.

How do I just send messages in the future generation platform?

The most straight-forward way to send a message to a channel is with the SendMessage built-in function.

If you need to do something more complex--like send a message with metadata--you can use the client object proxy when defining a function to make Web API calls to methods like chat.postMessage.

Here is an example of using the client object to call chat.postMessage, and pass along some metadata in a custom message:

export const SendExampleMessage = DefineFunction(
  "send_example_message",
  {
    title: "Send Example Message",
    description: "Sends a message with metadata via chat.postMessage",
    input_parameters: {
      required: ["the_channel_id"],
      properties: {
        the_channel_id: {
          type: Schema.slack.types.channel_id,
          description: "The channel to post the message.",
        },
      },
    },
    output_parameters: {
      required: [],
      properties: {},
    },
  },
  async ({ inputs, client, env }) => {
    const result = await client.call("chat.postMessage", {
      channel: inputs.the_channel_id,
      text:
        "With a great effort, the rug is moved to one side of the room, revealing the dusty cover of a closed trap door.",
      metadata: {
        event_type: "rug_moved",
        event_payload: {
          id: "ZORK-RUG-MOVED-1310",
          summary: "The user moved the rug to reveal a trap door",
          results: [
            "rug:moved",
            "door:revealed",
            "door:closed",
          ],
          waiting_for: "COMMAND",
        },
      },
    });
    return {};
  },
);

It's also possible to send messages at part of workflows using built in functions.

How do I make calls to Web API methods?

Under the hood, you're granted modern bot tokens in the future generation platform and they're able to call just about any method a bot user token can already call. You might not receive the token in exactly the same way, but as far as the Deno runtime is concerned, you can get a handle on the current bot token context by calling client.

For example, if I had the permissions already to list conversations my bot/application is a member of, I can call conversations.members and then inspect the result in result:

let result = await client.call("conversations.members");

Which Events API events can I use in the future generation platform?

The Events API itself is not yet a direct member of the future generation platform. We're gradually exposing a limited number of existing and net new events as triggers your app can subscribe to, along with metadata.

How do I migrate my slack project from 0.7.1 to 1.0.0?

To migrate your project to the latest Slack Cloud SDK, you'll need to modify how you define both input_parameters and output_parameters in Functions and Workflows.

For custom Functions and Workflows you have written, all input and output parameters are now encapsulated in a properties property of both input_parameters and output_parameters, respectively. There is also a new required property that allows you to specify which parameters must be provided for the Function or Workflow to run.

0.7.1 Syntax (old)

input_parameters: {
  stringToReverse: {
    type: Schema.types.string,
    description: "The string to reverse"
  }
},
output_parameters: {
  reverseString: {
    type: Schema.types.string,
    description: "The string in reverse",
  },
},

1.0.0 Syntax (current)

input_parameters: {
  required: [],  // NEW
  properties: {  // NEW
    stringToReverse: {
      type: Schema.types.string,
      description: "The string to reverse"
    }
  }
},
output_parameters: {
  required: [],  // NEW
  properties: {  // NEW
    reverseString: {
      type: Schema.types.string,
      description: "The string in reverse",
    }
  }
},

My webhook triggers aren't working!

Here are a few things to check:

  • Confirm your app is installed on the workspace you would expect with slack deploy, and that the URL you are using matches what you see from slack triggers.

  • Confirm the availableToChannel() the function is called on your Trigger definition, and that the channel there is a public channel you are in.

  • Confirm that you are seeing a 200 status from the HTTP request. If it's not a 200, the error message should give you some hints.

  • An invalid_input response probably means your payload can't be mapped to the contextual data fields you declared in .withInputs(). Make sure the names in the payload exactly match the path defined (e.g. ctx.data.my_string expects a top-level my_string key in your payload).

  • An invalid_auth error shouldn't happen unless the secret portion of the URL is not correct. Re-confirm that the URL from slack triggers matches the one you are trying to curl. Note that the URL may change (for now) if you re-deploy the webhook after changing the availableToChannel() call.

  • A 404 webhook_not_found error means the resource in the URL is not correct. Re-confirm that the URL returned by slack triggers matches the one you are trying to curl.

How do I grant others access to invoke a shortcut trigger?

By default, all triggers are disabled in a workspace except for the owner of the application.

To grant specific users access to invoke a shortcut, use the availableToWorkspaceUsers method. Find more info and example code here.

To grant all users of a specific channel access to invoke a shortcut, use the availableToChannel method. Find more info and example code here.

How do I build a slash command in the future generation platform?

Slash commands as they've been known in previous generations of the platform are not part of the new platform. You can, however, still invoke your app by pulling up the Shortcut menu with the slash (/) key and typing the name of your Shortcut. Think of Shortcuts as the modern version of Slash commands; they have a similar front-end (where you can invoke them /like this) but are more robust on the back-end. We may refer to this clever way of executing a shortcut as a slash command, especially to end users, so fear not fellow slash commandos.

What languages can I program in while hosting with Slack?

Currently, our hosted apps only support Typescript in a Deno runtime environment.

Errata

Hosting, deployment, and installation

  • Workspace owners and administrators cannot run slack deploy to deploy apps when a workspace has admin-approved apps turned on. Use an alternative non-admin or non-owner account to build, test, and deploy beta apps.
  • JSON or YAML-based app manifests are no longer how your app's configuration is canonically defined. Instead, most definitions go in project.ts and function definitions are defined in code.

Tools

Was this page helpful?