Добавьте кнопки
Добавляйте кнопки под любую карточку. Кнопка открывает ссылку, меняет карточку для всех в момент нажатия или сообщает вашему сервису, что её нажали.
Что можно сделать
- Откройте ссылкуОтправьте людей на страницу, дашборд или pull request.
- Меняйте карточку по нажатиюОтредактируйте её, удалите, поставьте реакцию или ответьте прямо по нажатию, без собственного сервера.
- Узнавайте о каждом нажатииВаш сервис вживую узнаёт, кто что нажал.
- Запустите командуКнопка может запустить одну из слэш-команд сообщества и передать ей данные.
В приложении
Кто-то звонит: появляется карточка
Нажатие на «Открыть ворота»: карточка меняется для всех
Для самого изменения сервер не нужен: шаги хранятся вместе с сообщением. Ваш контроллер ворот узнаёт о нажатии и открывает ворота.
Быстрый старт
Добавьте список actions
Кнопки передаются в
actions, рядом с карточкой: в публикации через вебхук, в ответе на команду или в обновлении.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" } ] }deploysВыберите, что делает нажатие
Ссылка, изменение карточки или обращение к вашему сервису. Три вида кнопок описаны ниже.
Три вида кнопок
type определяет, что делает нажатие.
| Тип | Что делает нажатие | Доходит ли до вас |
|---|---|---|
url:{url} | Открывает ссылку. | Нет |
webhook_action | Выполняет сохранённые вместе с ней шаги, для всех в канале. | Да, в stream_url сообщения |
trigger:{guid} | Запускает один из триггеров сообщества с payload кнопки. | Да, новым запросом на URL этого триггера |
Изменение карточки по нажатию
Кнопка webhook_action содержит список шагов в triggers. При нажатии они по порядку выполняются на сервере mssgs, и все в канале видят результат.
| Шаг | Что делает, для всех | Поля |
|---|---|---|
update_message | Заменяет карточку и её кнопки. Отправьте "actions": [], чтобы убрать кнопки. | message_container, actions, content |
remove_message | Удаляет сообщение. | Нет |
add_reaction | Добавляет реакцию от имени участника, который нажал. | emoji |
add_reply | Публикует ответ от имени участника, который нажал. | 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:" }
]
}
]
}Как узнать о нажатии
Сообщение с кнопками возвращается от вебхука со stream_url. Держите его открытым, и каждое нажатие придёт событием типа action с id кнопки, сохранённой кнопкой и её payload, а также с тем, кто нажал:
data: {"type": "action", "message_id": "...", "action_id": "open_gate", "action": {"id": "open_gate", "payload": {"door": "front"}, ...}, "member_guid": "member-guid", "member": {...}, "ts": 1790000000000}Выполните настоящую работу, например откройте ворота, а затем задайте итоговое состояние карточки через callback_url. Как работают поток и callback, описано на странице обновлений вживую.
Запуск команды кнопкой
Кнопка trigger:{guid} запускает один из триггеров вашего сообщества, как будто кто-то ввёл команду, и передаёт payload кнопки. Триггер получает:
{
"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.Поля
| Поле | Тип | Что делает |
|---|---|---|
type | string | url:{url}, webhook_action или trigger:{guid}. Обязательно. |
text | string | Надпись на кнопке. Обязательно; label тоже работает. |
color | string | Цвет кнопки, см. ниже. |
id | string | Для webhook_action: какая кнопка нажата. Уникален в пределах сообщения. |
payload | object | Ваши данные, которые возвращаются при нажатии. |
triggers | array | Для webhook_action: шаги, которые нужно выполнить. |
disabled | boolean | Показывает кнопку серой, а нажатия отклоняются. |
Цвета
green, blue и purple рисуют сплошную основную кнопку. red, orange и yellow рисуют второстепенную: используйте их для «Отклонить», «Отмена» и других действий, требующих осторожности.
Ошибки
Когда вы публикуете сообщение с кнопками, mssgs сначала проверяет их:
| Код | Что означает |
|---|---|
INVALID_ACTIONS_FORMAT | actions не является списком объектов. |
INVALID_ACTION_MISSING_FIELDS | У кнопки нет type или text. |
DUPLICATE_ACTION_ID | У двух кнопок одинаковый id. |
INVALID_TRIGGERS_FORMAT | triggers не является списком шагов. |
INVALID_TRIGGER_MISSING_ACTION | У шага нет action. |
INVALID_TRIGGER_ACTION_NOT_ALLOWED | Шаг не входит в четыре перечисленных выше. |
Когда кто-то нажимает
| Код | Что означает |
|---|---|
MESSAGE_NOT_FOUND | Сообщение за это время удалили. |
ACTION_NOT_FOUND | В сообщении нет кнопки с таким id. |
ACTION_DISABLED | Кнопка отключена. |
TRIGGER_NOT_FOUND, TRIGGER_NOT_ACTIVE | Триггер, на который указывает кнопка, удалён или выключен. |
TRIGGER_NOT_ALLOWED | У участника нет роли, которой разрешено использовать этот триггер. |
Переходите со старой документации?
button с шагами ws:send, local:update_message и local:remove_message, условия previous:success и expire_in_seconds больше не работают для внешних отправителей. Используйте webhook_action с шагами, описанными выше: они доходят до всех, а не только до того, кто нажал.