0
# Dialog Interface
1

2
**⚠️ DEPRECATED**: Dialogs are a deprecated surface in Slack. For new development, use [Views and Modals](./views.md) instead. This interface is maintained for legacy application support.
3

4
## Migration Notice
5

6
Dialogs have been replaced by Block Kit modals which provide better user experience and more flexibility. See the [official migration guide](https://docs.slack.dev/block-kit/upgrading-outmoded-dialogs-to-modals) for upgrading to modals.
7

8
## Capabilities
9

10
### Dialog Interface
11

12
Legacy dialog structure for simple form collection in Slack applications.
13

14
```typescript { .api }
15
/**
16
 * @deprecated Dialogs are deprecated. Use Block Kit modals instead.
17
 * @see https://docs.slack.dev/block-kit/upgrading-outmoded-dialogs-to-modals
18
 */
19
interface Dialog {
20
  /** Dialog title displayed to users */
21
  title: string;
22
  /** Callback identifier for handling submissions */
23
  callback_id: string;
24
  /** Array of form elements */
25
  elements: DialogElement[];
26
  /** Custom text for submit button (default: "Submit") */
27
  submit_label?: string;
28
  /** Whether to notify when dialog is cancelled */
29
  notify_on_cancel?: boolean;
30
  /** Optional state data to include with submissions */
31
  state?: string;
32
}
33

34
interface DialogElement {
35
  /** Element type */
36
  type: 'text' | 'textarea' | 'select';
37
  /** Element identifier */
38
  name: string;
39
  /** Label shown to user */
40
  label: string;
41
  /** Whether element is optional */
42
  optional?: boolean;
43
  /** Placeholder text */
44
  placeholder?: string;
45
  /** Default value */
46
  value?: string;
47
  
48
  // Text and textarea specific
49
  /** Maximum character length */
50
  max_length?: number;
51
  /** Minimum character length */
52
  min_length?: number;
53
  /** Help text shown below element */
54
  hint?: string;
55
  /** Input validation subtype */
56
  subtype?: 'email' | 'number' | 'tel' | 'url';
57
  
58
  // Select specific  
59
  /** Data source for select options */
60
  data_source?: 'users' | 'channels' | 'conversations' | 'external';
61
  /** Pre-selected options */
62
  selected_options?: SelectOption[];
63
  /** Static option list */
64
  options?: SelectOption[];
65
  /** Grouped options */
66
  option_groups?: {
67
    label: string;
68
    options: SelectOption[];
69
  }[];
70
  /** Minimum characters before external search */
71
  min_query_length?: number;
72
}
73

74
interface SelectOption {
75
  /** Option text shown to user */
76
  label: string;
77
  /** Option value sent to application */
78
  value: string;
79
}
80
```
81

82
**Legacy Usage Example:**
83

84
```typescript
85
import { Dialog, SelectOption } from "@slack/types";
86

87
// Simple text input dialog (DEPRECATED - use modals instead)
88
const legacyDialog: Dialog = {
89
  title: "Task Creation",
90
  callback_id: "create_task_dialog",
91
  elements: [
92
    {
93
      type: "text",
94
      name: "task_title",
95
      label: "Task Title",
96
      placeholder: "Enter task title",
97
      max_length: 100
98
    },
99
    {
100
      type: "textarea", 
101
      name: "task_description",
102
      label: "Description",
103
      optional: true,
104
      placeholder: "Describe the task",
105
      max_length: 500
106
    },
107
    {
108
      type: "select",
109
      name: "priority",
110
      label: "Priority",
111
      options: [
112
        { label: "Low", value: "low" },
113
        { label: "Medium", value: "medium" },
114
        { label: "High", value: "high" }
115
      ]
116
    }
117
  ],
118
  submit_label: "Create Task"
119
};
120
```
121

122
### Migration to Modals
123

124
Instead of dialogs, use Block Kit modals:
125

126
```typescript
127
// Modern approach using ModalView
128
import { ModalView, PlainTextInput, SectionBlock } from "@slack/types";
129

130
const modernModal: ModalView = {
131
  type: "modal",
132
  title: {
133
    type: "plain_text",
134
    text: "Task Creation"
135
  },
136
  blocks: [
137
    {
138
      type: "input",
139
      block_id: "task_title",
140
      label: {
141
        type: "plain_text", 
142
        text: "Task Title"
143
      },
144
      element: {
145
        type: "plain_text_input",
146
        action_id: "title_input",
147
        placeholder: {
148
          type: "plain_text",
149
          text: "Enter task title"
150
        },
151
        max_length: 100
152
      }
153
    }
154
    // Add more input blocks as needed
155
  ],
156
  submit: {
157
    type: "plain_text",
158
    text: "Create Task"
159
  }
160
};
161
```
162

163
## Deprecation Timeline
164

165
- **Current Status**: Deprecated but still functional
166
- **Support**: Legacy applications continue to work
167
- **Recommendation**: Migrate to Block Kit modals for new features
168
- **Future**: Will be removed in next major version of @slack/types