0
# Views & Modals
1
2
Open, update, and manage interactive modals and home tabs for rich user interfaces. The Views API allows you to create modal dialogs and App Home tabs that provide sophisticated user interactions within Slack.
3
4
## Capabilities
5
6
### Open View
7
8
Open a modal dialog or App Home tab.
9
10
```typescript { .api }
11
/**
12
* Open a view for a user
13
* @param options - View configuration with trigger or interactivity pointer
14
* @returns Promise resolving to view details
15
*/
16
views.open(options: ViewsOpenArguments): Promise<ViewsOpenResponse>;
17
18
type ViewsOpenArguments = BaseViewsArguments & TokenOverridable & (ViewTriggerId | ViewInteractivityPointer);
19
20
interface BaseViewsArguments {
21
/** A view payload defining the modal or home tab structure */
22
view: View;
23
}
24
25
interface ViewTriggerId {
26
/** Access token from a user interaction - required to open views */
27
trigger_id: string;
28
}
29
30
interface ViewInteractivityPointer {
31
/** Access token from a user interaction - alternative to trigger_id */
32
interactivity_pointer: string;
33
}
34
35
interface ViewsOpenResponse extends WebAPICallResult {
36
/** The opened view object */
37
view?: View;
38
}
39
```
40
41
**Usage Examples:**
42
43
```typescript
44
import { WebClient } from "@slack/web-api";
45
46
const web = new WebClient(process.env.SLACK_BOT_TOKEN);
47
48
// Open a modal dialog
49
const result = await web.views.open({
50
trigger_id: "123456.789.abc",
51
view: {
52
type: "modal",
53
title: {
54
type: "plain_text",
55
text: "My Modal"
56
},
57
blocks: [
58
{
59
type: "section",
60
text: {
61
type: "mrkdwn",
62
text: "Hello from a modal!"
63
}
64
}
65
]
66
}
67
});
68
69
// Open an App Home tab
70
await web.views.publish({
71
user_id: "U1234567890",
72
view: {
73
type: "home",
74
blocks: [
75
{
76
type: "section",
77
text: {
78
type: "mrkdwn",
79
text: "Welcome to the App Home!"
80
}
81
}
82
]
83
}
84
});
85
```
86
87
### Push View
88
89
Push a new view onto the modal stack.
90
91
```typescript { .api }
92
/**
93
* Push a view onto the stack of a root view
94
* @param options - View configuration with trigger or interactivity pointer
95
* @returns Promise resolving to view details
96
*/
97
views.push(options: ViewsPushArguments): Promise<ViewsPushResponse>;
98
99
type ViewsPushArguments = BaseViewsArguments & TokenOverridable & (ViewTriggerId | ViewInteractivityPointer);
100
101
interface ViewsPushResponse extends WebAPICallResult {
102
/** The pushed view object */
103
view?: View;
104
}
105
```
106
107
### Update View
108
109
Update an existing view with new content.
110
111
```typescript { .api }
112
/**
113
* Update an existing view
114
* @param options - View configuration with view identifier
115
* @returns Promise resolving to updated view details
116
*/
117
views.update(options: ViewsUpdateArguments): Promise<ViewsUpdateResponse>;
118
119
type ViewsUpdateArguments = BaseViewsArguments & TokenOverridable & (ViewExternalId | ViewViewId) & ViewHash;
120
121
interface ViewExternalId {
122
/** Unique identifier set by developer - alternative to view_id */
123
external_id: string;
124
}
125
126
interface ViewViewId {
127
/** Unique identifier of the view to update */
128
view_id: string;
129
}
130
131
interface ViewHash {
132
/** String representing view state to prevent race conditions */
133
hash?: string;
134
}
135
136
interface ViewsUpdateResponse extends WebAPICallResult {
137
/** The updated view object */
138
view?: View;
139
}
140
```
141
142
### Publish View
143
144
Publish a static view to a user's App Home tab.
145
146
```typescript { .api }
147
/**
148
* Publish a static view for a user
149
* @param options - View configuration with user ID
150
* @returns Promise resolving to published view details
151
*/
152
views.publish(options: ViewsPublishArguments): Promise<ViewsPublishResponse>;
153
154
interface ViewsPublishArguments extends BaseViewsArguments, TokenOverridable, ViewHash {
155
/** ID of the user to publish the view to */
156
user_id: string;
157
}
158
159
interface ViewsPublishResponse extends WebAPICallResult {
160
/** The published view object */
161
view?: View;
162
}
163
```
164
165
## Core Types
166
167
```typescript { .api }
168
interface View {
169
/** App ID that owns the view */
170
app_id?: string;
171
/** Team ID where app is installed */
172
app_installed_team_id?: string;
173
/** Array of blocks that define the view structure */
174
blocks?: Block[];
175
/** Bot ID associated with the view */
176
bot_id?: string;
177
/** Developer-defined callback identifier */
178
callback_id?: string;
179
/** Whether to clear view state when closed */
180
clear_on_close?: boolean;
181
/** Close button configuration */
182
close?: TextObject;
183
/** External ID set by developer */
184
external_id?: string;
185
/** Hash for preventing race conditions */
186
hash?: string;
187
/** Unique view identifier */
188
id?: string;
189
/** Whether to notify when view is closed */
190
notify_on_close?: boolean;
191
/** ID of the previous view in the stack */
192
previous_view_id?: string;
193
/** Private metadata string (up to 3000 characters) */
194
private_metadata?: string;
195
/** Root view ID in the stack */
196
root_view_id?: string;
197
/** Current state of input elements */
198
state?: ViewState;
199
/** Submit button configuration */
200
submit?: TextObject;
201
/** Whether submit button is disabled */
202
submit_disabled?: boolean;
203
/** Team ID associated with the view */
204
team_id?: string;
205
/** Title of the view */
206
title?: TextObject;
207
/** Type of view - 'modal' or 'home' */
208
type?: string;
209
}
210
211
interface TextObject {
212
/** Whether text contains emoji */
213
emoji?: boolean;
214
/** Text content */
215
text?: string;
216
/** Text type - 'plain_text' or 'mrkdwn' */
217
type?: string;
218
/** Whether to use verbatim text rendering */
219
verbatim?: boolean;
220
}
221
222
interface ViewState {
223
values?: Record<string, Record<string, any>>;
224
}
225
226
interface TokenOverridable {
227
/** Override the default token for this request */
228
token?: string;
229
}
230
```