Add buttons
Put buttons under any card. A button opens a link, changes the card for everyone the moment someone taps it, or tells your service it was pressed.
What you can do
- Open a linkSend people to a page, a dashboard or a pull request.
- Change the card on a tapEdit it, remove it, react or reply, straight from the press, with no server of your own.
- Hear every pressYour service learns who pressed what, live.
- Run a commandA button can fire one of the community's slash commands, with data.
In the app
Someone rings: the card appears
A tap on Open gate: the card changes for everyone
No server needed for the change itself: the steps are stored with the message. Your gate controller hears the press and opens the gate.
Quick start
Add an actions list
Buttons go in
actions, next to the card, in a webhook post, a command reply or an update.json{ "message_container": { "color": "yellow", "title": "Deploy v2.1 to production?", "description": "Requested by maya." }, "actions": [ { "type": "url:https://ci.example.com/deploys/218", "text": "View changes", "color": "blue" } ] }deploysPick what a press does
A link, a change to the card, or a call to your service. The three kinds are below.
Three kinds of button
The type decides what a press does.
| Type | What a press does | Reaches you |
|---|---|---|
url:{url} | Opens the link. | No |
webhook_action | Runs the steps you stored with it, for everyone in the channel. | Yes, on the message's stream_url |
trigger:{guid} | Fires one of the community's triggers with the button's payload. | Yes, as a new request to that trigger's URL |
Change the card on a tap
A webhook_action button carries a list of steps in triggers. On a press they run on the mssgs server, in order, and everyone in the channel sees the result.
| Step | What it does, for everyone | Fields |
|---|---|---|
update_message | Replaces the card and its buttons. Send "actions": [] to take the buttons away. | message_container, actions, content |
remove_message | Deletes the message. | None |
add_reaction | Adds a reaction, from the member who pressed. | emoji |
add_reply | Posts a reply, from the member who pressed. | content |
{
"message_container": { "color": "yellow", "title": "Front door", "description": "Someone rang the bell." },
"actions": [
{
"type": "webhook_action",
"id": "open_gate",
"text": "Open gate",
"color": "green",
"payload": { "door": "front" },
"triggers": [
{
"action": "update_message",
"message_container": { "color": "blue", "title": "Front door", "description": "Opening…" },
"actions": []
},
{ "action": "add_reaction", "emoji": ":white_check_mark:" }
]
}
]
}Hear the press
A message with buttons comes back from the webhook with a stream_url. Keep it open and every press arrives as an event of type action, with the button's id, the stored button and its payload, and who pressed it:
data: {"type": "action", "message_id": "...", "action_id": "open_gate", "action": {"id": "open_gate", "payload": {"door": "front"}, ...}, "member_guid": "member-guid", "member": {...}, "ts": 1790000000000}Do the real work, like opening the gate, then set the final state of the card through callback_url. How the stream and the callback work is on live updates.
Run a command from a button
A trigger:{guid} button fires one of your community's triggers, as if someone had typed the command, and hands over the button's payload. The trigger receives:
{
"actions": [
{
"type": "trigger:5f2c9a1e-trigger-guid",
"text": "Check status",
"color": "blue",
"payload": { "order_id": "12345" }
}
]
}{
"trigger_match": "/status",
"message": {
"content": "[Action Triggered]",
"member_guid": "member-guid",
"is_action_button": true,
"action_payload": { "order_id": "12345" }
},
"callback_url": "https://mss.gs/api/v1/trigger-callback/...",
"stream_url": "https://mss.gs/api/v1/instant/...?token=..."
}payload.Fields
| Field | Type | What it does |
|---|---|---|
type | string | url:{url}, webhook_action or trigger:{guid}. Required. |
text | string | The label on the button. Required; label works too. |
color | string | The button's colour, see below. |
id | string | For webhook_action: which button was pressed. Unique within the message. |
payload | object | Your data, handed back on a press. |
triggers | array | For webhook_action: the steps to run. |
disabled | boolean | Shows the button greyed out, and presses are refused. |
Colours
green, blue and purple draw a solid, primary button. red, orange and yellow draw a secondary one: use them for "Reject", "Cancel" and other careful choices.
Errors
When you post a message with buttons, mssgs checks them first:
| Code | Meaning |
|---|---|
INVALID_ACTIONS_FORMAT | actions is not a list of objects. |
INVALID_ACTION_MISSING_FIELDS | A button has no type or no text. |
DUPLICATE_ACTION_ID | Two buttons share an id. |
INVALID_TRIGGERS_FORMAT | triggers is not a list of steps. |
INVALID_TRIGGER_MISSING_ACTION | A step has no action. |
INVALID_TRIGGER_ACTION_NOT_ALLOWED | A step other than the four above. |
When someone presses
| Code | Meaning |
|---|---|
MESSAGE_NOT_FOUND | The message was deleted in the meantime. |
ACTION_NOT_FOUND | No button with that id on the message. |
ACTION_DISABLED | The button is disabled. |
TRIGGER_NOT_FOUND, TRIGGER_NOT_ACTIVE | The trigger a button points at is gone or switched off. |
TRIGGER_NOT_ALLOWED | The member does not have a role that may use that trigger. |
Coming from the old docs?
button with ws:send steps, local:update_message and local:remove_message, previous:success conditions and expire_in_seconds no longer work for outside senders. Use webhook_action with the steps above: they reach everyone, not only the person who pressed.