Navrhni karty správ
Všetko, čo bot pošle, či už cez webhook, ako odpoveď na príkaz alebo pri aktualizácii po stlačení tlačidla, je karta. Dobrá karta na prvý pohľad povie, čo sa stalo: farebný okraj, nadpis, stav a pod tým podrobnosti.
Čo s tým môžeš robiť
- Ukáž stavFarebný štítok ako Open, Merged alebo Passing, s počtom pridaných a odobratých riadkov.
- Vypíš podrobnostiRiadky s popisom a hodnotou, ktoré členovia skopírujú jedným ťuknutím.
- Píš v markdowneTučné písmo, inline kód, bloky kódu, citácie a zaškrtávacie políčka.
- Ukáž, že pracuješSpinner, kým bot premýšľa, a potom jeho uvažovanie skryté za prepínačom.
V aplikácii
Štyri karty tak, ako ich vidia členovia. Každá je len pár riadkov JSON.
Anatómia karty
Časti karty zhora nadol. Čo nepotrebuješ, vynechaj: aj karta iba s nadpisom je v poriadku.
- Hlavička„Message from“ a meno: názov webhooku alebo pri odpovedi na príkaz názov tvojej komunity. Odpoveď môže pridať
badge, napríklad repozitár. - Nadpis a stav
title, ktorý sa stane odkazom, keď nastavíštitle_url, a vedľa neho štítokstatus. - PodnadpisDruhý tučný riadok,
sub_title. - PopisTelo správy v markdowne.
- PoliaRiadky s popisom a hodnotou, s tlačidlom na kopírovanie.
- PätaČas a pridané a odobraté riadky, ak ich pošleš.
{
"message_container": {
"type": "embed_message",
"badge": "acme/web",
"color": "purple",
"title": "Pull request #212 opened",
"title_url": "https://github.com/acme/web/pull/212",
"status": { "label": "Open", "color": "green", "icon": "pull_request" },
"sub_title": "Faster search in the channel list",
"description": "Search now runs **per keystroke** with a 120 ms debounce.",
"fields": [
{ "field": "Author", "value": "maya" },
{ "field": "Reviewers", "value": "dani, sam" }
],
"additions": 86,
"deletions": 12,
"files_changed": 3
}
}Všetky polia
Tieto polia patria do message_container. Karta potrebuje popis alebo loader. Polia označené „Odpovede na príkazy“ sa pri posielaní cez webhook zahodia.
| Pole | Typ | Čo robí |
|---|---|---|
type | string | embed_message (predvolené) alebo system_message. |
badge | string | Malý štítok za menom v hlavičke, napríklad acme/web. Odpovede na príkazy |
avatar_url | string | Obrázok cez ikonu karty. |
color | string | Farba okraja. Pozri farby nižšie. |
title | string | Tučný prvý riadok. |
title_url | string | Z nadpisu urobí odkaz. |
sub_title | string | Druhý tučný riadok pod nadpisom. |
description | string | Telo správy v markdowne. |
fields | array | [{ "field": "…", "value": "…" }]: riadky s popisom a hodnotou. |
image_url, image_base64 | string | Obrázok na karte. |
images | array | [{ "image_url": "…" }]: galéria viacerých obrázkov. |
status | object alebo string | Farebný štítok vedľa nadpisu. Pozri nižšie. Odpovede na príkazy |
additions, deletions, files_changed | number | Štatistiky diffu v päte. Odpovede na príkazy |
loader, loader_text, loader_sub_text | boolean, string | Spinner namiesto tela správy. |
thinking | string | Uvažovanie skryté za prepínačom Show thinking. Odpovede na príkazy |
thinking rozumejú markdownu: **bold**, _italic_, ~~strike~~, `inline code`, bloky kódu ohraničené trojitými backtickmi, > quotes, zaškrtávacie políčka - [x], @zmienky a :emoji:.Stav a štatistiky diffu
Stavový štítok povie, o čo ide, skôr než si niekto prečíta text. Je vedľa nadpisu, a keď nadpis chýba, v päte; štatistiky diffu sa zobrazia vedľa času. Oboje funguje v odpovediach na príkazy a používa ich aj vstavaná integrácia s GitHubom. Webhook ich zahodí.
{
"message_container": {
"color": "red",
"title": "Build failed on main",
"status": { "label": "Failing", "color": "red" },
"description": "`search.test.js`: 2 of 212 tests failed."
}
}| Pole | Typ | Čo robí |
|---|---|---|
status | object alebo string | Samotný string je popis štítka: "status": "Open". |
status.label | string | Text štítka. Bez neho sa štítok nezobrazí. |
status.color | string | green, purple, red, orange, yellow, blue alebo gray. |
status.icon | string | Voliteľná ikona zo zoznamu nižšie. |
additions | number | Pridané riadky, zobrazené zelenou ako +86. |
deletions | number | Odobraté riadky, zobrazené červenou ako -12. |
files_changed | number | Zmenené súbory, zobrazené ako 3 files. |
Ikony
| Hodnota | Ikona | Typické použitie |
|---|---|---|
pull_request | git-pull-request | Otvorený pull request |
pull_request_closed | git-pull-request-closed | Zatvorený bez zlúčenia |
merge, merged | git-merge | Zlúčený |
commit | git-commit | Pushnutý commit |
issue | circle-dot | Otvorené issue |
issue_closed | circle-check | Zatvorené issue |
check | circle-check | Testy prešli, úloha uspela |
Mapovanie, ktoré sa osvedčilo pre GitHub
Vstavaná integrácia s GitHubom používa tieto hodnoty; skopíruj si ich do vlastných nástrojov.
| Udalosť | Štítok | Farba | Ikona |
|---|---|---|---|
| Otvorený pull request | Open | green | pull_request |
| Koncept | Draft | gray | pull_request |
| Zlúčený | Merged | purple | merged |
| Zatvorený bez zlúčenia | Closed | red | pull_request_closed |
| Otvorené issue | Open | green | issue |
| Zatvorené issue | Closed | purple | issue_closed |
| Pushnutý commit | Commit | gray | commit |
| Testy prešli | Passing | green | check |
| Testy zlyhali | Failing | red | žiadna |
Loader a uvažovanie
Pri všetkom, čo chvíľu trvá, napríklad pri odpovedi AI alebo dlhej úlohe, najprv pošli kartu so spinnerom a potom ju nahraď výsledkom. Loader funguje vo webhookoch aj v odpovediach na príkazy. V odpovedi na príkaz môžeš do thinking vložiť aj uvažovanie modelu: členovia namiesto steny textu uvidia prepínač Show thinking.
Najprv: loader
Potom: odpoveď so zbaleným uvažovaním
{
"message_container": {
"type": "embed_message",
"color": "blue",
"loader": true,
"loader_text": "Thinking…",
"loader_sub_text": "Reading the last 50 messages"
}
}{
"message_container": {
"type": "embed_message",
"color": "blue",
"sub_title": "maya: when is the standup?",
"description": "Standup is at **09:30**, in #daily.",
"thinking": "Checked the pinned messages and the recurring event in #daily…"
}
}| Pole | Typ | Čo robí |
|---|---|---|
loader | boolean | true zobrazí spinner namiesto tela správy. |
loader_text | string | Riadok vedľa spinnera, napríklad „Premýšľam…“. |
loader_sub_text | string | Menší riadok pod ním. |
thinking | string | Zbalené uvažovanie pod popisom, v markdowne. |
Ak chceš loader vymeniť za odpoveď, aktualizuj správu novou kartou bez loader. Ako na to, nájdeš na stránke živé aktualizácie.
Dlhé popisy
Popis môže mať až 50 000 bajtov. Po prvých 1 000 členovia uvidia začiatok a tlačidlo Show more, ktoré načíta zvyšok, takže dlhý report nezahltí kanál.
Systémové správy
Nastav "type": "system_message", keď chceš oznámenie namiesto príspevku bota: plánovanú údržbu, zmeny pravidiel, čokoľvek, čo hovorí za samotnú komunitu. Prijíma rovnaké polia a tlačidlá.
{
"message_container": {
"type": "system_message",
"color": "orange",
"title": "Maintenance tonight",
"description": "The build servers are down from 22:00 to 23:00."
}
}Farby
Farba okraja je najrýchlejší signál na karte. Pre rovnaký druh správ používaj vždy rovnakú farbu.
| Farba | Použi ju na |
|---|---|
green | Úspech: prešlo, nasadené, hotovo |
red | Zlyhanie: chyba, výpadok, zamietnuté |
orange | Varovanie, na ktoré treba pozrieť |
yellow | Čaká sa na niekoho: schválenia, otázky |
blue | Informácia, predvolená |
purple | Udalosti v kóde alebo niečo výnimočné |
Vytvor si svoj embed
Uprav polia alebo JSON payload: oboje zostáva zosynchronizované. Náhľad ukazuje správu presne tak, ako sa zobrazí v kanáli. Toto je skutočné telo webhooku; skopíruj si ho, keď bude všetko sedieť.