CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-slack--bolt

A framework for building Slack apps, fast.

—

Pending
Overview
Eval results
Files

receivers.mddocs/

Request Receivers

Receivers handle incoming HTTP requests and WebSocket connections from Slack, providing different deployment options for Slack Bolt applications including traditional servers, serverless functions, and Socket Mode connections.

Capabilities

Express Receiver

HTTP receiver using Express.js framework for traditional server deployments with OAuth support.

/**
 * Express.js-based HTTP receiver with OAuth integration
 * @param options - Configuration options for Express receiver
 */
class ExpressReceiver implements Receiver {
  constructor(options: ExpressReceiverOptions);
  
  /** Express application instance */
  readonly app: Application;
  /** Express router instance */
  readonly router: IRouter;
  /** OAuth installer instance (if configured) */
  readonly installer?: InstallProvider;
  
  /** Initialize receiver with app instance */
  init(app: App): void;
  /** Start HTTP server on specified port */
  start(port: number): Promise<Server>;
  /** Stop HTTP server */
  stop(): Promise<void>;
  /** Request handler middleware for Express */
  requestHandler(req: Request, res: Response): Promise<void>;
}

interface ExpressReceiverOptions {
  /** Signing secret for request verification */
  signingSecret: string;
  /** Custom logger instance */
  logger?: Logger;
  /** Log level for built-in logging */
  logLevel?: LogLevel;
  /** Custom endpoints for different request types */
  endpoints?: string | { [key: string]: string };
  /** Process events before sending HTTP response */
  processBeforeResponse?: boolean;
  /** OAuth client ID */
  clientId?: string;
  /** OAuth client secret */
  clientSecret?: string;
  /** State parameter secret for OAuth */
  stateSecret?: string;
  /** OAuth permission scopes */
  scopes?: string[];
  /** Installation provider options */
  installerOptions?: InstallProviderOptions;
  /** Custom Express routes */
  customRoutes?: CustomRoute[];
  /** Custom properties to add to context */
  customPropertiesExtractor?: (request: BufferedIncomingMessage) => StringIndexed;
}

Usage Examples:

import { App, ExpressReceiver } from "@slack/bolt";

// Basic usage
const receiver = new ExpressReceiver({
  signingSecret: process.env.SLACK_SIGNING_SECRET!,
});

const app = new App({
  token: process.env.SLACK_BOT_TOKEN,
  receiver,
});

// With OAuth
const receiverWithOAuth = new ExpressReceiver({
  signingSecret: process.env.SLACK_SIGNING_SECRET!,
  clientId: process.env.SLACK_CLIENT_ID,
  clientSecret: process.env.SLACK_CLIENT_SECRET,
  stateSecret: "my-state-secret",
  scopes: ["chat:write", "commands"],
});

// With custom routes
const receiverWithRoutes = new ExpressReceiver({
  signingSecret: process.env.SLACK_SIGNING_SECRET!,
  customRoutes: [
    {
      path: "/health",
      method: ["GET"],
      handler: (req, res) => {
        res.writeHead(200);
        res.end("OK");
      },
    },
  ],
});

Socket Mode Receiver

WebSocket-based receiver for Socket Mode connections, ideal for development and environments where HTTP endpoints are not available.

/**
 * WebSocket-based receiver for Socket Mode connections
 * @param options - Configuration options for Socket Mode
 */
class SocketModeReceiver implements Receiver {
  constructor(options: SocketModeReceiverOptions);
  
  /** Socket Mode client instance */
  readonly client: SocketModeClient;
  /** OAuth installer instance (if configured) */
  readonly installer?: InstallProvider;
  
  /** Initialize receiver with app instance */
  init(app: App): void;
  /** Start Socket Mode connection */
  start(): Promise<AppsConnectionsOpenResponse>;
  /** Stop Socket Mode connection */
  stop(): Promise<void>;
}

interface SocketModeReceiverOptions {
  /** App-level token starting with xapp- */
  appToken: string;
  /** Custom logger instance */
  logger?: Logger;
  /** Log level for built-in logging */
  logLevel?: LogLevel;
  /** Custom client options for socket mode */
  clientOptions?: SocketModeOptions;
  /** Custom properties to add to context */
  customPropertiesExtractor?: (event: ReceiverEvent) => StringIndexed;
}

