snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

api/v4/source/actions.yaml

@@ -0,0 +1,374 @@
+  /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"