0
# Chat Operations
1

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

4
## Capabilities
5

6
### Post Message
7

8
Send messages to channels, groups, or direct messages with rich formatting and attachments.
9

10
```typescript { .api }
11
/**
12
 * Post a message to a conversation
13
 * @param options - Message parameters
14
 * @returns Promise resolving to message details
15
 */
16
chat.postMessage(options: ChatPostMessageArguments): Promise<ChatPostMessageResponse>;
17

18
interface ChatPostMessageArguments {
19
  /** Channel, private group, or DM channel to send message to */
20
  channel: string;
21
  /** Text of the message to send (required if no blocks/attachments) */
22
  text?: string;
23
  /** Post as the authed user instead of as a bot */
24
  as_user?: boolean;
25
  /** Structured message attachments (legacy) */
26
  attachments?: MessageAttachment[];
27
  /** Structured blocks for rich message layout */
28
  blocks?: Block[];
29
  /** Emoji to use as the icon for this message */
30
  icon_emoji?: string;
31
  /** URL to an image to use as the icon for this message */
32
  icon_url?: string;
33
  /** How this message should be linked to other messages */
34
  link_names?: boolean;
35
  /** Additional message metadata */
36
  metadata?: {
37
    event_type: string;
38
    event_payload: Record<string, any>;
39
  };
40
  /** Disable Slack markup parsing */
41
  mrkdwn?: boolean;
42
  /** Change how messages are treated */
43
  parse?: 'full' | 'none';
44
  /** Used with thread_ts to make reply visible to channel */
45
  reply_broadcast?: boolean;
46
  /** Thread timestamp to reply to a specific message */
47
  thread_ts?: string;
48
  /** Unfurl primarily text-based content */
49
  unfurl_links?: boolean;
50
  /** Unfurl media content */  
51
  unfurl_media?: boolean;
52
  /** Set your bot's user name */
53
  username?: string;
54
}
55
```
56

57
**Usage Examples:**
58

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

62
const web = new WebClient(token);
63

64
// Simple text message
65
const result = await web.chat.postMessage({
66
  channel: '#general',
67
  text: 'Hello, world!'
68
});
69

70
// Message with formatting
71
await web.chat.postMessage({
72
  channel: 'C1234567890',
73
  text: 'Check out this *bold* text and ~strikethrough~',
74
  unfurl_links: false
75
});
76

77
// Thread reply
78
await web.chat.postMessage({
79
  channel: '#general',
80
  text: 'This is a reply',
81
  thread_ts: '1234567890.123456'
82
});
83

84
// Message with blocks (rich formatting)
85
await web.chat.postMessage({
86
  channel: '#general',
87
  blocks: [
88
    {
89
      type: 'section',
90
      text: {
91
        type: 'mrkdwn',
92
        text: '*Welcome to the team!* 🎉'
93
      }
94
    },
95
    {
96
      type: 'actions',
97
      elements: [
98
        {
99
          type: 'button',
100
          text: { type: 'plain_text', text: 'Get Started' },
101
          action_id: 'get_started_button'
102
        }
103
      ]
104
    }
105
  ]
106
});
107
```
108

109
### Update Message
110

111
Modify the content of previously sent messages.
112

113
```typescript { .api }
114
/**
115
 * Update a message
116
 * @param options - Update parameters
117
 * @returns Promise resolving to updated message details
118
 */
119
chat.update(options: ChatUpdateArguments): Promise<ChatUpdateResponse>;
120

121
interface ChatUpdateArguments {
122
  /** Channel containing the message to update */
123
  channel: string;
124
  /** Timestamp of the message to update */
125
  ts: string;
126
  /** New text for the update */
127
  text?: string;
128
  /** Post as the authed user instead of as a bot */
129
  as_user?: boolean;
130
  /** Updated structured attachments */
131
  attachments?: MessageAttachment[];
132
  /** Updated structured blocks */
133
  blocks?: Block[];
134
  /** How this message should be linked to other messages */
135
  link_names?: boolean;
136
  /** Additional message metadata */
137
  metadata?: {
138
    event_type: string;
139
    event_payload: Record<string, any>;
140
  };
141
  /** Change how messages are treated */
142
  parse?: 'full' | 'none';
143
  /** Broadcast thread reply to channel */
144
  reply_broadcast?: boolean;
145
}
146
```
147

148
**Usage Examples:**
149

150
```typescript
151
// Update message text
152
const updated = await web.chat.update({
153
  channel: '#general',
154
  ts: '1234567890.123456',
155
  text: 'Updated message content'
156
});
157