Usage Examples:

import { App, SocketModeReceiver } from "@slack/bolt";

// Basic Socket Mode setup
const receiver = new SocketModeReceiver({
  appToken: process.env.SLACK_APP_TOKEN!,
});

const app = new App({
  token: process.env.SLACK_BOT_TOKEN,
  receiver,
});

// With custom options
const customReceiver = new SocketModeReceiver({
  appToken: process.env.SLACK_APP_TOKEN!,
  logLevel: "DEBUG",
  clientOptions: {
    pingInterval: 30000,
    closeTimeout: 5000,
  },
});

HTTP Receiver

Basic HTTP receiver without Express.js dependency for lightweight deployments.

/**
 * Basic HTTP receiver without Express.js dependency
 * @param options - Configuration options for HTTP receiver
 */
class HTTPReceiver implements Receiver {
  constructor(options: HTTPReceiverOptions);
  
  /** HTTP request listener function */
  readonly requestListener: RequestListener;
  /** OAuth installer instance (if configured) */
  readonly installer?: InstallProvider;
  
  /** Initialize receiver with app instance */
  init(app: App): void;
  /** Start HTTP server on specified port */
  start(
    port: number | string | ListenOptions,
    serverOptions?: ServerOptions | HTTPSServerOptions
  ): Promise<Server | HTTPSServer>;
  /** Stop HTTP server */
  stop(): Promise<void>;
}

interface HTTPReceiverOptions {
  /** Signing secret for request verification */
  signingSecret: string;
  /** Custom logger instance */
  logger?: Logger;
  /** Log level for built-in logging */
  logLevel?: LogLevel;
  /** Custom endpoints for different request types */
  endpoints?: string | { [key: string]: string };
  /** Process events before sending HTTP response */
  processBeforeResponse?: boolean;
  /** Custom properties to add to context */
  customPropertiesExtractor?: (request: BufferedIncomingMessage) => StringIndexed;
  /** Custom request dispatcher */
  dispatchErrorHandler?: (args: ReceiverDispatchErrorHandlerArgs) => Promise<void>;
  /** Custom event processing error handler */
  processEventErrorHandler?: (args: ReceiverProcessEventErrorHandlerArgs) => Promise<boolean>;
  /** Custom unhandled request handler */
  unhandledRequestHandler?: (args: ReceiverUnhandledRequestHandlerArgs) => void;
  /** Custom request timeout in milliseconds */
  requestTimeout?: number;
}

Usage Examples:

import { App, HTTPReceiver } from "@slack/bolt";

// Basic HTTP receiver
const receiver = new HTTPReceiver({
  signingSecret: process.env.SLACK_SIGNING_SECRET!,
});

const app = new App({
  token: process.env.SLACK_BOT_TOKEN,
  receiver,
});

// With custom error handling
const customReceiver = new HTTPReceiver({
  signingSecret: process.env.SLACK_SIGNING_SECRET!,
  processEventErrorHandler: async ({ error, logger, request, response }) => {
    logger.error("Event processing failed", error);
    return false; // Don't retry
  },
  unhandledRequestHandler: ({ logger, request, response }) => {
    logger.warn("Unhandled request", request.url);
    response.writeHead(404);
    response.end("Not Found");
  },
});

AWS Lambda Receiver

Serverless receiver for AWS Lambda function deployments.

/**
 * Serverless receiver for AWS Lambda deployments
 * @param options - Configuration options for Lambda receiver
 */
class AwsLambdaReceiver implements Receiver {
  constructor(options: AwsLambdaReceiverOptions);
  
  /** Logger instance */
  get logger(): Logger;
  
  /** Initialize receiver with app instance */
  init(app: App): void;
  /** Start receiver (returns handler for Lambda) */
  start(...args: any[]): Promise<AwsHandler>;
  /** Stop receiver */
  stop(...args: any[]): Promise<void>;
  
