0
# Message Attachments
1

2
Message attachments provide a legacy system for adding rich, structured content to Slack messages. While Block Kit is now the preferred approach for new development, attachments remain fully supported for backward compatibility and specific use cases.
3

4
## Capabilities
5

6
### Message Attachment Structure
7

8
Core interface for secondary message attachments.
9

10
```typescript { .api }
11
interface MessageAttachment {
12
  blocks?: AnyBlock[];
13
  fallback?: string;
14
  color?: 'good' | 'warning' | 'danger' | string;
15
  pretext?: string;
16
  author_name?: string;
17
  author_link?: string;
18
  author_icon?: string;
19
  author_subname?: string;
20
  title?: string;
21
  title_link?: string;
22
  text?: string;
23
  fields?: MessageAttachmentField[];
24
  image_url?: string;
25
  thumb_url?: string;
26
  footer?: string;
27
  footer_icon?: string;
28
  ts?: string;
29
  actions?: AttachmentAction[];
30
  callback_id?: string;
31
  mrkdwn_in?: ('pretext' | 'text' | 'fields')[];
32
  app_unfurl_url?: string;
33
  is_app_unfurl?: boolean;
34
  app_id?: string;
35
  bot_id?: string;
36
  preview?: MessageAttachmentPreview;
37
}
38
```
39

40
**Basic Usage Example:**
41

42
```typescript
43
import { MessageAttachment } from "@slack/types";
44

45
const attachment: MessageAttachment = {
46
  color: "good",
47
  title: "Deployment Successful",
48
  title_link: "https://example.com/deployment/12345",
49
  text: "Version 2.1.4 has been successfully deployed to production.",
50
  fields: [
51
    {
52
      title: "Environment",
53
      value: "Production",
54
      short: true
55
    },
56
    {
57
      title: "Duration",
58
      value: "3 minutes 42 seconds",
59
      short: true
60
    }
61
  ],
62
  footer: "Deployment Bot",
63
  footer_icon: "https://example.com/icons/deploy.png",
64
  ts: "1609459200"
65
};
66
```
67

68
### Attachment Fields
69

70
Table-like field display within attachments.
71

72
```typescript { .api }
73
interface MessageAttachmentField {
74
  title: string;
75
  value: string;
76
  short?: boolean;
77
}
78
```
79

80
**Usage Example:**
81

82
```typescript
83
const fields: MessageAttachmentField[] = [
84
  {
85
    title: "Priority",
86
    value: "High",
87
    short: true
88
  },
89
  {
90
    title: "Status",
91
    value: "In Progress",
92
    short: true
93
  },
94
  {
95
    title: "Description",
96
    value: "This is a longer description that will span the full width",
97
    short: false
98
  }
99
];
100
```
101

102
### Link Unfurls
103

104
URL-to-attachment mapping for rich link previews.
105

106
```typescript { .api }
107
interface LinkUnfurls {
108
  [linkUrl: string]: MessageAttachment;
109
}
110
```
111

112
**Usage Example:**
113

114
```typescript
115
import { LinkUnfurls } from "@slack/types";
116

117
const unfurls: LinkUnfurls = {
118
  "https://example.com/article/123": {
119
    color: "#36a64f",
120
    title: "How to Build Great APIs",
121
    title_link: "https://example.com/article/123",
122
    text: "A comprehensive guide to designing and implementing REST APIs that developers love to use.",
123
    author_name: "Jane Developer",
124
    author_icon: "https://example.com/avatars/jane.png",
125
    image_url: "https://example.com/images/api-guide.png",
126
    footer: "Dev Blog",
127
    footer_icon: "https://example.com/favicon.ico",
128
    ts: "1609459200"
129
  }
130
};
131
```
132

133
## Attachment Properties
134

135
### Visual Styling
136

137
#### Color Bar
138

139
Left border color to categorize or highlight attachments.
140

141
```typescript { .api }
142
color?: 'good' | 'warning' | 'danger' | string;
143
```
144

145
- `'good'` - Green color for positive/success states
146
- `'warning'` - Yellow color for warning states  
147
- `'danger'` - Red color for error/failure states
148
- Custom hex color (e.g., `'#439FE0'`)
149

150
#### Pretext
151

152
Text appearing above the attachment block.
153

154
```typescript { .api }
155
pretext?: string;
156
```
157

158
### Author Information
159

160
Author details displayed at the top of the attachment.
161

162
```typescript { .api }
163
author_name?: string;
164
author_link?: string;
165
author_icon?: string;
166
author_subname?: string;
167
```
168

169
**Usage Example:**
170

171
```typescript
172
const authorAttachment: MessageAttachment = {
173
  author_name: "GitHub",
174
  author_link: "https://github.com/user/repo",
175
  author_icon: "https://github.com/favicon.ico",
176
  title: "New Pull Request",
177
  text: "Feature: Add user authentication"
178
};
179
```
180

