This IntegrationIntegration - An integration is the place the you write your code to get things done! Written in NodeJS, an integration runs in Fusebit's secure and scalable environment to translate between the needs of your backend application and the remote service or services you're connecting to. allows full access to the Slack Web API for cloud-hosted instances from your application. Fusebit's multi-tenant approach makes it easy for you to manage multiple Slack connections on behalf of your app's users. Our Node.js-based programming model and lightweight deployment story make it easy to customize the Integration with any necessary business logic.

Getting Started

  1. Use the Fusebit Management PortalFusebit Management Portal - The Fusebit Management Portal enables you to easily setup and manage all your integrations in one place. Link: https://manage.fusebit.io to create an account and log in.
  2. Create a new Integration using one of our Slack templates
  1. You will then be able to run the Integration, download it's code, modify it, and deploy your changes. Detailed instructions on how to get started with an Integration are available here.

Invoking the Slack API

The Integration template comes pre-configured with some example calls that invoke Slack's API, for example:

const result = await slackClient.chat.postMessage({
  text: 'Hello world from Fusebit!',
  channel: 'demo',
 });

The slackClient object provided by Fusebit is an instance of the @slack/web-api npm package. The full reference documentation for the package is available here.

Fusebit ensures the above SDK object is already bootstrapped with the Slack credentials of the user invoking the integration. You do not need to worry about obtaining an access token or refresh token -- Fusebit does that for you automatically.

Creating your own Slack App

Out of the box, Fusebit's Slack Integration uses our own demonstration application in the Slack App Directory. This is to make it easier to get started, however you will likely need to register your own Slack App in case:

  • the Slack method you are executing via the SDK requires more advanced permissions
  • you want to receive inbound messages via the Slack Events API
  • you want to deploy your Integration in production and you want end-users to see your own branding instead of Fusebit branding

To create your own Slack App:

  1. Go to https://api.slack.com/apps and create an App "from scratch". Pick your company workspace for development, the app will be installed on your customer workspaces once it has been set up.
  1. Note the Client ID and Client Secret shown on the next screen.
  1. If the method(s) you want to invoke against the Slack API require certain permissions see here, add the appropriate scopes under Features > OAuth & Permissions > Scopes > Bot Token Scopes.

The following permissions are necessary to run the example provided later: channels:join, channels:read, chat:write, users:read.

  1. Back in the Fusebit Portal, find the Integration you would like to connect to the new Slack App you just created. Select the ConnectorConnector - A connector is the package from Fusebit that manages the relationship between one or more integrations and a specific service. One of the most common types of connector is an OAuth connector, which takes care of the OAuth negotiation between your customers and the service you're integrating, so that you don't have to! tied to that integration

📘

If more than one Integration is linked to that same Connector, they will all use the new Slack App you are about to configure.

  1. Select Enable Production Credentials in the Connector Configuration and then paste in the Client ID and Client Secret you obtained earlier from the Slack App you created. Also, list the permissions your code requires in the Bot Token Scopes field. To use the example provided later in this guide, specify the following scopes: channels:join channels:read chat:write users:read.

🚧

When switching a Connector to a different Slack App, all IdentityIdentity - An identity is a unique relationship one of your customers has with a service. An identity can be used by multiple integrations to act on that service on behalf of your customer. objects associated with that Connector will be deleted. Your users will need to re-authenticate against Slack after you make the change.

  1. Navigate back to your Slack App and over to Features > OAuth & Permissions > Redirect URLs and paste the URL provided by Fusebit in the Slack Configuration section under OAuth2 Redirect URL
  1. Any time a new user installs your Integration, you should now see your Slack App information displayed during the authorization step.

Receiving events from Slack (Event API support)

With this Slack App configuration, your Fusebit Integration will be able to post messages as a bot (or on behalf of users if you configured that functionality). But you will likely also want to get notified when users respond to your messages OR when they post certain keywords or commands. We can achieve that by configuring Slack’s Event API and connecting it to Fusebit

  1. Make sure you are you are using your own Slack App and have configured your Connector with that app's secrets
  2. In your Connector, paste the Signing Secret you find under App Credentials in your Slack App

In your Connector, note the Events API Request URL as you will need it in the next step

  1. In your Slack App configuration, go to Features > Event Subscriptions:
    1. Toggle Enable Events
    2. In the Request URL field, paste the URL you copied from Fusebit in the previous step
  1. You need to decide what event types you would like to listen to, and ensure your app is registered for those events and has requested the relevant scopes. In this example, we will subscribe to the message.channels Bot User event which requires the channels:history scope.
    1. In Features > Event Subscriptions under Subscribe to bot events (or Subscribe to events on behalf of users) add the event type message.channels
    2. In Features > OAuth & Permissions > Scopes > Bot Token Scopes, add channels:history
    3. In your Connector, make sure you add the channels:history scope in the Bot User Token Scopes field.

Once you have configured Slack Events API support in your Connector, you can receive events in your Integration. The Connector will route all events from the workspace (team) that your Integration was authorized for when it was created.

  1. Depending on the permissions you requested, your Bot User may need to be a member of a channel to receive events for activity in that channel. In this example, given the message.channels event type we subscribed to and the associated channels:history permission we requested, you need to add the bot to the channel. You can do that by going to the channel details and selecting More > Add apps
  1. At the bottom of integration.js edit the following handler, which will echo any messages sent to the channel.
integration.event.on('/:componentName/webhook/event_callback', async (ctx) => {
  const slackClient = await integration.service.getSdk(ctx, ctx.params.componentName, ctx.req.body.installIds[0]);
  const messagingUser = ctx.req.body.data.event.user;
  const authorizedListeningUser = ctx.req.body.data.authorizations[0].user_id;

  // Don't echo our bot's own messages
  if (messagingUser !== authorizedListeningUser) {
    const text = ctx.req.body.data.event.text;
    slackClient.chat.postMessage({
      text: 'User <@${messagingUser}> sent message: \n\n "${text}"',
      channel: ctx.req.body.data.event.channel,
    });
  }
});
  1. Type in a message in the channel where the bot was added, you should see your message echoed back in the channel.