The new Slack platform is in beta. Your feedback is most welcome.

Link Triggers

Invoke a Workflow from a public channel in Slack

Link triggers are an interactive type of trigger. To invoke one, click on a special "shortcut URL" associated with the Trigger. A Link Trigger will unfurl into a button when posted in a channel. When a Link Trigger is invoked in a channel, it will be placed in a bookmarked "Workflows" folder in that same channel.

There are two steps to setting up a Link Trigger:

  1. Define the Trigger
  2. Create the Link Trigger, either via the CLI or at runtime

1. Define the Trigger

A Trigger contains a Typescript payload with the following parameters:

Parameters

Field Description Required
type The type of Trigger: shortcut
name The name of the Trigger
workflow Path to Workflow that the Trigger initiates
description The description of the Trigger
inputs The inputs provided to the Workflow
shortcut Contains button_text, if desired
shortcut.button_text The text of the shortcut button

The inputs object

Pass any of these values into a Workflow's inputs!

Field Type Description
type string The type of Trigger: shortcut
team_id string A unique identifier for the team where the Trigger was invoked
enterprise_id string A unique identifier for the enterprise where the Trigger was invoked
event_timestamp integer A UNIX timestamp in seconds indicating when the Trigger was invoked
data.user_id string A unique identifier for the Slack user who invoked the Trigger
data.channel_id string A unique identifier for the channel where the Trigger was invoked
data.interactivity object See Block Kit interactivity
data.location string Where the Trigger was invoked. Can be message or bookmark
data.message_ts string A unique UNIX timestamp in seconds indicating when the Trigger-invoking message was sent
data.user object An object containing a user_id and a secret that can be used to identify and validate the specific user who invoked the Trigger
data.action_id string A unique identifier for the action that invoked the Trigger. See Block Kit interactivity
data.block_id string A unique identifier for the block where the Trigger was invoked. See Block Kit interactivity
data.bookmark_id string A unique identifier for the bookmark where the Trigger was invoked

Example TypeScript payload

The following is a TypeScript payload for creating a Link Trigger with an input from a Workflow:

{
  type: "shortcut",
  name: "Reverse a String",
  description: "Starts the workflow to test reversing a string",
  workflow: "#/workflows/test_reverse",
  inputs: {
    interactivity: {
      value: "{{data.interactivity}}",
    },
    channel: {
      value: "{{data.channel_id}}",
    },
  },
};

2. Create the Link Trigger

There are two ways to create a Link Trigger. You can:

Create a Link Trigger with the CLI

While you usually need a trigger file to create a Trigger, you can choose to create a Link Trigger without one.

If your workflow doesn't need any parameters mapped from the Trigger, such as interactivity, then you can create a Trigger like so:

slack trigger create --workflow "#/workflows/your_workflow"

Use the --interactivity flag to create a Trigger that does provide the interactivity parameter:

slack trigger create --workflow "#/workflows/your_workflow" --interactivity

You can, of course, still create a Link Trigger using a trigger file. The trigger file contains the payload you used to define your Trigger.

TypeScript trigger files take the following form:

import { Trigger} from “deno-slack-api/types.ts”;

const trigger : Trigger<typeof ExampleWorkflow.definition> = {
  // your TypeScript payload 
}

export default trigger;

Once you have created a trigger file, use the following command to create the Link Trigger:

slack trigger create --trigger-def "path/to/trigger.ts"

Create a Link Trigger at runtime

Create a Link Trigger at runtime using the client.workflows.triggers.create method within the relevant Function file.

const triggerResponse = await client.workflows.triggers.create<typeof ExampleWorkflow.definition>({
  // your TypeScript payload
});

Link Trigger response

Let's look at an example successful response for a Link Trigger with no inputs. The response will have a property called ok. If true, then the Trigger was created, and the trigger property will be populated.

{
  // If ok == true, the trigger was created
  ok: true,

  // The newly created trigger's details are here
  trigger: {
    // Your trigger's unique ID
    id: "Ft12345",

    // inputs will contain a summary of your inputs as defined in the trigger file
    inputs: {},

    // since this is a link trigger, `outputs` will automatically contain:
    //   {{event_timestamp}}: time when the workflow started
    //   {{data.user_id}}: The user ID of the person who invoked the trigger 
    //                     (by clicking the shortcut link or run button in Slack)
    //   {{data.channel_id}}: The channel where the shortcut was run
    //   {{data.interactivity}}: The trigger's interactivity context 
    outputs: {
      "{{event_timestamp}}": {
        type: "string",
        name: "event_timestamp",
        title: "Time when workflow started",
        is_required: false,
        description: "Time when workflow started"
      },
      "{{data.user_id}}": {
        type: "slack#/types/user_id",
        name: "user_id",
        title: "Person who ran this shortcut",
        is_required: true,
        description: "Person who clicked the shortcut link or run button in Slack"
      },
      "{{data.channel_id}}": {
        type: "slack#/types/channel_id",
        name: "channel_id",
        title: "Channel where the shortcut was run",
        is_required: false,
        description: "Channel where the shortcut was run, if available"
      },
      "{{data.interactivity}}": {
        type: "slack#/types/interactivity",
        name: "interactivity",
        title: "Interactivity context",
        is_required: true,
        description: "Interactivity context",
        is_hidden: true
      }
    },

    // Trigger-specific information
    date_created: 1661894315,
    date_updated: 1661894315,
    type: "shortcut",
    name: "Submit a ticket to our work management system",
    description: "",

    // The shortcut URL that will activate this trigger and invoke the underlying workflow
    shortcut_url: "https://slack.com/shortcuts/Ft12345/caef7d773d611ddd1da81fd85de08a78",

    // Details about the workflow associated with this trigger
    workflow: {
      id: "Fn1234567890",
      callback_id: "handle_new_tickets_workflow",
      title: "Handle new tickets",
      description: "Handles a new ticket and updates the submitting user",
      type: "workflow",

      // Any workflow inputs will be included here
      input_parameters: [],

      // Any of the workflow's outputs will be included here
      output_parameters: [],

      app_id: "A1234567890",

      // App-specific details
      app: {
        id: "A1234567890",
        name: "ticket-management-app",
        icons: [Object],
        is_workflow_app: false
      },
      date_created: 1661889787,
      date_updated: 1661894304,
      date_deleted: 0,
      workflow_id: "Wf01234567890"
    }
  }
}