0
# @slack/types
1

2
@slack/types provides comprehensive TypeScript type definitions for building Slack applications and integrations with the Node Slack SDK. This package serves as the foundational type system for the entire Slack development ecosystem, offering strongly-typed interfaces for Block Kit components, event handling, message formatting, and all Slack API interactions.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import {
15
  Button,
16
  SectionBlock,
17
  PlainTextElement,
18
  SlackEvent,
19
  ModalView,
20
  MessageAttachment,
21
  MessageMetadata,
22
  Dialog,
23
  BotProfile
24
} from "@slack/types";
25
```
26

27
For CommonJS:
28

29
```javascript
30
const {
31
  Button,
32
  SectionBlock,
33
  PlainTextElement,
34
  SlackEvent,
35
  ModalView,
36
  MessageAttachment,
37
  MessageMetadata,
38
  Dialog,
39
  BotProfile
40
} = require("@slack/types");
41
```
42

43
## Basic Usage
44

45
```typescript
46
import { SectionBlock, PlainTextElement, Button } from "@slack/types";
47

48
// Define a section block with text and button
49
const section: SectionBlock = {
50
  type: "section",
51
  text: {
52
    type: "plain_text",
53
    text: "Hello from Slack!"
54
  },
55
  accessory: {
56
    type: "button",
57
    text: {
58
      type: "plain_text",
59
      text: "Click me"
60
    },
61
    value: "button_1",
62
    action_id: "button_action"
63
  }
64
};
65

66
// Use in a message or modal
67
const message = {
68
  blocks: [section]
69
};
70
```
71

72
## Architecture
73

74
@slack/types is organized around several key architectural patterns:
75

76
- **Discriminated Unions**: All blocks and elements use `type` field as the discriminator for type safety
77
- **Composition Mixins**: Shared behaviors like `Actionable`, `Confirmable` are mixed into concrete interfaces
78
- **Hierarchical Structure**: Views contain Blocks, Blocks contain Elements, Elements contain Composition Objects
79
- **Event System**: Comprehensive event type system with discriminated unions for all 70+ Slack event types
80
- **Legacy Support**: Deprecated types maintained for backward compatibility with clear deprecation markers
81

82
## Capabilities
83

84
### Block Kit Framework
85

86
Core building blocks for creating rich, interactive Slack interfaces including blocks, elements, and composition objects. Essential for building modern Slack apps with sophisticated UI components.
87

88
```typescript { .api }
89
// Block types
90
type KnownBlock = ActionsBlock | ContextBlock | DividerBlock | FileBlock | HeaderBlock | ImageBlock | InputBlock | MarkdownBlock | RichTextBlock | SectionBlock | VideoBlock;
91

92
// Key block interfaces
93
interface SectionBlock extends Block {
94
  type: 'section';
95
  text?: TextObject;
96
  fields?: TextObject[];
97
  accessory?: SectionBlockAccessory;
98
  expand?: boolean;
99
}
100

101
interface ActionsBlock extends Block {
102
  type: 'actions';
103
  elements: ActionsBlockElement[];
104
}
105
```
106

107
[Block Kit Framework](./block-kit.md)
108

109
### Interactive Elements
110

111
Complete set of interactive UI components for user input including buttons, select menus, date pickers, and text inputs. These elements enable rich user interactions within Slack interfaces.
112

113
```typescript { .api }
114
interface Button extends Actionable, Confirmable {
115
  type: 'button';
116
  text: PlainTextElement;
117
  value?: string;
118
  url?: string;
119
  style?: ColorScheme;
120
  accessibility_label?: string;
121
}
122

123
interface PlainTextInput extends Actionable, Dispatchable, Focusable, Placeholdable {
124
  type: 'plain_text_input';
125
  initial_value?: string;
126
  multiline?: boolean;
127
  min_length?: number;
128
  max_length?: number;
129
}
130
```
131

132
[Interactive Elements](./interactive-elements.md)
133

134
### Event System
135

136
Comprehensive event type definitions for all Slack Events API events including message events, user events, channel events, and app events. Essential for building reactive Slack applications.
137

138
```typescript { .api }
139
type SlackEvent = AppDeletedEvent | AppHomeOpenedEvent | AppMentionEvent | ChannelCreatedEvent | MessageEvent | UserChangeEvent | /* ...70+ more event types */;
140

