0
# Request Receivers
1

2
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.
3

4
## Capabilities
5

6
### Express Receiver
7

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

10
```typescript { .api }
11
/**
12
 * Express.js-based HTTP receiver with OAuth integration
13
 * @param options - Configuration options for Express receiver
14
 */
15
class ExpressReceiver implements Receiver {
16
  constructor(options: ExpressReceiverOptions);
17
  
18
  /** Express application instance */
19
  readonly app: Application;
20
  /** Express router instance */
21
  readonly router: IRouter;
22
  /** OAuth installer instance (if configured) */
23
  readonly installer?: InstallProvider;
24
  
25
  /** Initialize receiver with app instance */
26
  init(app: App): void;
27
  /** Start HTTP server on specified port */
28
  start(port: number): Promise<Server>;
29
  /** Stop HTTP server */
30
  stop(): Promise<void>;
31
  /** Request handler middleware for Express */
32
  requestHandler(req: Request, res: Response): Promise<void>;
33
}
34

35
interface ExpressReceiverOptions {
36
  /** Signing secret for request verification */
37
  signingSecret: string;
38
  /** Custom logger instance */
39
  logger?: Logger;
40
  /** Log level for built-in logging */
41
  logLevel?: LogLevel;
42
  /** Custom endpoints for different request types */
43
  endpoints?: string | { [key: string]: string };
44
  /** Process events before sending HTTP response */
45
  processBeforeResponse?: boolean;
46
  /** OAuth client ID */
47
  clientId?: string;
48
  /** OAuth client secret */
49
  clientSecret?: string;
50
  /** State parameter secret for OAuth */
51
  stateSecret?: string;
52
  /** OAuth permission scopes */
53
  scopes?: string[];
54
  /** Installation provider options */
55
  installerOptions?: InstallProviderOptions;
56
  /** Custom Express routes */
57
  customRoutes?: CustomRoute[];
58
  /** Custom properties to add to context */
59
  customPropertiesExtractor?: (request: BufferedIncomingMessage) => StringIndexed;
60
}
61
```
62

63
**Usage Examples:**
64

65
```typescript
66
import { App, ExpressReceiver } from "@slack/bolt";
67

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

73
const app = new App({
74
  token: process.env.SLACK_BOT_TOKEN,
75
  receiver,
76
});
77

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

87
// With custom routes
88
const receiverWithRoutes = new ExpressReceiver({
89
  signingSecret: process.env.SLACK_SIGNING_SECRET!,
90
  customRoutes: [
91
    {
92
      path: "/health",
93
      method: ["GET"],
94
      handler: (req, res) => {
95
        res.writeHead(200);
96
        res.end("OK");
97
      },
98
    },
99
  ],
100
});
101
```
102

103
### Socket Mode Receiver
104

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

107
```typescript { .api }
108
/**
109
 * WebSocket-based receiver for Socket Mode connections
110
 * @param options - Configuration options for Socket Mode
111
 */
112
class SocketModeReceiver implements Receiver {
113
  constructor(options: SocketModeReceiverOptions);
114
  
115
  /** Socket Mode client instance */
116
  readonly client: SocketModeClient;
117
  /** OAuth installer instance (if configured) */
118
  readonly installer?: InstallProvider;
119
  
120
  /** Initialize receiver with app instance */
121
  init(app: App): void;
122
  /** Start Socket Mode connection */
123
  start(): Promise<AppsConnectionsOpenResponse>;
124
  /** Stop Socket Mode connection */
125
  stop(): Promise<void>;
126
}
127

128
interface SocketModeReceiverOptions {
129
  /** App-level token starting with xapp- */
130
  appToken: string;
131
  /** Custom logger instance */
132
  logger?: Logger;
133
  /** Log level for built-in logging */
134
  logLevel?: LogLevel;
135
  /** Custom client options for socket mode */
136
  clientOptions?: SocketModeOptions;
137
  /** Custom properties to add to context */
138
  customPropertiesExtractor?: (event: ReceiverEvent) => StringIndexed;
139
}
140
```
141

142
**Usage Examples:**
143

144
```typescript
145
import { App, SocketModeReceiver } from "@slack/bolt";
146

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

152
const app = new App({
153
  token: process.env.SLACK_BOT_TOKEN,
154
  receiver,
155
});
156

157
// With custom options
158
const customReceiver = new SocketModeReceiver({
159
  appToken: process.env.SLACK_APP_TOKEN!,
160
  logLevel: "DEBUG",
161
  clientOptions: {
162
    pingInterval: 30000,
163
    closeTimeout: 5000,
164
  },
165
});
166
```
167

