0
# Slack Web API
1

2
The @slack/web-api package is the official Node.js SDK for interacting with Slack's Web API. It provides a comprehensive WebClient class that handles authentication, automatic retries, rate limiting, pagination, and error management for accessing over 200 Slack API methods. The library supports modern TypeScript with full type safety and includes robust features for production use.
3

4
## Package Information
5

6
- **Package Name**: @slack/web-api
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @slack/web-api`
10

11
## Core Imports
12

13
```typescript
14
import { WebClient } from "@slack/web-api";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { WebClient } = require("@slack/web-api");
21
```
22

23
Additional imports for error handling and configuration:
24

25
```typescript
26
import { 
27
  WebClient, 
28
  WebAPICallError, 
29
  ErrorCode, 
30
  LogLevel 
31
} from "@slack/web-api";
32
```
33

34
## Basic Usage
35

36
```typescript
37
import { WebClient } from "@slack/web-api";
38

39
// Initialize client with bot token
40
const web = new WebClient(process.env.SLACK_BOT_TOKEN);
41

42
// Post a message
43
const result = await web.chat.postMessage({
44
  channel: '#general',
45
  text: 'Hello world!'
46
});
47

48
// Get user info
49
const userInfo = await web.users.info({
50
  user: 'U1234567890'
51
});
52

53
// List conversations
54
const conversations = await web.conversations.list({
55
  types: 'public_channel,private_channel'
56
});
57
```
58

59
## Architecture
60

61
The Slack Web API library is built around several key components:
62

63
- **WebClient Class**: Main HTTP client providing access to all API methods with automatic retry and rate limiting
64
- **Method Organization**: API methods grouped by namespace (e.g., `chat.*`, `users.*`, `conversations.*`)
65
- **Type Safety**: Complete TypeScript definitions for all request and response types
66
- **Error Handling**: Comprehensive error classes with specific error codes for different failure scenarios
67
- **Pagination Support**: Built-in cursor-based pagination with async iteration
68
- **Configuration System**: Flexible options for logging, retries, timeouts, and HTTP agents
69

70
## Capabilities
71

72
### Client Configuration
73

74
Core WebClient initialization and configuration options for authentication, networking, and behavior customization.
75

76
```typescript { .api }
77
class WebClient {
78
  constructor(token?: string, options?: WebClientOptions);
79
}
80

81
interface WebClientOptions {
82
  slackApiUrl?: string;
83
  logger?: Logger;
84
  logLevel?: LogLevel;
85
  maxRequestConcurrency?: number;
86
  retryConfig?: RetryOptions;
87
  agent?: Agent;
88
  tls?: TLSOptions;
89
  timeout?: number;
90
  rejectRateLimitedCalls?: boolean;
91
  headers?: Record<string, string>;
92
  teamId?: string;
93
}
94
```
95

96
[Client Configuration](./client-configuration.md)
97

98
### Core API Methods
99

100
Essential WebClient methods for making API calls, handling pagination, and uploading files.
101

102
```typescript { .api }
103
apiCall(method: string, options?: Record<string, unknown>): Promise<WebAPICallResult>;
104
paginate(method: string, options?: Record<string, unknown>): AsyncIterable<WebAPICallResult>;
105
filesUploadV2(options: FilesUploadV2Arguments): Promise<WebAPICallResult>;
106
```
107

108
[Core API Methods](./core-api-methods.md)
109

110
### Chat Operations
111

112
Send, update, delete, and schedule messages in Slack channels and direct messages.
113

114
```typescript { .api }
115
chat.postMessage(options: ChatPostMessageArguments): Promise<ChatPostMessageResponse>;
116
chat.update(options: ChatUpdateArguments): Promise<ChatUpdateResponse>;
117
chat.delete(options: ChatDeleteArguments): Promise<ChatDeleteResponse>;
118
chat.scheduleMessage(options: ChatScheduleMessageArguments): Promise<ChatScheduleMessageResponse>;
119
```
120

121
[Chat Operations](./chat-operations.md)
122

123
### Conversation Management
124

125
Create, manage, and interact with Slack channels, groups, and direct messages.
126

127
```typescript { .api }
128
conversations.create(options: ConversationsCreateArguments): Promise<ConversationsCreateResponse>;
129
conversations.list(options?: ConversationsListArguments): Promise<ConversationsListResponse>;
130
conversations.info(options: ConversationsInfoArguments): Promise<ConversationsInfoResponse>;
131
conversations.members(options: ConversationsMembersArguments): Promise<ConversationsMembersResponse>;
132
```
133

134
[Conversation Management](./conversation-management.md)
135

136
### User Operations
137

138
Retrieve user information, manage user profiles, and handle user presence.
139

140
```typescript { .api }
141
users.info(options: UsersInfoArguments): Promise<UsersInfoResponse>;
142
users.list(options?: UsersListArguments): Promise<UsersListResponse>;
143
users.profile.get(options?: UsersProfileGetArguments): Promise<UsersProfileGetResponse>;
144
users.profile.set(options: UsersProfileSetArguments): Promise<UsersProfileSetResponse>;
145
```
146

147
[User Operations](./user-operations.md)
148

149
### File Operations
150

151
Upload files, manage file permissions, and interact with Slack's file storage system.
152

153
```typescript { .api }
154
files.uploadV2(options: FilesUploadV2Arguments): Promise<WebAPICallResult>;
155
files.info(options: FilesInfoArguments): Promise<FilesInfoResponse>;
156
files.list(options?: FilesListArguments): Promise<FilesListResponse>;
157
files.delete(options: FilesDeleteArguments): Promise<FilesDeleteResponse>;
158
```
159

160
[File Operations](./file-operations.md)
161

162
### Admin Operations
163

164
Enterprise Grid administration including user management, team settings, and policy enforcement.
165

166
```typescript { .api }
167
admin.users.invite(options: AdminUsersInviteArguments): Promise<AdminUsersInviteResponse>;
168
admin.conversations.create(options: AdminConversationsCreateArguments): Promise<AdminConversationsCreateResponse>;
169
admin.teams.create(options: AdminTeamsCreateArguments): Promise<AdminTeamsCreateResponse>;
170
```
171

172
[Admin Operations](./admin-operations.md)
173

174
### Authentication & OAuth
175

176
Handle OAuth flows, token management, and authentication verification.
177

178
```typescript { .api }
179
auth.test(): Promise<AuthTestResponse>;
180
oauth.v2.access(options: OauthV2AccessArguments): Promise<OauthV2AccessResponse>;
181
oauth.v2.exchange(options: OauthV2ExchangeArguments): Promise<OauthV2ExchangeResponse>;
182
```
183

184
[Authentication & OAuth](./authentication-oauth.md)
185

186
### Views & Modals
187

188
Open, update, and manage interactive modals and home tabs for rich user interfaces.
189

190
```typescript { .api }
191
views.open(options: ViewsOpenArguments): Promise<ViewsOpenResponse>;
192
views.push(options: ViewsPushArguments): Promise<ViewsPushResponse>;
193
views.update(options: ViewsUpdateArguments): Promise<ViewsUpdateResponse>;
194
views.publish(options: ViewsPublishArguments): Promise<ViewsPublishResponse>;
195
```
196

197
[Views & Modals](./views-modals.md)
198

199
### Reactions
200

201
Add, remove, and retrieve emoji reactions on messages, files, and file comments.
202

203
```typescript { .api }
204
reactions.add(options: ReactionsAddArguments): Promise<ReactionsAddResponse>;
205
reactions.get(options: ReactionsGetArguments): Promise<ReactionsGetResponse>;
206
reactions.list(options?: ReactionsListArguments): Promise<ReactionsListResponse>;
207
reactions.remove(options: ReactionsRemoveArguments): Promise<ReactionsRemoveResponse>;
208
```
209

210
[Reactions](./reactions.md)
211

212
### Search
213

214
Search for messages, files, and content across the Slack workspace with flexible query options.
215

216
```typescript { .api }
217
search.all(options: SearchAllArguments): Promise<SearchAllResponse>;
218
search.files(options: SearchFilesArguments): Promise<SearchFilesResponse>;
219
search.messages(options: SearchMessagesArguments): Promise<SearchMessagesResponse>;
220
```
221

222
[Search](./search.md)
223

224
### Pins
225

226
Pin and unpin messages in channels, and retrieve lists of pinned items.
227

228
```typescript { .api }
229
pins.add(options: PinsAddArguments): Promise<PinsAddResponse>;
230
pins.list(options: PinsListArguments): Promise<PinsListResponse>;
231
pins.remove(options: PinsRemoveArguments): Promise<PinsRemoveResponse>;
232
```
233

234
[Pins](./pins.md)
235

236
### User Groups
237

238
Create, manage, and configure user groups for organizing team members and permissions.
239

240
```typescript { .api }
241
usergroups.create(options: UsergroupsCreateArguments): Promise<UsergroupsCreateResponse>;
242
usergroups.disable(options: UsergroupsDisableArguments): Promise<UsergroupsDisableResponse>;
243
usergroups.enable(options: UsergroupsEnableArguments): Promise<UsergroupsEnableResponse>;
244
usergroups.list(options?: UsergroupsListArguments): Promise<UsergroupsListResponse>;
245
usergroups.update(options: UsergroupsUpdateArguments): Promise<UsergroupsUpdateResponse>;
246
usergroups.users.list(options: UsergroupsUsersListArguments): Promise<UsergroupsUsersListResponse>;
247
usergroups.users.update(options: UsergroupsUsersUpdateArguments): Promise<UsergroupsUsersUpdateResponse>;
248
```
249

250
[User Groups](./user-groups.md)
251

252
### Error Handling
253

254
Comprehensive error types and handling strategies for different failure scenarios.
255

256
```typescript { .api }
257
enum ErrorCode {
258
  RequestError = 'slack_webapi_request_error',
259
  HTTPError = 'slack_webapi_http_error', 
260
  PlatformError = 'slack_webapi_platform_error',
261
  RateLimitedError = 'slack_webapi_rate_limited_error'
262
}
263

264
interface WebAPICallError extends CodedError {
265
  code: ErrorCode;
266
}
267
```
268

269
[Error Handling](./error-handling.md)
270

271
## Core Types
272

273
```typescript { .api }
274
interface WebAPICallResult {
275
  ok: boolean;
276
  error?: string;
277
  response_metadata?: {
278
    warnings?: string[];
279
    next_cursor?: string;
280
    scopes?: string[];
281
  };
282
}
283

284
interface CodedError extends NodeJS.ErrnoException {
285
  code: ErrorCode;
286
}
287

288
type PageReducer<A = any> = (accumulator: A | undefined, page: WebAPICallResult) => A;
289
type PaginatePredicate = (page: WebAPICallResult) => boolean;
290
```