158
// Update with new blocks
159
await web.chat.update({
160
  channel: 'C1234567890',
161
  ts: '1234567890.123456',
162
  blocks: [
163
    {
164
      type: 'section',
165
      text: {
166
        type: 'mrkdwn',
167
        text: '*Updated:* Task completed ✅'
168
      }
169
    }
170
  ]
171
});
172
```
173

174
### Delete Message
175

176
Remove messages from conversations.
177

178
```typescript { .api }
179
/**
180
 * Delete a message
181
 * @param options - Delete parameters
182
 * @returns Promise resolving to deletion confirmation
183
 */
184
chat.delete(options: ChatDeleteArguments): Promise<ChatDeleteResponse>;
185

186
interface ChatDeleteArguments {
187
  /** Channel containing the message to delete */
188
  channel: string;
189
  /** Timestamp of the message to delete */
190
  ts: string;
191
  /** Pass true to delete as the authed user */
192
  as_user?: boolean;
193
}
194
```
195

196
**Usage Examples:**
197

198
```typescript
199
// Delete a message
200
const result = await web.chat.delete({
201
  channel: '#general',
202
  ts: '1234567890.123456'
203
});
204

205
if (result.ok) {
206
  console.log('Message deleted successfully');
207
}
208
```
209

210
### Schedule Message
211

212
Schedule messages to be sent at a future time.
213

214
```typescript { .api }
215
/**
216
 * Schedule a message to be sent later
217
 * @param options - Scheduling parameters
218
 * @returns Promise resolving to scheduled message details
219
 */
220
chat.scheduleMessage(options: ChatScheduleMessageArguments): Promise<ChatScheduleMessageResponse>;
221

222
interface ChatScheduleMessageArguments {
223
  /** Channel to send the scheduled message to */
224
  channel: string;
225
  /** Unix timestamp when the message should be sent */
226
  post_at: number;
227
  /** Text of the message */
228
  text?: string;
229
  /** Structured attachments */
230
  attachments?: MessageAttachment[];
231
  /** Structured blocks */
232
  blocks?: Block[];
233
  /** Pass true to post as the authed user */
234
  as_user?: boolean;
235
  /** How this message should be linked to other messages */
236
  link_names?: boolean;
237
  /** Change how messages are treated */
238
  parse?: 'full' | 'none';
239
  /** Thread timestamp to reply to a message */
240
  thread_ts?: string;
241
  /** Unfurl links in message text */
242
  unfurl_links?: boolean;
243
  /** Unfurl media in message */
244
  unfurl_media?: boolean;
245
}
246
```
247

248
**Usage Examples:**
249

250
```typescript
251
// Schedule message for tomorrow at 9 AM
252
const tomorrow9AM = Math.floor(Date.now() / 1000) + (24 * 60 * 60) + (9 * 60 * 60);
253

254
const scheduled = await web.chat.scheduleMessage({
255
  channel: '#general',
256
  text: 'Good morning! Daily standup in 30 minutes.',
257
  post_at: tomorrow9AM
258
});
259

260
console.log('Scheduled message ID:', scheduled.scheduled_message_id);
261
```
262

263
### Ephemeral Messages
264

265
Send messages visible only to specific users.
266

267
```typescript { .api }
268
/**
269
 * Send an ephemeral message to a user in a channel
270
 * @param options - Ephemeral message parameters
271
 * @returns Promise resolving to message details
272
 */
273
chat.postEphemeral(options: ChatPostEphemeralArguments): Promise<ChatPostEphemeralResponse>;
274