141
interface MessageEvent {
142
  type: 'message';
143
  channel: string;
144
  user: string;
145
  text: string;
146
  ts: string;
147
  thread_ts?: string;
148
  blocks?: AnyBlock[];
149
}
150
```
151

152
[Event System](./events.md)
153

154
### Views and Modals
155

156
Type definitions for Slack surfaces including modals, App Home tabs, and workflow step configuration views. Critical for building interactive Slack applications with sophisticated user interfaces.
157

158
```typescript { .api }
159
type View = HomeView | ModalView | WorkflowStepView;
160

161
interface ModalView extends BaseView {
162
  type: 'modal';
163
  title: PlainTextElement;
164
  close?: PlainTextElement;
165
  submit?: PlainTextElement;
166
  clear_on_close?: boolean;
167
  notify_on_close?: boolean;
168
}
169
```
170

171
[Views and Modals](./views.md)
172

173
### Message Attachments
174

175
Legacy message attachment system for adding rich content to messages. While Block Kit is preferred for new development, attachments remain supported for backward compatibility.
176

177
```typescript { .api }
178
interface MessageAttachment {
179
  blocks?: AnyBlock[];
180
  fallback?: string;
181
  color?: 'good' | 'warning' | 'danger' | string;
182
  title?: string;
183
  text?: string;
184
  fields?: MessageAttachmentField[];
185
  image_url?: string;
186
  footer?: string;
187
}
188
```
189

190
[Message Attachments](./message-attachments.md)
191

192
### Calls API
193

194
Type definitions for Slack Calls API enabling 3rd party call integrations within the Slack client. Used for displaying external call information and participants.
195

196
```typescript { .api }
197
type CallUser = CallUserSlack | CallUserExternal;
198

199
interface CallUserSlack {
200
  slack_id: string;
201
}
202

203
interface CallUserExternal {
204
  external_id: string;
205
  display_name: string;
206
  avatar_url?: string;
207
}
208
```
209

210
[Calls API](./calls.md)
211

212
### Message Metadata
213

214
Application-specific data that can be attached to Slack messages to enable rich interactive experiences and custom workflows. Essential for building contextual applications.
215

216
```typescript { .api }
217
interface MessageMetadata {
218
  /** Human readable alphanumeric string representing your application's metadata event */
219
  event_type: string;
220
  /** Free-form object containing whatever data your application wishes to attach */
221
  event_payload: {
222
    [key: string]: string | number | boolean | MessageMetadataEventPayloadObject | MessageMetadataEventPayloadObject[];
223
  };
224
}
225

226
interface MessageMetadataEventPayloadObject {
227
  [key: string]: string | number | boolean;
228
}
229
```
230

231
[Message Metadata](./message-metadata.md)
232

233
### Dialog Interface
234

235
Legacy dialog interface for simple form collection. This interface is deprecated in favor of Block Kit modals but remains available for backward compatibility.
236

237
```typescript { .api }
238
/**
239
 * @deprecated Dialogs are deprecated. Use Block Kit modals instead.
240
 */
241
interface Dialog {
242
  title: string;
243
  callback_id: string;
244
  elements: DialogElement[];
245
  submit_label?: string;
246
  notify_on_cancel?: boolean;
247
  state?: string;
248
}
249
```
250

251
[Dialog Interface](./dialog.md)
252

253
## Common Types
254

255
### Core Composition Objects
256

257
```typescript { .api }
258
type TextObject = PlainTextElement | MrkdwnElement;
259

260
interface PlainTextElement {
261
  type: 'plain_text';
262
  text: string;
263
  emoji?: boolean;
264
}
265

266
interface MrkdwnElement {
267
  type: 'mrkdwn';
268
  text: string;
269
  verbatim?: boolean;
270
}
271
```
272

273
### Color and Styling
274

275
```typescript { .api }
276
type ColorScheme = 'primary' | 'danger';
277
type ConversationType = 'im' | 'mpim' | 'private' | 'public';
278
```
279

280
### Extension Mixins
281

282
```typescript { .api }
283
interface Actionable {
284
  type: string;
285
  action_id?: string;
286
}
287

288
interface Confirmable {
289
  confirm?: ConfirmationDialog;
290
}
291

292
interface Placeholdable {
293
  placeholder?: PlainTextElement;
294
}
295
```
296

297
### Shared Entity Types
298

299
```typescript { .api }
300
interface BotProfile {
301
  id: string;
302
  name: string;
303
  app_id: string;
304
  team_id: string;
305
  icons: {
306
    [size: string]: string;
307
  };
308
  updated: number;
309
  deleted: boolean;
310
}
311

312
interface StatusEmojiDisplayInfo {
313
  emoji_name?: string;
314
  display_alias?: string;
315
  display_url?: string;
316
}
317
```