Skip to content

Document datetime_config nested property for interactive dialog fields #1502

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sbishel merged 10 commits into from
May 1, 2026
Merged

Document datetime_config nested property for interactive dialog fields #1502

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
b5ca58e
Document datetime_config nested property for interactive dialog fields
sbishel Apr 20, 2026
8baad30
Merge branch 'master' into update-datetime-config
sbishel Apr 21, 2026
094e3f6
Rename allow_manual_time_entry to manual_time_entry in datetime_confi…
sbishel Apr 21, 2026
9de18dd
Merge branch 'master' into update-datetime-config
sbishel Apr 21, 2026
3ad3f28
Add missing commas in compound sentences for date field descriptions
sbishel Apr 21, 2026
e0d1acf
Merge branch 'master' into update-datetime-config
sbishel Apr 21, 2026
0ad4749
Merge branch 'master' into update-datetime-config
sbishel Apr 23, 2026
64449cf
Merge branch 'master' into update-datetime-config
sbishel Apr 30, 2026
0167eab
Merge branch 'master' into update-datetime-config
sbishel May 1, 2026
d958fea
Merge branch 'master' into update-datetime-config
sbishel May 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 97 additions & 48 deletions site/content/integrate/plugins/interactive-dialogs/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -423,24 +423,27 @@ Date elements provide native date picker functionality for selecting dates witho
"placeholder": "Select a date",
"help_text": "Choose the date for your event",
"optional": false,
"min_date": "today",
"max_date": "+30d"
"datetime_config": {
"min_date": "today",
"max_date": "+30d"
}
}
```

The full list of supported fields for `date` elements is included below:

| Field | Type | Description |
|----------------|---------|------------------------------------------------------------------------------------------------------------------------------------|
| `display_name` | String | Display name of the field shown to the user in the dialog. Maximum 24 characters. |
| `name` | String | Name of the field element used by the integration. Maximum 300 characters. You should use unique `name` fields in the same dialog. |
| `type` | String | Set this value to `date` for a date element. |
| `default` | String | (Optional) Default value in ISO date format (YYYY-MM-DD) or relative format (`today`, `tomorrow`, `+1d`, `+1w`, `+1M`, `+1y`). Full ISO datetime strings are accepted but only the date part is parsed; timezone information is ignored. |
| `placeholder` | String | (Optional) Placeholder text shown in the input field. Maximum 150 characters. |
| `help_text` | String | (Optional) Help text displayed below the field. Maximum 150 characters. |
| `optional` | Boolean | (Optional) Set to `true` if this form element is not required. Default is `false`. |
| `min_date` | String | (Optional) Earliest selectable date. Supports ISO date format (YYYY-MM-DD) or relative formats (`today`, `tomorrow`, `+1d`, `-7d`, etc.). Full ISO datetime strings are accepted but only the date part is parsed; timezone information is ignored. |
| `max_date` | String | (Optional) Latest selectable date. Supports ISO date format (YYYY-MM-DD) or relative formats (`today`, `+30d`, `+1y`, etc.). Full ISO datetime strings are accepted but only the date part is parsed; timezone information is ignored. |
| Field | Type | Description |
|-------------------|---------|------------------------------------------------------------------------------------------------------------------------------------|
| `display_name` | String | Display name of the field shown to the user in the dialog. Maximum 24 characters. |
| `name` | String | Name of the field element used by the integration. Maximum 300 characters. You should use unique `name` fields in the same dialog. |
| `type` | String | Set this value to `date` for a date element. |
| `default` | String | (Optional) Default value in ISO date format (YYYY-MM-DD) or relative format (`today`, `tomorrow`, `+1d`, `+1w`, `+1M`, `+1y`). Full ISO datetime strings are accepted, but only the date part is parsed; timezone information is ignored. |
| `placeholder` | String | (Optional) Placeholder text shown in the input field. Maximum 150 characters. |
| `help_text` | String | (Optional) Help text displayed below the field. Maximum 150 characters. |
| `optional` | Boolean | (Optional) Set to `true` if this form element is not required. Default is `false`. |
| `datetime_config` | Object | (Optional) Nested date configuration object. See [datetime_config object](#datetime_config-object) for supported properties. |
| `min_date` | String | (Deprecated — use `datetime_config.min_date`.) Earliest selectable date. Supports ISO date format (YYYY-MM-DD) or relative formats (`today`, `tomorrow`, `+1d`, `-7d`, etc.). Full ISO datetime strings are accepted, but only the date part is parsed; timezone information is ignored. |
| `max_date` | String | (Deprecated — use `datetime_config.max_date`.) Latest selectable date. Supports ISO date format (YYYY-MM-DD) or relative formats (`today`, `+30d`, `+1y`, etc.). Full ISO datetime strings are accepted, but only the date part is parsed; timezone information is ignored. |

#### Date field usage examples

Expand All @@ -451,7 +454,9 @@ The full list of supported fields for `date` elements is included below:
"name": "deadline",
"type": "date",
"help_text": "When is this project due?",
"min_date": "today",
"datetime_config": {
"min_date": "today"
},
"optional": false
}
```
Expand All @@ -463,8 +468,10 @@ The full list of supported fields for `date` elements is included below:
"name": "any_date",
"type": "date",
"help_text": "Any date within the next year",
"min_date": "today",
"max_date": "+1y",
"datetime_config": {
"min_date": "today",
"max_date": "+1y"
},
"default": "+1w",
"optional": true
}
Expand All @@ -486,26 +493,29 @@ DateTime elements provide combined date and time picker functionality with timez
"placeholder": "Select date and time",
"help_text": "Choose when the meeting should start",
"optional": false,
"time_interval": 30,
"min_date": "today",
"max_date": "+7d"
"datetime_config": {
"min_date": "today",
"max_date": "+7d",
"time_interval": 30
}
}
```

The full list of supported fields for `datetime` elements is included below:

| Field | Type | Description |
|-----------------|---------|------------------------------------------------------------------------------------------------------------------------------------|
| `display_name` | String | Display name of the field shown to the user in the dialog. Maximum 24 characters. |
| `name` | String | Name of the field element used by the integration. Maximum 300 characters. You should use unique `name` fields in the same dialog. |
| `type` | String | Set this value to `datetime` for a datetime element. |
| `default` | String | (Optional) Default value in ISO datetime format (RFC3339) or relative format. For relative dates, time defaults to noon. When specifying a time, it must align with the `time_interval` (be a multiple of the interval). |
| `placeholder` | String | (Optional) Placeholder text shown in the input field. Maximum 150 characters. |
| `help_text` | String | (Optional) Help text displayed below the field. Maximum 150 characters. |
| `optional` | Boolean | (Optional) Set to `true` if this form element is not required. Default is `false`. |
| `min_date` | String | (Optional) Earliest selectable date. Supports ISO format or relative formats (`today`, `tomorrow`, `+1d`, `-7d`, etc.). |
| `max_date` | String | (Optional) Latest selectable date. Supports ISO format or relative formats (`today`, `+30d`, `+1y`, etc.). |
| `time_interval` | Integer | (Optional) Time selection interval in minutes. Must be between 1 and 1440, and must be a divisor of 1440 to create evenly spaced intervals throughout the day. Common values: 15, 30, 60, 90, 120. Default is 60. |
| Field | Type | Description |
|-------------------|---------|------------------------------------------------------------------------------------------------------------------------------------|
| `display_name` | String | Display name of the field shown to the user in the dialog. Maximum 24 characters. |
| `name` | String | Name of the field element used by the integration. Maximum 300 characters. You should use unique `name` fields in the same dialog. |
| `type` | String | Set this value to `datetime` for a datetime element. |
| `default` | String | (Optional) Default value in ISO datetime format (RFC3339) or relative format. For relative dates, time defaults to noon. When specifying a time, it must align with `datetime_config.time_interval` (be a multiple of the interval). |
| `placeholder` | String | (Optional) Placeholder text shown in the input field. Maximum 150 characters. |
| `help_text` | String | (Optional) Help text displayed below the field. Maximum 150 characters. |
| `optional` | Boolean | (Optional) Set to `true` if this form element is not required. Default is `false`. |
| `datetime_config` | Object | (Optional) Nested datetime configuration object. See [datetime_config object](#datetime_config-object) for supported properties. |
| `min_date` | String | (Deprecated — use `datetime_config.min_date`.) Earliest selectable date. Supports ISO format or relative formats (`today`, `tomorrow`, `+1d`, `-7d`, etc.). |
| `max_date` | String | (Deprecated — use `datetime_config.max_date`.) Latest selectable date. Supports ISO format or relative formats (`today`, `+30d`, `+1y`, etc.). |
| `time_interval` | Integer | (Deprecated — use `datetime_config.time_interval`.) Time selection interval in minutes. Must be between 1 and 1440, and must be a divisor of 1440 to create evenly spaced intervals throughout the day. Common values: 15, 30, 60, 90, 120. Default is 60. |

#### DateTime field usage examples

Expand All @@ -516,9 +526,11 @@ The full list of supported fields for `datetime` elements is included below:
"name": "meeting_time",
"type": "datetime",
"help_text": "Select a time during business hours",
"time_interval": 30,
"min_date": "+1d",
"max_date": "+14d",
"datetime_config": {
"min_date": "+1d",
"max_date": "+14d",
"time_interval": 30
},
"optional": false
}
```
Expand All @@ -530,13 +542,46 @@ The full list of supported fields for `datetime` elements is included below:
"name": "event_start",
"type": "datetime",
"help_text": "When does your event begin?",
"time_interval": 15,
"min_date": "today",
"max_date": "+90d",
"datetime_config": {
"min_date": "today",
"max_date": "+90d",
"time_interval": 15
},
"default": "today"
}
```

**Fixed location timezone with manual entry:**
```json
{
"display_name": "Conference Start",
"name": "conference_start",
"type": "datetime",
"help_text": "All attendees see this time in the conference timezone",
"datetime_config": {
"location_timezone": "America/Denver",
"manual_time_entry": true,
"time_interval": 30
}
}
```

#### datetime_config object
##### Minimum Server Version: 11.6

The `datetime_config` object groups date/datetime configuration into a single nested structure. It is supported on both `date` and `datetime` elements.

| Field | Type | Applies to | Since | Description |
|---------------------------|---------|--------------------|--------|-----------------------------------------------------------------------------------------------------------------------------|
| `min_date` | String | `date`, `datetime` | 11.8 | (Optional) Earliest selectable date. Supports ISO format or relative formats (`today`, `+1d`, etc.). |
| `max_date` | String | `date`, `datetime` | 11.8 | (Optional) Latest selectable date. Supports ISO format or relative formats (`+30d`, `+1y`, etc.). |
| `time_interval` | Integer | `datetime` | 11.6 | (Optional) Time selection interval in minutes. Must be between 1 and 1440, and must be a divisor of 1440. Default is 60. |
| `location_timezone` | String | `datetime` | 11.6 | (Optional) IANA timezone used to display and submit the time (e.g. `America/Denver`, `Asia/Tokyo`). When set, all users see the same wall-clock time regardless of their own timezone. Defaults to the viewing user's timezone. |
| `manual_time_entry` | Boolean | `datetime` | 11.8 | (Optional) When `true`, users can type the time directly in addition to using the dropdown. Default is `false`. |
| `allow_manual_time_entry` | Boolean | `datetime` | 11.6 (deprecated in 11.8) | (Deprecated — use `manual_time_entry`.) When both are set, either enabling turns the feature on. |

**Backward compatibility (new in 11.8):** The top-level `min_date`, `max_date`, and `time_interval` fields on `date` and `datetime` elements are still accepted for existing integrations, but are deprecated in favor of `datetime_config`. When both are provided on the same element, values inside `datetime_config` take precedence over the legacy top-level values.

Comment thread
sbishel marked this conversation as resolved.
#### Date and DateTime field specifications

**Relative Date Formats:**
Expand Down Expand Up @@ -566,15 +611,15 @@ The full list of supported fields for `datetime` elements is included below:
**Validation:**
- Client validates date formats and range constraints
- Server validates relative date resolution and field configuration
- For datetime fields, `time_interval` must be a divisor of 1440 (24 hours in minutes)
- Default times must align with the specified `time_interval` (be a multiple of the interval)
- For datetime fields, `datetime_config.time_interval` must be a divisor of 1440 (24 hours in minutes)
- Default times must align with the effective `time_interval` (be a multiple of the interval)
- Invalid dates, times, or out-of-range selections show appropriate error messages

**Time Interval Examples:**
- `time_interval: 15` creates options: 00:00, 00:15, 00:30, 00:45, 01:00, etc.
- `time_interval: 30` creates options: 00:00, 00:30, 01:00, 01:30, etc.
- `time_interval: 60` creates options: 00:00, 01:00, 02:00, 03:00, etc.
- Invalid: `time_interval: 7` (7 is not a divisor of 1440)
- `"time_interval": 15` creates options: 00:00, 00:15, 00:30, 00:45, 01:00, etc.
- `"time_interval": 30` creates options: 00:00, 00:30, 01:00, 01:30, etc.
- `"time_interval": 60` creates options: 00:00, 01:00, 02:00, 03:00, etc.
- Invalid: `"time_interval": 7` (7 is not a divisor of 1440)

## Dialog submission

Expand Down Expand Up @@ -999,8 +1044,10 @@ Below is a full example of a JSON payload that creates an interactive dialog in
"default":"today",
"placeholder":"Select event date",
"help_text":"Choose when your event takes place",
"min_date":"today",
"max_date":"+30d",
"datetime_config":{
"min_date":"today",
"max_date":"+30d"
},
"optional":false
},
{
Expand All @@ -1010,9 +1057,11 @@ Below is a full example of a JSON payload that creates an interactive dialog in
"default":"",
"placeholder":"Select meeting date and time",
"help_text":"Schedule your meeting with date and time",
"time_interval":30,
"min_date":"today",
"max_date":"+14d",
"datetime_config":{
"min_date":"today",
"max_date":"+14d",
"time_interval":30
},
"optional":true
}
],
Expand Down
Loading