@oouuyab/slack

A Nestjs module to interact seamlessly with Slack API using the Bolt SDK.

Table of Contents

• Description
• Features
• Installation
• Quick Start
• Configuration
• Usage
  • Using annotations
    • Handling a message event
    • Handling an action
    • Handling a command
    • Handling an event
    • Handling a shortcut event
  • Using the SlackService
• Troubleshooting
• Changelog
• Contributing
• Support
• License
• Contributors

Description

This module provides a convenient way to develop Slack applications using the Nestjs framework. It seamlessly integrates the Slack Bolt SDK with NestJS, allowing you to leverage the power of both platforms.

Features

• Message Handling: Easily respond to and process incoming Slack messages.
• Command Handling: Implement custom Slack commands for your application.
• Action Handling: React to user interactions with buttons, select menus, and other Slack UI elements.
• Event Handling: Listen and respond to various Slack events in real-time.
• Shortcut Handling: Create and manage global and message shortcuts.
• View Submissions: Process and respond to modal view submissions.
• Seamless NestJS Integration: Utilize NestJS dependency injection and module system with Slack Bolt.
• Decorators for Easy Setup: Use custom decorators to quickly set up event listeners.

Installation

$ npm install nestjs-slack-bolt
# or
$ yarn add nestjs-slack-bolt

Quick Start

1. Install the package
2. Set up environment variables (see Configuration)
3. Import SlackModule in your app.module.ts:

import { Module } from '@nestjs/common';
import { SlackModule } from 'nestjs-slack-bolt';

@Module({
  imports: [SlackModule.forRoot()],
})
export class AppModule {}

4. Use decorators in your controllers to handle Slack events

Configuration

Add these variables to your .env file:

# Required for all modes
SLACK_BOT_TOKEN="xoxb-your-bot-token"

# Required for socket mode
SLACK_APP_TOKEN="xapp-your-app-token"
SLACK_SOCKET_MODE=true

# Required for HTTP mode
SLACK_SIGNING_SECRET="your-signing-secret"

You can also pass options to SlackModule.forRoot():

SlackModule.forRoot({
  logLevel: LogLevel.DEBUG,
  // other Bolt app options
});

Usage

Using annotations

Handling a message event

import { Controller } from '@nestjs/common';
import { Message } from 'nestjs-slack-bolt';
import { SlackEventMiddlewareArgs } from '@slack/bolt';

@Controller()
export class AppController {
  @Message('hi')
  message({ say }: SlackEventMiddlewareArgs) {
    say('Hello, I received your message!');
  }
  // Other handlers...
}

Handling an action

import { Controller } from '@nestjs/common';
import { Action } from 'nestjs-slack-bolt';
import { SlackActionMiddlewareArgs } from '@slack/bolt';

@Controller()
export class AppController {
  @Action('click')
  action({ say }: SlackActionMiddlewareArgs) {
    say('Click event received, nice job!');
  }
  // Other handlers...
}

Handling a command

import { Controller } from '@nestjs/common';
import { Command } from 'nestjs-slack-bolt';
import { SlackCommandMiddlewareArgs } from '@slack/bolt';

@Controller()
export class AppController {
  @Command('/list')
  command({ say }: SlackCommandMiddlewareArgs) {
    say('The /list command has been received. Processing...');
  }
  // Other handlers...
}

Handling an event

import { Controller } from '@nestjs/common';
import { Event } from 'nestjs-slack-bolt';
import { SlackEventMiddlewareArgs } from '@slack/bolt';

@Controller()
export class AppController {
  @Event('app_home_opened')
  event({ say }: SlackEventMiddlewareArgs) {
    say('The app was just opened!');
  }
  // Other handlers...
}

Handling a shortcut event

import { Controller } from '@nestjs/common';
import { Shortcut } from 'nestjs-slack-bolt';

@Controller()
export class AppController {
  @Shortcut('test_shortcut')
  async shortcut({ shortcut, ack, client, logger }) {
    try {
      await ack(); //Acknowledge shortcut request

      const result = await client.views.open({
        trigger_id: shortcut.trigger_id,
        view: {
          /* Your view parameters */
        },
      });

      logger.info(result); // Log the result
    } catch (error) {
      logger.error(error); // Log any error
    }
  }
  // Other handlers...
}

Using the SlackService

import { Controller } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { SlackService } from 'nestjs-slack-bolt/services/slack.service';
import { Cron, CronExpression } from '@nestjs/schedule';
import { from } from 'rxjs';

@Controller()
export class AppController {
  constructor(
    private readonly slackService: SlackService,
    private readonly configService: ConfigService,
  ) {}

  @Cron(CronExpression.EVERY_10_SECONDS)
  cronJob() {
    this.searchUsers()
      .pipe()
      .subscribe((users) => {
        console.log(JSON.stringify(users));
      });
  }

  searchUsers(cursor?: string) {
    return from(
      this.slackService.client.users.list({
        token: this.configService.get('SLACK_BOT_TOKEN'),
        limit: 1,
        ...(cursor && { cursor }),
      }),
    );
  }
}

Troubleshooting

Here are some common issues and their solutions:

1. "Cannot find module 'nestjs-slack-bolt'": Ensure you've installed the package correctly.
2. "Invalid token": Double-check your SLACK_BOT_TOKEN in the .env file.
3. Socket mode not working: Verify that SLACK_APP_TOKEN is set and SLACK_SOCKET_MODE is true.

For more issues, please check our GitHub issues or open a new one.

Changelog

See CHANGELOG.md for details on recent changes.

Contributing

We welcome contributions! Please see our CONTRIBUTING.md for details on how to contribute.

Support

For support, please open an issue on our GitHub repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

madcam ⚠️ 💻 📖 🐛

Nadir Abbas ⚠️ 📖 🐛 💻

ognjenco 🐛 💻 📖 ⚠️

This project follows the all-contributors specification.