/api/v4/actions/dialogs/open: post: tags: - integration_actions summary: Open a dialog description: > Open an interactive dialog using a trigger ID provided by a slash command, or some other action payload. See https://docs.mattermost.com/developer/interactive-dialogs.html for more information on interactive dialogs. Up to 3 interactive dialogs may be open at once (minimum server version 11.10). Additional `open_dialog` events beyond this limit are silently ignored by the client. __Minimum server version: 5.6__ operationId: OpenInteractiveDialog requestBody: content: application/json: schema: type: object required: - trigger_id - url - dialog properties: trigger_id: type: string description: Trigger ID provided by other action url: type: string description: The URL to send the submitted dialog payload to dialog: type: object required: - title - elements description: Post object to create properties: callback_id: type: string description: Set an ID that will be included when the dialog is submitted title: type: string description: Title of the dialog introduction_text: type: string description: Markdown formatted introductory paragraph elements: type: array description: > Input elements, see https://docs.mattermost.com/developer/interactive-dialogs.html#elements. Supported element types include `text`, `textarea`, `select`, `radio`, `bool`, `checkbox_group`, `checkbox_matrix`, and `action_button`. An `action_button` element (minimum server version 11.10) renders a clickable button — fields: `name`, `display_name`, `type` set to "action_button", and an `action_button` object with a required `url` (must be a valid lookup URL) and optional `context` (string map). Clicking it calls `POST /api/v4/actions/dialogs/execute`. `action_button` elements are not included in the dialog submission payload. A `checkbox_group` element (minimum server version 11.10) renders a multi-select list of checkboxes. It uses `options` (array of `{text, value}`, up to 50) and an optional `default` of comma-separated option values. It must not set `data_source` or `placeholder`. The submitted value is an array of the selected option values. A `checkbox_matrix` element (minimum server version 11.10) renders a grid of checkboxes. Instead of `options` it uses a `matrix_config` object with `rows` and `columns` (each an array of `{text, value}`; up to 30 rows and 10 columns) and an optional `row_selection` of `"multiple"` (default) or `"single"` (at most one column selectable per row). The optional `default` is a `;`-separated list of `"rowValue:col1,col2"` entries. It must not set `options`, `data_source`, or `placeholder`. The submitted value is an array of the same `"rowValue:col1,col2"` entries. Row and column values must not contain `:`, `,`, or `;`. `checkbox_group`, `radio`, and `bool` elements accept an optional `label_position` of `"before"` or `"after"` (default `"after"`) controlling whether the option label renders before or after its input. items: type: object submit_label: type: string description: Label on the submit button notify_on_cancel: type: boolean description: Set true to receive payloads when user cancels a dialog state: type: string description: Set some state to be echoed back with the dialog submission description: Metadata for the dialog to be opened required: true responses: "200": description: Dialog open successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" /api/v4/actions/dialogs/submit: post: tags: - integration_actions summary: Submit a dialog description: > Endpoint used by the Mattermost clients to submit a dialog. See https://docs.mattermost.com/developer/interactive-dialogs.html for more information on interactive dialogs. __Minimum server version: 5.6__ operationId: SubmitInteractiveDialog requestBody: content: application/json: schema: type: object required: - url - submission - channel_id properties: url: type: string description: The URL to send the submitted dialog payload to channel_id: type: string description: Channel ID the user submitted the dialog from team_id: type: string description: > Optional. The server resolves the authoritative team from the channel, so a client-supplied value is ignored. Empty for DM/GM channels (which have no team). submission: type: object description: String map where keys are element names and values are the element input values callback_id: type: string description: Callback ID sent when the dialog was opened state: type: string description: State sent when the dialog was opened cancelled: type: boolean description: Set to true if the dialog was cancelled file_ids: type: array items: type: string description: > List of file IDs uploaded as part of the dialog submission. Each file must have been uploaded by the submitting user. A maximum of 10 file IDs may be submitted. description: Dialog submission data required: true responses: "200": description: Dialog submission successful content: application/json: schema: $ref: "#/components/schemas/StatusOK" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "429": description: The upstream integration rate-limited the request. The original status code is preserved so clients can honor retry semantics. content: application/json: schema: $ref: "#/components/schemas/AppError" "502": description: The upstream integration returned a 5xx (other than 503). Surfaced as Bad Gateway because the failure is upstream of Mattermost. content: application/json: schema: $ref: "#/components/schemas/AppError" "503": description: The upstream integration is unavailable. The original status code is preserved so clients can honor retry semantics. content: application/json: schema: $ref: "#/components/schemas/AppError" /api/v4/actions/dialogs/lookup: post: tags: - integration_actions summary: Lookup dialog elements description: > Endpoint used by the Mattermost clients to lookup dynamic dialog elements. See https://docs.mattermost.com/developer/interactive-dialogs.html for more information on interactive dialogs. __Minimum server version: 11.0__ operationId: LookupInteractiveDialog requestBody: content: application/json: schema: type: object required: - url - submission - channel_id properties: url: type: string description: The URL to send the lookup request to channel_id: type: string description: Channel ID the user is performing the lookup from team_id: type: string description: > Optional. The server resolves the authoritative team from the channel, so a client-supplied value is ignored. Empty for DM/GM channels (which have no team). submission: type: object description: String map where keys are element names and values are the element input values callback_id: type: string description: Callback ID sent when the dialog was opened state: type: string description: State sent when the dialog was opened description: Dialog lookup request data required: true responses: "200": description: Dialog lookup successful content: application/json: schema: type: object properties: options: type: array description: List of options returned from the lookup items: type: object properties: text: type: string description: Display text for the option value: type: string description: Value for the option "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "429": description: The upstream integration rate-limited the request. The original status code is preserved so clients can honor retry semantics. content: application/json: schema: $ref: "#/components/schemas/AppError" "502": description: The upstream integration returned a 5xx (other than 503). Surfaced as Bad Gateway because the failure is upstream of Mattermost. content: application/json: schema: $ref: "#/components/schemas/AppError" "503": description: The upstream integration is unavailable. The original status code is preserved so clients can honor retry semantics. content: application/json: schema: $ref: "#/components/schemas/AppError" /api/v4/actions/dialogs/execute: post: tags: - integration_actions summary: Execute a dialog action button description: > Endpoint used by the Mattermost clients when a user clicks an `action_button` element inside an interactive dialog. The server generates a new trigger ID and forwards the button's context to the integration URL; the integration can then open a child (stacked) dialog with that trigger ID. See https://docs.mattermost.com/developer/interactive-dialogs.html for more information on interactive dialogs. This request is always processed server-side. The client caps the number of simultaneously open interactive dialogs at 3, so if the resulting `open_dialog` event would exceed that limit the client silently skips rendering the additional dialog. __Minimum server version: 11.10__ operationId: ExecuteDialogAction requestBody: content: application/json: schema: type: object required: - url - channel_id properties: url: type: string description: The action button URL to send the action payload to. Must be a valid lookup URL. context: type: object description: String map of context values configured on the action button, forwarded to the integration channel_id: type: string description: Channel ID the user clicked the action button from team_id: type: string description: > Optional. The server resolves the authoritative team from the channel, so a client-supplied value is ignored. Empty for DM/GM channels (which have no team). description: Dialog action button execution data required: true responses: "200": description: Dialog action executed successfully content: application/json: schema: type: object properties: status: type: string description: Status of the request ("OK") trigger_id: type: string description: New trigger ID the integration can use to open a child dialog "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden"