# Slack Web API

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.

## Package Information

- **Package Name**: @slack/web-api
- **Package Type**: npm
- **Language**: TypeScript
- **Installation**: `npm install @slack/web-api`

## Core Imports

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

For CommonJS:

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

Additional imports for error handling and configuration:

```typescript
import { 
  WebClient, 
  WebAPICallError, 
  ErrorCode, 
  LogLevel 
} from "@slack/web-api";
```

## Basic Usage

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

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

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

// Get user info
const userInfo = await web.users.info({
  user: 'U1234567890'
});

// List conversations
const conversations = await web.conversations.list({
  types: 'public_channel,private_channel'
});
```

## Architecture

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

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

## Capabilities

### Client Configuration

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

```typescript { .api }
class WebClient {
  constructor(token?: string, options?: WebClientOptions);
}

interface WebClientOptions {
  slackApiUrl?: string;
  logger?: Logger;
  logLevel?: LogLevel;
  maxRequestConcurrency?: number;
  retryConfig?: RetryOptions;
  agent?: Agent;
  tls?: TLSOptions;
  timeout?: number;
  rejectRateLimitedCalls?: boolean;
  headers?: Record<string, string>;
  teamId?: string;
}
```

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

### Core API Methods

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

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

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

### Chat Operations

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

```typescript { .api }
chat.postMessage(options: ChatPostMessageArguments): Promise<ChatPostMessageResponse>;
chat.update(options: ChatUpdateArguments): Promise<ChatUpdateResponse>;
chat.delete(options: ChatDeleteArguments): Promise<ChatDeleteResponse>;
chat.scheduleMessage(options: ChatScheduleMessageArguments): Promise<ChatScheduleMessageResponse>;
```

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

### Conversation Management

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

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

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

### User Operations

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

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

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

### File Operations

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

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

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

### Admin Operations

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

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

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

### Authentication & OAuth

Handle OAuth flows, token management, and authentication verification.

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

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

### Views & Modals

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

```typescript { .api }
views.open(options: ViewsOpenArguments): Promise<ViewsOpenResponse>;
views.push(options: ViewsPushArguments): Promise<ViewsPushResponse>;
views.update(options: ViewsUpdateArguments): Promise<ViewsUpdateResponse>;
views.publish(options: ViewsPublishArguments): Promise<ViewsPublishResponse>;
```

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

### Reactions

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

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

[Reactions](./reactions.md)

### Search

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

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

[Search](./search.md)

### Pins

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

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

[Pins](./pins.md)

### User Groups

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

```typescript { .api }
usergroups.create(options: UsergroupsCreateArguments): Promise<UsergroupsCreateResponse>;
usergroups.disable(options: UsergroupsDisableArguments): Promise<UsergroupsDisableResponse>;
usergroups.enable(options: UsergroupsEnableArguments): Promise<UsergroupsEnableResponse>;
usergroups.list(options?: UsergroupsListArguments): Promise<UsergroupsListResponse>;
usergroups.update(options: UsergroupsUpdateArguments): Promise<UsergroupsUpdateResponse>;
usergroups.users.list(options: UsergroupsUsersListArguments): Promise<UsergroupsUsersListResponse>;
usergroups.users.update(options: UsergroupsUsersUpdateArguments): Promise<UsergroupsUsersUpdateResponse>;
```

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

### Error Handling

Comprehensive error types and handling strategies for different failure scenarios.

```typescript { .api }
enum ErrorCode {
  RequestError = 'slack_webapi_request_error',
  HTTPError = 'slack_webapi_http_error', 
  PlatformError = 'slack_webapi_platform_error',
  RateLimitedError = 'slack_webapi_rate_limited_error'
}

interface WebAPICallError extends CodedError {
  code: ErrorCode;
}
```

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

## Core Types

```typescript { .api }
interface WebAPICallResult {
  ok: boolean;
  error?: string;
  response_metadata?: {
    warnings?: string[];
    next_cursor?: string;
    scopes?: string[];
  };
}

interface CodedError extends NodeJS.ErrnoException {
  code: ErrorCode;
}

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