181
### Title and Content
182

183
Main title and body content of the attachment.
184

185
```typescript { .api }
186
title?: string;
187
title_link?: string;
188
text?: string;
189
fallback?: string;
190
```
191

192
The `fallback` property provides plain text for clients that don't support rich attachments.
193

194
### Media Content
195

196
Images and thumbnails within attachments.
197

198
```typescript { .api }
199
image_url?: string;
200
thumb_url?: string;
201
```
202

203
- `image_url` - Large image displayed at bottom (cannot be used with `thumb_url`)
204
- `thumb_url` - Small thumbnail on the right side (75px max)
205

206
### Footer Information
207

208
Footer text and icon displayed at the bottom.
209

210
```typescript { .api }
211
footer?: string;
212
footer_icon?: string;
213
ts?: string;
214
```
215

216
The `ts` property adds a timestamp to the footer display.
217

218
### Markdown Formatting
219

220
Control which fields support markdown formatting.
221

222
```typescript { .api }
223
mrkdwn_in?: ('pretext' | 'text' | 'fields')[];
224
```
225

226
**Usage Example:**
227

228
```typescript
229
const formattedAttachment: MessageAttachment = {
230
  text: "*Bold text* and _italic text_ with `code`",
231
  mrkdwn_in: ["text"],
232
  fields: [
233
    {
234
      title: "Status",
235
      value: "*Active* :white_check_mark:",
236
      short: true
237
    }
238
  ]
239
};
240
```
241

242
## Block Kit Integration
243

244
Modern attachments can include Block Kit content alongside legacy properties.
245

246
```typescript { .api }
247
blocks?: AnyBlock[];
248
```
249

250
**Hybrid Usage Example:**
251

252
```typescript
253
const modernAttachment: MessageAttachment = {
254
  color: "good",
255
  blocks: [
256
    {
257
      type: "section",
258
      text: {
259
        type: "mrkdwn",
260
        text: "*Deployment Status*\nVersion 2.1.4 deployed successfully"
261
      },
262
      accessory: {
263
        type: "button",
264
        text: {
265
          type: "plain_text",
266
          text: "View Logs"
267
        },
268
        action_id: "view_deployment_logs",
269
        url: "https://logs.example.com/deployment/12345"
270
      }
271
    }
272
  ],
273
  fallback: "Deployment successful - Version 2.1.4"
274
};
275
```
276

277
## Legacy Interactive Components
278

279
Deprecated interactive elements for attachments (replaced by Block Kit).
280

281
```typescript { .api }
282
actions?: AttachmentAction[];
283
callback_id?: string;
284
```
285

286
**Note**: Use Block Kit buttons and interactive elements in `blocks` array instead of legacy actions.
287

288
## Confirmation Dialog (Legacy)
289

290
Legacy confirmation structure used in bolt-js.
291

292
```typescript { .api }
293
interface Confirmation {
294
  dismiss_text?: string;
295
  ok_text?: string;
296
  text: string;
297
  title?: string;
298
}
299
```
300

301
## Best Practices
302

303
### When to Use Attachments
304

305
- **Link unfurling**: Rich previews for external URLs
306
- **Legacy compatibility**: Maintaining existing attachment-based integrations  
307
- **Simple structured data**: Basic field/value displays without interaction
308

309
### When to Use Block Kit Instead
310

311
- **New development**: All new Slack apps should use Block Kit
312
- **Interactive elements**: Buttons, select menus, inputs
313
- **Complex layouts**: Multi-column layouts, rich formatting
314
- **Accessibility**: Better screen reader support
315

316
### Migration Path
317

318
To migrate from attachments to Block Kit:
319

320
1. Replace `text` with `SectionBlock` containing `TextObject`
321
2. Replace `fields` with `SectionBlock` using `fields` property
322
3. Replace `actions` with `ActionsBlock` containing Block Kit elements
323
4. Replace `title` with `HeaderBlock` or `SectionBlock` with formatted text
324

325
**Before (Attachment):**
326

327
```typescript
328
const legacyAttachment: MessageAttachment = {
329
  title: "Task Update",
330
  text: "Task has been completed successfully",
331
  fields: [
332
    { title: "Assignee", value: "John Doe", short: true },
333
    { title: "Priority", value: "High", short: true }
334
  ]
335
};
336
```
337

338
**After (Block Kit):**
339

340
```typescript
341
const modernBlocks = [
342
  {
343
    type: "header",
344
    text: { type: "plain_text", text: "Task Update" }
345
  },
346
  {
347
    type: "section",
348
    text: { type: "plain_text", text: "Task has been completed successfully" },
349
    fields: [
350
      { type: "mrkdwn", text: "*Assignee:*\nJohn Doe" },
351
      { type: "mrkdwn", text: "*Priority:*\nHigh" }
352
    ]
353
  }
354
];
355
```