mirror of
https://github.com/hanzoai/team.git
synced 2026-09-30 01:57:35 +00:00
69efa65158
* Preserve 429/503 retry status codes through DoActionRequest DoActionRequest collapsed all plugin non-200 responses to 400, losing the retry semantics carried by 429 and 503 (RFC 6585, RFC 7231). This preserves 429/503 verbatim, maps other 5xx to 502 Bad Gateway, and leaves other non-200 responses wrapped as 400. * update api documentation for new errors * fix tests affected by change --------- Co-authored-by: Mattermost Build <[email protected]> Co-authored-by: Scott Bishel <[email protected]>
346 lines
13 KiB
YAML
346 lines
13 KiB
YAML
/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`, 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.
|
|
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"
|