  /** 
   * AWS Lambda handler function
   * @param event - Lambda event object
   * @param context - Lambda context object
   * @param callback - Lambda callback function
   */
  toHandler(): AwsHandler;
}

interface AwsLambdaReceiverOptions {
  /** Signing secret for request verification */
  signingSecret: string;
  /** Custom logger instance */
  logger?: Logger;
  /** Log level for built-in logging */
  logLevel?: LogLevel;
  /** Process events before sending HTTP response */
  processBeforeResponse?: boolean;
  /** Custom properties to add to context */
  customPropertiesExtractor?: (request: BufferedIncomingMessage) => StringIndexed;
}

Usage Examples:

import { App, AwsLambdaReceiver } from "@slack/bolt";

// Lambda receiver setup
const receiver = new AwsLambdaReceiver({
  signingSecret: process.env.SLACK_SIGNING_SECRET!,
});

const app = new App({
  token: process.env.SLACK_BOT_TOKEN,
  receiver,
});

// Export Lambda handler
export const handler = receiver.toHandler();

// Usage in serverless.yml or AWS CDK
/*
functions:
  slack:
    handler: dist/lambda.handler
    events:
      - http:
          path: /slack/events
          method: post
*/

Custom Routes

Add custom HTTP routes to Express and HTTP receivers.

interface CustomRoute {
  /** Route path pattern */
  path: string;
  /** HTTP methods to handle */
  method: string | string[];
  /** Route handler function */
  handler: (req: IncomingMessage, res: ServerResponse) => void;
}

interface ReceiverRoutes {
  [path: string]: CustomRoute;
}

/**
 * Build receiver routes from route definitions
 * @param routes - Array of custom route definitions
 * @returns ReceiverRoutes object
 */
function buildReceiverRoutes(routes: CustomRoute[]): ReceiverRoutes;

Usage Examples:

import { ExpressReceiver, buildReceiverRoutes } from "@slack/bolt";

const customRoutes = buildReceiverRoutes([
  {
    path: "/api/status",
    method: ["GET"],
    handler: (req, res) => {
      res.writeHead(200, { "Content-Type": "application/json" });
      res.end(JSON.stringify({ status: "healthy" }));
    },
  },
  {
    path: "/api/webhook",
    method: ["POST"],
    handler: (req, res) => {
      // Handle webhook
      res.writeHead(200);
      res.end("OK");
    },
  },
]);

const receiver = new ExpressReceiver({
  signingSecret: process.env.SLACK_SIGNING_SECRET!,
  customRoutes: Object.values(customRoutes),
});

HTTP Module Functions

Utility functions and types for HTTP request handling.

interface ReceiverDispatchErrorHandlerArgs {
  error: Error | CodedError;
  logger: Logger;
  request: IncomingMessage;
  response: ServerResponse;
}

interface ReceiverProcessEventErrorHandlerArgs {
  error: Error | CodedError;
  logger: Logger;
  request: IncomingMessage;
  response: ServerResponse;
  storedResponse: any;
}

interface ReceiverUnhandledRequestHandlerArgs {
  logger: Logger;
  request: IncomingMessage;
  response: ServerResponse;
}

class BufferedIncomingMessage extends IncomingMessage {
  body: string;
  rawBody: Buffer;
}

class HTTPResponseAck {
  constructor(response: ServerResponse);
  
  /** Send acknowledgment response */
  ack(): Promise<void>;
}

Request Verification

interface RequestVerificationOptions {
  /** Signing secret from Slack app settings */
  signingSecret: string;
  /** Raw request body as string */
  body: string;
  /** Request headers object */
  headers: { [key: string]: string | string[] | undefined };
}

/**
 * Verify Slack request signature
 * @param options - Verification options
 * @returns True if request is valid
 */
function verifySlackRequest(options: RequestVerificationOptions): boolean;

/**
 * Check if Slack request is valid
 * @param options - Verification options  
 * @returns True if request signature is valid
 */
function isValidSlackRequest(options: RequestVerificationOptions): boolean;

Install with Tessl CLI

npx tessl i tessl/npm-slack--bolt

docs

advanced-features.md

core-application.md

index.md

middleware.md

receivers.md

request-verification.md

tile.json