You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: site/content/integrate/plugins/interactive-messages/_index.md
+87Lines changed: 87 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -37,6 +37,7 @@ The following payload gives an example that uses message buttons.
37
37
{
38
38
"id": "message",
39
39
"name": "Ephemeral Message",
40
+
"tooltip": "Send a message only visible to you",
40
41
"integration": {
41
42
"url": "http://127.0.0.1:7357",
42
43
"context": {
@@ -46,6 +47,7 @@ The following payload gives an example that uses message buttons.
46
47
}, {
47
48
"id": "update",
48
49
"name": "Update",
50
+
"tooltip": "Update this message",
49
51
"integration": {
50
52
"url": "http://127.0.0.1:7357",
51
53
"context": {
@@ -71,6 +73,18 @@ In the HTTP response for this request, the integration can choose to update the
71
73
}
72
74
```
73
75
76
+
To return a custom error message to the user, your integration can respond with an error object:
77
+
78
+
```json
79
+
{
80
+
"error": {
81
+
"message": "Unable to complete action. Please check your permissions."
82
+
}
83
+
}
84
+
```
85
+
86
+
The error message will be displayed to the user below the message attachment. If no custom error message is provided, a default "Action failed to execute" message is shown. This feature is available in Mattermost v10.5 and later.
87
+
74
88
75
89
76
90
Button actions support a style parameter to change the color of the button. The possible values for style are: `good`, `warning`, `danger`, `default`, `primary`, and `success`. It's also possible to pass a theme variable or a hex color, but we discourage this approach because it won't be resilient against theme changes.
@@ -114,6 +128,51 @@ The actions used in the previous example include the following:
114
128
]
115
129
```
116
130
131
+
### Tooltips on buttons
132
+
133
+
You can add tooltips to provide helpful information when users hover over action buttons:
134
+
135
+
```json
136
+
{
137
+
"attachments": [
138
+
{
139
+
"pretext": "Review this pull request",
140
+
"text": "Pull request #1234: Add new feature",
141
+
"actions": [
142
+
{
143
+
"id": "approve",
144
+
"type": "button",
145
+
"name": "Approve",
146
+
"tooltip": "Click to approve this pull request",
147
+
"style": "primary",
148
+
"integration": {
149
+
"url": "http://127.0.0.1:7357",
150
+
"context": {
151
+
"action": "approve",
152
+
"pr_id": 1234
153
+
}
154
+
}
155
+
},
156
+
{
157
+
"id": "reject",
158
+
"type": "button",
159
+
"name": "Reject",
160
+
"tooltip": "Click to reject this pull request",
161
+
"style": "danger",
162
+
"integration": {
163
+
"url": "http://127.0.0.1:7357",
164
+
"context": {
165
+
"action": "reject",
166
+
"pr_id": 1234
167
+
}
168
+
}
169
+
}
170
+
]
171
+
}
172
+
]
173
+
}
174
+
```
175
+
117
176
## Message menus
118
177
119
178
Similar to buttons, add message menus as `actions` in your integration [message attachments]({{< ref "/integrate/reference/message-attachments" >}}).
@@ -244,6 +303,9 @@ A per post unique identifier.
244
303
**Name**<br/>
245
304
Give your action a descriptive name.
246
305
306
+
**Tooltip** (optional)<br/>
307
+
Display helpful text when users hover over the button. Available in Mattermost v10.5 and later.
308
+
247
309
**URL**<br/>
248
310
The actions are backed by an integration that handles HTTP POST requests when users select the message button. The URL parameter determines where this action is sent. The request contains an `application/json` JSON string. As of 5.14, relative URLs are accepted, simplifying the workflow when a plugin handles the action.
249
311
@@ -336,6 +398,31 @@ In most cases, your integration will do one or both of these things:
336
398
337
399
Then, when the integration receives the request, it can act based on the action ID.
338
400
401
+
## Error handling
402
+
403
+
When an action button integration fails, Mattermost automatically displays an error message to the user below the message attachment. This provides immediate feedback when button actions don't work as expected.
404
+
405
+
406
+
407
+
**Key behaviors:**
408
+
- Integrations can return custom error messages using the error response format (see above)
409
+
- If no custom message is provided, a default "Action failed to execute" message is shown
410
+
- Previous errors are automatically cleared when a new action is triggered
411
+
- Error display works for both button and menu actions
412
+
413
+
This feature is available in Mattermost v10.5 and later.
414
+
415
+
**Automatic error display scenarios:**
416
+
417
+
When your integration returns an error response with a custom message, that message is displayed to the user. For system-level errors where no custom message can be returned, a default error message is shown:
418
+
419
+
- Network connection fails when contacting the integration URL
420
+
- Integration URL is invalid or unreachable
421
+
- Integration returns a non-200 HTTP status code
422
+
- Integration returns invalid JSON
423
+
424
+
For troubleshooting integration errors from the server side, see the FAQ section "Why does an interactive button or menu return a 400 error?" below.
425
+
339
426
## Tips and best practices
340
427
341
428
1. The external application may be written in any programming language. It needs to provide a URL which receives the request sent by your Mattermost server and responds within the required JSON format.
0 commit comments