---
title: "Buttons: interactive mssgs messages"
description: "Put buttons under an mssgs card: open a link, change the card for everyone on a tap, hear every press live, or run another command. Fields, steps, events and errors."
canonical: https://mss.gs/en/docs/buttons
language: en
---

# 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 link** Send people to a page, a dashboard or a pull request.

- **Change the card on a tap** Edit it, remove it, react or reply, straight from the press, with no server of your own.

- **Hear every press** Your service learns who pressed what, live.

- **Run a command** A button can fire one of the community's slash commands, with data.

In the app

#### Front door

Someone rings: the card appears

#### Front door

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](#quick-start)

- [Three kinds](#kinds)

- [Change the card](#steps)

- [Hear the press](#listen)

- [Run a command](#trigger)

- [Fields](#fields)

- [Errors](#errors)

## Quick start

### Add an actions list

Buttons go in actions , next to the card, in a [webhook](https://mss.gs/en/docs/webhooks) post, a [command](https://mss.gs/en/docs/commands) reply or an [update](https://mss.gs/en/docs/live-updates).

```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" }
  ]
}
```

#### Deploy v2.1 to production?

- 2 Pick 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 |

```json
{
  "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:

```sse
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](https://mss.gs/en/docs/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:

```json
{
  "actions": [
    {
      "type": "trigger:5f2c9a1e-trigger-guid",
      "text": "Check status",
      "color": "blue",
      "payload": { "order_id": "12345" }
    }
  ]
}
```

```json
{
  "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=..."
}
```

## 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?

## Keep building