Custom functions BETA

Defining a function

Functions are defined in your app via the DefineFunction method, which is part of the SDK that gets included with every newly created project. These function definitions are stored under the manifest/functions/ directory.

Let’s go ahead and create a new function definition file under manifest/functions directory. Name it something related to what the function does. In our Bolt for JavaScript Starter Template, we name the file sample-function.js. Let’s take a peek at it:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

const { DefineFunction, Schema } = require('@slack/bolt');

const SampleFunctionDefinition = DefineFunction({
  callback_id: 'sample_function_id',
  title: 'Send a greeting',
  description: 'Send greeting to channel',
  input_parameters: {
    properties: {
      recipient: {
        type: Schema.slack.types.user_id,
        description: 'Send greeting to this recipient',
      },
      message: {
        type: Schema.types.string,
        description: 'Message to the recipient',
      },
    },
    required: ['message'],
  },
  output_parameters: {
    properties: {
      greeting: {
        type: Schema.types.string,
        description: 'Greeting for the recipient',
      },
    },
    required: ['greeting'],
  },
});

module.exports = { SampleFunctionDefinition };

Note that we import DefineFunction, which is used for defining our function, and also Schema, which has information on supported built-in types.

Just like workflows, custom functions have a unique callback_id and also require a title. Additionally, you can set inputs and outputs just like you can with workflows.

Here’s all the fields you can use when defining a custom function:

The value for properties in input_parameters and output_parameters needs to be an object with further sub-properties:

• type: The type of the input parameter. This can be a built-in type or a custom type that you define.
• description: A string description of the parameter.

If you want to set a property as required, list its name in its respective input or output properties as a required property.

For example, if you have an input parameter named customer_id that you want to be required, you can do so like this:

1
2
3
4
5
6
7
8
9

input_parameters: {
  properties: {
    customer_id: {
      type: Schema.types.string,
      description: "The customer's ID"
    }
  },
  required: ["customer_id"]
}

Functions can (and generally should) declare inputs and outputs.

Inputs are declared in the input_parameters property, and outputs are declared in the output_parameters property. Each can contain either built-in types or custom types that you define.

While, strictly speaking, input and output parameters are optional, they are a common and standard way to pass data between functions and nearly any function you write will expect at least one input and pass along an output.

Functions are similar in philosophy to Unix system commands: they should be minimalist, modular, and reusable. Expect the output of one function to eventually become the input of another, with no other frame of reference.

Once your function is defined in its own file in manifest/functions, the next steps are to add a function listener, register the listener, and implement the function in a workflow.

Implementing a function listener

Implement functions in just a few steps:

1. Create the function definition file in the manifest/functions directory

If you haven’t done so already, create a file for your function definition to live in and name it something that makes sense for your function. In the Bolt for JavaScript Starter Template, we named this file sample-function.js

2. Add function listener and handler(s)

Once your function has been defined, you’ll need to register a function listener to trigger the function’s functionality as well as any other related events.

To do this, create a file in listeners/functions directory for your function listener (in this case, the file will be called hello-world.js). This file will use the function definition you created earlier and also implement any needed additional logic—in this case, it’ll send a message to greet someone based on what is being passed in as inputs. You can see the full completed hello-world.js function listener here.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// listeners/functions/hello-world.js
// For more information about functions: https://api.slack.com/future/functions
const { SlackFunction } = require('@slack/bolt');

// Get our function Definition from the manifest!
const { SampleFunctionDefinition } = require('../../manifest/functions/sample-function');

// Here is the work we want to do!
const helloWorld = async ({ event, complete }) => {
  const { recipient, message } = event.inputs;
  const salutations = ['Hello', 'Hi', 'Howdy', 'Hola', 'Salut'];
  const salutation = salutations[Math.floor(Math.random() * salutations.length)];
  try {
    const greeting = `${salutation}, <@${recipient}>! :wave: Someone sent the following greeting: \n\n>${message}`;
    complete({ outputs: { greeting } });
  } catch (err) {
    // Complete function with an error
    await complete({ error: `There was an issue: ${err}` });
    throw (err);
  }
};

// Let's create a new Slack function with helloWorld as its handler
const helloWorldFunc = new SlackFunction(SampleFunctionDefinition.id, helloWorld);

module.exports = { helloWorldFunc };

The hello-world.js file declares a function handler, helloWorld, that takes in inputs from the event, which is the payload received when your function is being executed. It executes logic within the handler to return a message with a random greeting. This message is the function’s output. In addition to the function handler, a new SlackFunction instance is declared that actually links the helloWorld handler to SampleFunctionDefinition through the function’s ID:

1
2

// Let's create a new Slack function with helloWorld as its handler
const helloWorldFunc = new SlackFunction(SampleFunctionDefinition.id, helloWorld);

Once this file has been created, the function handler can be registered in an index.js file within the listeners/functions directory:

1
2
3
4
5
6
7
8

// listeners/functions/index.js
const { helloWorldFunc } = require('./hello-world');

// Register a complete function
module.exports.register = (app) => {
  app.function(helloWorldFunc);
  // Register another function here
};

Lastly, in order to make sure this handler is triggered, make sure the function listeners are registered in your listeners/index.js file:

1
2
3
4
5
6

// listeners/index.js
const functions = require('./functions');

module.exports.registerListeners = (app) => {
  functions.register(app);
};

3. Add the function as a step in your workflow

To actually call the defined function, SampleFunctionDefinition, don’t forget to add your function to a workflow! When you’re finished defining and implementing your functions, the next step is to add them to workflows. Once added as a step in a workflow, your function will run when that workflow is invoked by a trigger.

Next steps

You’ve learned about built-in and custom functions - now it’s time to jump into workflows and learn about how they work with functions. 🎉