Adicione botões
Coloque botões embaixo de qualquer cartão. Um botão abre um link, muda o cartão para todos no instante em que alguém toca nele ou avisa o seu serviço que foi tocado.
O que você pode fazer
- Abra um linkMande as pessoas para uma página, um dashboard ou um pull request.
- Mude o cartão com um toqueEdite, remova, reaja ou responda direto do toque, sem servidor próprio.
- Receba cada toqueO seu serviço fica sabendo ao vivo quem tocou em quê.
- Rode um comandoUm botão pode disparar um dos comandos de barra da comunidade, com dados.
No app
Alguém toca a campainha: o cartão aparece
Um toque em Abrir portão: o cartão muda para todos
A mudança em si não precisa de servidor: as etapas ficam guardadas com a mensagem. O controlador do seu portão recebe o toque e abre o portão.
Início rápido
Adicione uma lista actions
Os botões vão em
actions, ao lado do cartão, numa publicação por webhook, numa resposta a comando ou numa atualização.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" } ] }deploysEscolha o que um toque faz
Um link, uma mudança no cartão ou uma chamada ao seu serviço. Os três tipos estão abaixo.
Três tipos de botão
O type decide o que um toque faz.
| Tipo | O que um toque faz | Chega até você |
|---|---|---|
url:{url} | Abre o link. | Não |
webhook_action | Executa as etapas que você guardou com ele, para todos no canal. | Sim, na stream_url da mensagem |
trigger:{guid} | Dispara um dos triggers da comunidade com o payload do botão. | Sim, como uma nova requisição para a URL desse trigger |
Mudar o cartão com um toque
Um botão webhook_action leva uma lista de etapas em triggers. Com um toque, elas rodam no servidor do mssgs, em ordem, e todos no canal veem o resultado.
| Etapa | O que faz, para todos | Campos |
|---|---|---|
update_message | Substitui o cartão e os botões dele. Envie "actions": [] para tirar os botões. | message_container, actions, content |
remove_message | Apaga a mensagem. | Nenhum |
add_reaction | Adiciona uma reação, em nome do membro que tocou. | emoji |
add_reply | Publica uma resposta, em nome do membro que tocou. | 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:" }
]
}
]
}Receber o toque
Uma mensagem com botões volta do webhook com uma stream_url. Mantenha-a aberta e cada toque chega como um evento do tipo action, com o id do botão, o botão guardado e o payload dele, e quem tocou:
data: {"type": "action", "message_id": "...", "action_id": "open_gate", "action": {"id": "open_gate", "payload": {"door": "front"}, ...}, "member_guid": "member-guid", "member": {...}, "ts": 1790000000000}Faça o trabalho de verdade, como abrir o portão, e depois defina o estado final do cartão pela callback_url. Como o stream e o callback funcionam está em atualizações ao vivo.
Rodar um comando a partir de um botão
Um botão trigger:{guid} dispara um dos triggers da sua comunidade, como se alguém tivesse digitado o comando, e repassa o payload do botão. O trigger recebe:
{
"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.Campos
| Campo | Tipo | O que faz |
|---|---|---|
type | string | url:{url}, webhook_action ou trigger:{guid}. Obrigatório. |
text | string | O rótulo do botão. Obrigatório; label também funciona. |
color | string | A cor do botão, veja abaixo. |
id | string | Para webhook_action: qual botão foi tocado. Único dentro da mensagem. |
payload | object | Os seus dados, devolvidos num toque. |
triggers | array | Para webhook_action: as etapas a executar. |
disabled | boolean | Mostra o botão acinzentado, e os toques são recusados. |
Cores
green, blue e purple desenham um botão principal, preenchido. red, orange e yellow desenham um secundário: use-os para “Rejeitar”, “Cancelar” e outras escolhas que pedem cuidado.
Erros
Quando você publica uma mensagem com botões, o mssgs os verifica primeiro:
| Código | Significado |
|---|---|
INVALID_ACTIONS_FORMAT | actions não é uma lista de objetos. |
INVALID_ACTION_MISSING_FIELDS | Um botão não tem type ou não tem text. |
DUPLICATE_ACTION_ID | Dois botões têm o mesmo id. |
INVALID_TRIGGERS_FORMAT | triggers não é uma lista de etapas. |
INVALID_TRIGGER_MISSING_ACTION | Uma etapa não tem action. |
INVALID_TRIGGER_ACTION_NOT_ALLOWED | Uma etapa diferente das quatro acima. |
Quando alguém toca
| Código | Significado |
|---|---|
MESSAGE_NOT_FOUND | A mensagem foi apagada nesse meio-tempo. |
ACTION_NOT_FOUND | Não há botão com esse id na mensagem. |
ACTION_DISABLED | O botão está desativado. |
TRIGGER_NOT_FOUND, TRIGGER_NOT_ACTIVE | O trigger para o qual o botão aponta não existe mais ou está desligado. |
TRIGGER_NOT_ALLOWED | O membro não tem um cargo que possa usar esse trigger. |
Vindo da documentação antiga?
button com etapas ws:send, local:update_message e local:remove_message, condições previous:success e expire_in_seconds não funcionam mais para remetentes externos. Use webhook_action com as etapas acima: elas chegam a todos, não só a quem tocou.