0
# Client Configuration
1

2
WebClient initialization and configuration options for authentication, networking, and behavior customization.
3

4
## Capabilities
5

6
### WebClient Constructor
7

8
Creates a new WebClient instance with optional authentication token and configuration options.
9

10
```typescript { .api }
11
/**
12
 * Creates a new WebClient instance
13
 * @param token - Slack bot or user token (starts with xoxb- or xoxp-)
14
 * @param options - Configuration options for the client
15
 */
16
class WebClient {
17
  constructor(token?: string, options?: WebClientOptions);
18
}
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
import { WebClient, LogLevel } from "@slack/web-api";
25

26
// Basic initialization with token
27
const web = new WebClient(process.env.SLACK_BOT_TOKEN);
28

29
// With configuration options
30
const web = new WebClient(process.env.SLACK_BOT_TOKEN, {
31
  logLevel: LogLevel.DEBUG,
32
  timeout: 30000,
33
  maxRequestConcurrency: 10
34
});
35

36
// Without token (must pass token with each call)
37
const web = new WebClient();
38
const result = await web.apiCall('auth.test', { token: 'xoxb-...' });
39
```
40

41
### WebClientOptions Interface
42

43
Configuration options for customizing WebClient behavior.
44

45
```typescript { .api }
46
interface WebClientOptions {
47
  /** Base URL for API requests (default: https://slack.com/api/) */
48
  slackApiUrl?: string;
49
  /** Custom logger instance */
50
  logger?: Logger;
51
  /** Logging verbosity level */
52
  logLevel?: LogLevel;
53
  /** Maximum concurrent requests (default: 100) */
54
  maxRequestConcurrency?: number;
55
  /** Retry policy configuration */
56
  retryConfig?: RetryOptions;
57
  /** HTTP agent for requests */
58
  agent?: Agent;
59
  /** TLS/SSL configuration */
60
  tls?: TLSOptions;
61
  /** Request timeout in milliseconds */
62
  timeout?: number;
63
  /** Whether to reject rate-limited calls instead of retrying */
64
  rejectRateLimitedCalls?: boolean;
65
  /** Default HTTP headers to include in all requests */
66
  headers?: Record<string, string>;
67
  /** Slack team/workspace ID */
68
  teamId?: string;
69
  /** Allow absolute URLs in method names (default: true) */
70
  allowAbsoluteUrls?: boolean;
71
  /** Include original error in exceptions (default: true) */
72
  attachOriginalToWebAPIRequestError?: boolean;
73
  /** Custom request interceptor function */
74
  requestInterceptor?: RequestInterceptor;
75
  /** Custom HTTP adapter configuration */
76
  adapter?: AdapterConfig;
77
}
78
```
79

80
### Logging Configuration
81

82
Configure logging behavior for debugging and monitoring.
83

84
```typescript { .api }
85
interface Logger {
86
  debug(...msgs: any[]): void;
87
  info(...msgs: any[]): void;
88
  warn(...msgs: any[]): void;
89
  error(...msgs: any[]): void;
90
  setLevel(level: LogLevel): void;
91
  setName(name: string): void;
92
}
93

94
enum LogLevel {
95
  ERROR = 'error',
96
  WARN = 'warn', 
97
  INFO = 'info',
98
  DEBUG = 'debug'
99
}
100
```
101

102
**Usage Examples:**
103

104
```typescript
105
import { WebClient, LogLevel } from "@slack/web-api";
106

107
// Built-in logging levels
108
const web = new WebClient(token, {
109
  logLevel: LogLevel.DEBUG // Will log all requests and responses
110
});
111

112
// Custom logger
113
const customLogger = {
114
  debug: (msg) => console.log(`[DEBUG] ${msg}`),
115
  info: (msg) => console.log(`[INFO] ${msg}`),
116
  warn: (msg) => console.warn(`[WARN] ${msg}`),
117
  error: (msg) => console.error(`[ERROR] ${msg}`)
118
};
119

120
const web = new WebClient(token, { logger: customLogger });
121
```
122