168
### HTTP Receiver
169

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

172
```typescript { .api }
173
/**
174
 * Basic HTTP receiver without Express.js dependency
175
 * @param options - Configuration options for HTTP receiver
176
 */
177
class HTTPReceiver implements Receiver {
178
  constructor(options: HTTPReceiverOptions);
179
  
180
  /** HTTP request listener function */
181
  readonly requestListener: RequestListener;
182
  /** OAuth installer instance (if configured) */
183
  readonly installer?: InstallProvider;
184
  
185
  /** Initialize receiver with app instance */
186
  init(app: App): void;
187
  /** Start HTTP server on specified port */
188
  start(
189
    port: number | string | ListenOptions,
190
    serverOptions?: ServerOptions | HTTPSServerOptions
191
  ): Promise<Server | HTTPSServer>;
192
  /** Stop HTTP server */
193
  stop(): Promise<void>;
194
}
195

196
interface HTTPReceiverOptions {
197
  /** Signing secret for request verification */
198
  signingSecret: string;
199
  /** Custom logger instance */
200
  logger?: Logger;
201
  /** Log level for built-in logging */
202
  logLevel?: LogLevel;
203
  /** Custom endpoints for different request types */
204
  endpoints?: string | { [key: string]: string };
205
  /** Process events before sending HTTP response */
206
  processBeforeResponse?: boolean;
207
  /** Custom properties to add to context */
208
  customPropertiesExtractor?: (request: BufferedIncomingMessage) => StringIndexed;
209
  /** Custom request dispatcher */
210
  dispatchErrorHandler?: (args: ReceiverDispatchErrorHandlerArgs) => Promise<void>;
211
  /** Custom event processing error handler */
212
  processEventErrorHandler?: (args: ReceiverProcessEventErrorHandlerArgs) => Promise<boolean>;
213
  /** Custom unhandled request handler */
214
  unhandledRequestHandler?: (args: ReceiverUnhandledRequestHandlerArgs) => void;
215
  /** Custom request timeout in milliseconds */
216
  requestTimeout?: number;
217
}
218
```
219

220
**Usage Examples:**
221

222
```typescript
223
import { App, HTTPReceiver } from "@slack/bolt";
224

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

230
const app = new App({
231
  token: process.env.SLACK_BOT_TOKEN,
232
  receiver,
233
});
234

235
// With custom error handling
236
const customReceiver = new HTTPReceiver({
237
  signingSecret: process.env.SLACK_SIGNING_SECRET!,
238
  processEventErrorHandler: async ({ error, logger, request, response }) => {
239
    logger.error("Event processing failed", error);
240
    return false; // Don't retry
241
  },
242
  unhandledRequestHandler: ({ logger, request, response }) => {
243
    logger.warn("Unhandled request", request.url);
244
    response.writeHead(404);
245
    response.end("Not Found");
246
  },
247
});
248
```
249

250
### AWS Lambda Receiver
251

252
Serverless receiver for AWS Lambda function deployments.
253

254
```typescript { .api }
255
/**
256
 * Serverless receiver for AWS Lambda deployments
257
 * @param options - Configuration options for Lambda receiver
258
 */
259
class AwsLambdaReceiver implements Receiver {
260
  constructor(options: AwsLambdaReceiverOptions);
261
  
262
  /** Logger instance */
263
  get logger(): Logger;
264
  
265
  /** Initialize receiver with app instance */
266
  init(app: App): void;
267
  /** Start receiver (returns handler for Lambda) */
268
  start(...args: any[]): Promise<AwsHandler>;
269
  /** Stop receiver */
270
  stop(...args: any[]): Promise<void>;
271
  
272
  /** 
273
   * AWS Lambda handler function
274
   * @param event - Lambda event object
275
   * @param context - Lambda context object
276
   * @param callback - Lambda callback function
277
   */
278
  toHandler(): AwsHandler;
279
}
280

281
interface AwsLambdaReceiverOptions {
282
  /** Signing secret for request verification */
283
  signingSecret: string;
284
  /** Custom logger instance */
285
  logger?: Logger;
286
  /** Log level for built-in logging */
287
  logLevel?: LogLevel;
288
  /** Process events before sending HTTP response */
289
  processBeforeResponse?: boolean;
290
  /** Custom properties to add to context */
291
  customPropertiesExtractor?: (request: BufferedIncomingMessage) => StringIndexed;
292
}
293
```
294