275
interface ChatPostEphemeralArguments {
276
  /** Channel to send the ephemeral message in */
277
  channel: string;
278
  /** User who will receive the ephemeral message */
279
  user: string;
280
  /** Text of the message */
281
  text?: string;
282
  /** Structured attachments */
283
  attachments?: MessageAttachment[];
284
  /** Structured blocks */
285
  blocks?: Block[];
286
  /** Pass true to post as the authed user */
287
  as_user?: boolean;
288
  /** Emoji to use as icon */
289
  icon_emoji?: string;
290
  /** URL to image for icon */
291
  icon_url?: string;
292
  /** Link names in the message */
293
  link_names?: boolean;
294
  /** Change how messages are treated */
295
  parse?: 'full' | 'none';
296
  /** Thread timestamp to reply to */
297
  thread_ts?: string;
298
  /** Set bot's username */
299
  username?: string;
300
}
301
```
302

303
**Usage Examples:**
304

305
```typescript
306
// Send private message visible only to specific user
307
await web.chat.postEphemeral({
308
  channel: '#general',
309
  user: 'U1234567890',
310
  text: 'This message is only visible to you!'
311
});
312

313
// Ephemeral message with blocks
314
await web.chat.postEphemeral({
315
  channel: '#general',
316
  user: 'U1234567890',
317
  blocks: [
318
    {
319
      type: 'section',
320
      text: {
321
        type: 'mrkdwn',
322
        text: ':warning: *Private reminder:* Your task deadline is approaching.'
323
      }
324
    }
325
  ]
326
});
327
```
328

329
### Message Permalinks
330

331
Generate permanent links to messages.
332

333
```typescript { .api }
334
/**
335
 * Get a permalink URL for a message
336
 * @param options - Permalink parameters
337
 * @returns Promise resolving to permalink details
338
 */
339
chat.getPermalink(options: ChatGetPermalinkArguments): Promise<ChatGetPermalinkResponse>;
340

341
interface ChatGetPermalinkArguments {
342
  /** Channel containing the message */
343
  channel: string;
344
  /** Timestamp of the message */
345
  message_ts: string;
346
}
347
```
348

349
**Usage Examples:**
350

351
```typescript
352
const permalink = await web.chat.getPermalink({
353
  channel: '#general',
354
  message_ts: '1234567890.123456'
355
});
356

357
console.log('Message permalink:', permalink.permalink);
358
// https://example.slack.com/archives/C1234567890/p1234567890123456
359
```
360

361
### Scheduled Message Management
362

363
List and manage scheduled messages.
364

365
```typescript { .api }
366
/**
367
 * List scheduled messages
368
 * @param options - List parameters
369
 * @returns Promise resolving to scheduled messages list
370
 */
371
chat.scheduledMessages.list(options?: ChatScheduledMessagesListArguments): Promise<ChatScheduledMessagesListResponse>;
372

373
/**
374
 * Delete a scheduled message
375
 * @param options - Delete parameters  
376
 * @returns Promise resolving to deletion confirmation
377
 */
378
chat.deleteScheduledMessage(options: ChatDeleteScheduledMessageArguments): Promise<ChatDeleteScheduledMessageResponse>;
379

380
interface ChatDeleteScheduledMessageArguments {
381
  /** Channel containing the scheduled message */
382
  channel: string;
383
  /** ID of the scheduled message to delete */
384
  scheduled_message_id: string;
385
  /** Pass true to delete as the authed user */
386
  as_user?: boolean;
387
}
388
```
389

390
**Usage Examples:**
391

392
```typescript
393
// List all scheduled messages
394
const scheduledMessages = await web.chat.scheduledMessages.list();
395

396
for (const message of scheduledMessages.scheduled_messages) {
397
  console.log(`Message "${message.text}" scheduled for ${new Date(message.post_at * 1000)}`);
398
}
399

400
// Delete a scheduled message
401
await web.chat.deleteScheduledMessage({
402
  channel: '#general',
403
  scheduled_message_id: 'Q1234567890'
404
});
405
```
406

407
## Types
408

409
```typescript { .api }
410
interface ChatPostMessageResponse extends WebAPICallResult {
411
  channel: string;
412
  ts: string;
413
  message: {
414
    text: string;
415
    user: string;
416
    ts: string;
417
    team: string;
418
    bot_id?: string;
419
    app_id?: string;
420
  };
421
}
422

423
interface MessageAttachment {
424
  color?: string;
425
  fallback?: string;
426
  title?: string;
427
  title_link?: string;
428
  text?: string;
429
  fields?: { title: string; value: string; short?: boolean }[];
430
  footer?: string;
431
  footer_icon?: string;
432
  ts?: number;
433
}
434

435
interface Block {
436
  type: string;
437
  block_id?: string;
438
  [key: string]: any;
439
}
440
```