123
### Retry Configuration
124

125
Configure automatic retry behavior for failed requests.
126

127
```typescript { .api }
128
interface RetryOptions {
129
  /** Number of retry attempts */
130
  retries?: number;
131
  /** Factor by which delay increases after each retry */
132
  factor?: number;
133
  /** Minimum delay between retries in milliseconds */
134
  minTimeout?: number;
135
  /** Maximum delay between retries in milliseconds */
136
  maxTimeout?: number;
137
  /** Whether to randomize retry delays */
138
  randomize?: boolean;
139
}
140
```
141

142
**Pre-defined Retry Policies:**
143

144
```typescript { .api }
145
/** Default policy: 10 retries over approximately 30 minutes */
146
const tenRetriesInAboutThirtyMinutes: RetryOptions;
147

148
/** Shorter policy: 5 retries over 5 minutes */
149
const fiveRetriesInFiveMinutes: RetryOptions;
150

151
/** Fast policy for testing scenarios */
152
const rapidRetryPolicy: RetryOptions;
153
```
154

155
**Usage Examples:**
156

157
```typescript
158
import { WebClient, retryPolicies } from "@slack/web-api";
159

160
// Use pre-defined policy
161
const web = new WebClient(token, {
162
  retryConfig: retryPolicies.fiveRetriesInFiveMinutes
163
});
164

165
// Custom retry configuration
166
const web = new WebClient(token, {
167
  retryConfig: {
168
    retries: 3,
169
    factor: 2,
170
    minTimeout: 1000,
171
    maxTimeout: 10000,
172
    randomize: true
173
  }
174
});
175
```
176

177
### Network Configuration
178

179
Configure HTTP behavior including timeouts, agents, and TLS settings.
180

181
```typescript { .api }
182
interface TLSOptions extends SecureContextOptions {
183
  /** Custom TLS/SSL configuration */
184
}
185

186
type RequestInterceptor = (config: RequestConfig) => RequestConfig;
187
type AdapterConfig = AxiosAdapter;
188
```
189

190
**Usage Examples:**
191

192
```typescript
193
import { WebClient } from "@slack/web-api";
194
import { Agent } from "node:http";
195

196
// Custom HTTP agent with connection pooling
197
const agent = new Agent({
198
  keepAlive: true,
199
  maxSockets: 25
200
});
201

202
const web = new WebClient(token, {
203
  agent,
204
  timeout: 30000, // 30 second timeout
205
  headers: {
206
    'User-Agent': 'MySlackApp/1.0.0'
207
  }
208
});
209

210
// Request interceptor for custom headers
211
const web = new WebClient(token, {
212
  requestInterceptor: (config) => {
213
    config.headers['X-Request-ID'] = generateRequestID();
214
    return config;
215
  }
216
});
217
```
218

219
### Rate Limiting Configuration
220

221
Configure how the client handles rate limiting from Slack's API.
222

223
```typescript { .api }
224
/** Whether to reject rate-limited calls instead of automatically retrying */
225
rejectRateLimitedCalls?: boolean;
226
```
227

228
**Usage Examples:**
229

230
```typescript
231
import { WebClient, WebClientEvent } from "@slack/web-api";
232

233
// Handle rate limiting manually
234
const web = new WebClient(token, {
235
  rejectRateLimitedCalls: true
236
});
237

238
// Listen for rate limit events
239
web.on(WebClientEvent.RATE_LIMITED, (retryAfter) => {
240
  console.log(`Rate limited. Retry after ${retryAfter} seconds`);
241
});
242

243
// Automatic retry (default behavior)
244
const web = new WebClient(token, {
245
  rejectRateLimitedCalls: false // Default
246
});
247
```
248

249
## Types
250

251
```typescript { .api }
252
enum WebClientEvent {
253
  RATE_LIMITED = 'rate_limited'
254
}
255

256
type RequestConfig = InternalAxiosRequestConfig;
257
```