295
**Usage Examples:**
296

297
```typescript
298
import { App, AwsLambdaReceiver } from "@slack/bolt";
299

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

305
const app = new App({
306
  token: process.env.SLACK_BOT_TOKEN,
307
  receiver,
308
});
309

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

313
// Usage in serverless.yml or AWS CDK
314
/*
315
functions:
316
  slack:
317
    handler: dist/lambda.handler
318
    events:
319
      - http:
320
          path: /slack/events
321
          method: post
322
*/
323
```
324

325
### Custom Routes
326

327
Add custom HTTP routes to Express and HTTP receivers.
328

329
```typescript { .api }
330
interface CustomRoute {
331
  /** Route path pattern */
332
  path: string;
333
  /** HTTP methods to handle */
334
  method: string | string[];
335
  /** Route handler function */
336
  handler: (req: IncomingMessage, res: ServerResponse) => void;
337
}
338

339
interface ReceiverRoutes {
340
  [path: string]: CustomRoute;
341
}
342

343
/**
344
 * Build receiver routes from route definitions
345
 * @param routes - Array of custom route definitions
346
 * @returns ReceiverRoutes object
347
 */
348
function buildReceiverRoutes(routes: CustomRoute[]): ReceiverRoutes;
349
```
350

351
**Usage Examples:**
352

353
```typescript
354
import { ExpressReceiver, buildReceiverRoutes } from "@slack/bolt";
355

356
const customRoutes = buildReceiverRoutes([
357
  {
358
    path: "/api/status",
359
    method: ["GET"],
360
    handler: (req, res) => {
361
      res.writeHead(200, { "Content-Type": "application/json" });
362
      res.end(JSON.stringify({ status: "healthy" }));
363
    },
364
  },
365
  {
366
    path: "/api/webhook",
367
    method: ["POST"],
368
    handler: (req, res) => {
369
      // Handle webhook
370
      res.writeHead(200);
371
      res.end("OK");
372
    },
373
  },
374
]);
375

376
const receiver = new ExpressReceiver({
377
  signingSecret: process.env.SLACK_SIGNING_SECRET!,
378
  customRoutes: Object.values(customRoutes),
379
});
380
```
381

382
## HTTP Module Functions
383

384
Utility functions and types for HTTP request handling.
385

386
```typescript { .api }
387
interface ReceiverDispatchErrorHandlerArgs {
388
  error: Error | CodedError;
389
  logger: Logger;
390
  request: IncomingMessage;
391
  response: ServerResponse;
392
}
393

394
interface ReceiverProcessEventErrorHandlerArgs {
395
  error: Error | CodedError;
396
  logger: Logger;
397
  request: IncomingMessage;
398
  response: ServerResponse;
399
  storedResponse: any;
400
}
401

402
interface ReceiverUnhandledRequestHandlerArgs {
403
  logger: Logger;
404
  request: IncomingMessage;
405
  response: ServerResponse;
406
}
407

408
class BufferedIncomingMessage extends IncomingMessage {
409
  body: string;
410
  rawBody: Buffer;
411
}
412

413
class HTTPResponseAck {
414
  constructor(response: ServerResponse);
415
  
416
  /** Send acknowledgment response */
417
  ack(): Promise<void>;
418
}
419
```
420

421
## Request Verification
422

423
```typescript { .api }
424
interface RequestVerificationOptions {
425
  /** Signing secret from Slack app settings */
426
  signingSecret: string;
427
  /** Raw request body as string */
428
  body: string;
429
  /** Request headers object */
430
  headers: { [key: string]: string | string[] | undefined };
431
}
432

433
/**
434
 * Verify Slack request signature
435
 * @param options - Verification options
436
 * @returns True if request is valid
437
 */
438
function verifySlackRequest(options: RequestVerificationOptions): boolean;
439

440
/**
441
 * Check if Slack request is valid
442
 * @param options - Verification options  
443
 * @returns True if request signature is valid
444
 */
445
function isValidSlackRequest(options: RequestVerificationOptions): boolean;
446
```