Navrhni karty zpráv
Všechno, co bot zveřejní, ať přes webhook, v odpovědi na příkaz, nebo v aktualizaci po stisku tlačítka, je karta. Dobrá karta na první pohled řekne, co se stalo: barevný okraj, nadpis, stav a pod tím podrobnosti.
Co s tím můžeš dělat
- Ukaž stavBarevný štítek jako Open, Merged nebo Passing, s přidanými a odebranými řádky.
- Vypiš podrobnostiŘádky s popiskem a hodnotou, které členové zkopírují jedním klepnutím.
- Piš v markdownuTučné písmo, inline kód, bloky kódu, citace a zaškrtávací políčka.
- Ukaž, že pracuješSpinner, zatímco bot přemýšlí, a potom jeho uvažování schované za přepínačem.
V aplikaci
Čtyři karty tak, jak je vidí členové. Každá je pár řádků JSONu.
Stavba karty
Části karty, shora dolů. Co nepotřebuješ, vynech: i karta jen s nadpisem je v pořádku.
- Záhlaví„Message from“ a jméno: jméno webhooku, nebo u odpovědi na příkaz jméno tvé komunity. Odpověď může přidat
badge, třeba repozitář. - Nadpis a stav
title, který se stane odkazem, když nastavíštitle_url, a vedle něj štítekstatus. - PodnadpisDruhý tučný řádek,
sub_title. - PopisTělo karty, v markdownu.
- PoleŘádky s popiskem a hodnotou a s tlačítkem pro kopírování.
- PatičkaČas a přidané a odebrané řádky, pokud je 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šechna pole
Tato pole patří do message_container. Karta potřebuje popis, nebo loader. Pole označená „Odpovědi na příkazy“ se zahodí, když posíláš přes webhook.
| Pole | Typ | Co dělá |
|---|---|---|
type | string | embed_message (výchozí) nebo system_message. |
badge | string | Malý štítek za jménem v záhlaví, třeba acme/web. Odpovědi na příkazy |
avatar_url | string | Obrázek přes ikonu karty. |
color | string | Barva okraje. Viz barvy níže. |
title | string | Tučný první řádek. |
title_url | string | Udělá z nadpisu odkaz. |
sub_title | string | Druhý tučný řádek pod nadpisem. |
description | string | Tělo karty, v markdownu. |
fields | array | [{ "field": "…", "value": "…" }]: řádky s popiskem a hodnotou. |
image_url, image_base64 | string | Obrázek na kartě. |
images | array | [{ "image_url": "…" }]: galerie několika obrázků. |
status | object nebo string | Barevný štítek vedle nadpisu. Viz níže. Odpovědi na příkazy |
additions, deletions, files_changed | number | Statistiky diffu v patičce. Odpovědi na příkazy |
loader, loader_text, loader_sub_text | boolean, string | Spinner místo těla karty. |
thinking | string | Uvažování schované za přepínačem Show thinking. Odpovědi na příkazy |
thinking rozumí markdownu: **bold**, _italic_, ~~strike~~, `inline code`, bloky kódu ve trojitých backtickách, > quotes, zaškrtávací políčka - [x], @zmínky a :emoji:.Stav a statistiky diffu
Štítek stavu řekne, o co jde, dřív, než si kdokoli přečte text. Je vedle nadpisu, nebo v patičce, když nadpis chybí; statistiky diffu se ukážou vedle času. Obojí funguje v odpovědích na příkazy a používá to vestavěná integrace s GitHubem. Webhook je 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 | Co dělá |
|---|---|---|
status | object nebo string | Samotný string je popisek: "status": "Open". |
status.label | string | Text štítku. Bez něj žádný štítek není. |
status.color | string | green, purple, red, orange, yellow, blue nebo gray. |
status.icon | string | Volitelná ikona ze seznamu níže. |
additions | number | Přidané řádky, zobrazené zeleně jako +86. |
deletions | number | Odebrané řádky, zobrazené červeně jako -12. |
files_changed | number | Změněné soubory, zobrazené jako 3 files. |
Ikony
| Hodnota | Ikona | Typické použití |
|---|---|---|
pull_request | git-pull-request | Otevřený pull request |
pull_request_closed | git-pull-request-closed | Zavřený bez sloučení |
merge, merged | git-merge | Sloučeno |
commit | git-commit | Pushnutý commit |
issue | circle-dot | Otevřené issue |
issue_closed | circle-check | Zavřené issue |
check | circle-check | Testy prošly, úloha uspěla |
Mapování, které funguje pro GitHub
Vestavěná integrace s GitHubem používá tyto hodnoty; zkopíruj si je pro vlastní nástroje.
| Událost | Popisek | Barva | Ikona |
|---|---|---|---|
| Otevřený pull request | Open | green | pull_request |
| Koncept | Draft | gray | pull_request |
| Sloučený | Merged | purple | merged |
| Zavřený bez sloučení | Closed | red | pull_request_closed |
| Otevřené issue | Open | green | issue |
| Zavřené issue | Closed | purple | issue_closed |
| Pushnutý commit | Commit | gray | commit |
| Testy prošly | Passing | green | check |
| Testy selhaly | Failing | red | žádná |
Loader a uvažování
U všeho, co chvíli trvá, třeba u odpovědi AI nebo dlouhé úlohy, nejdřív zveřejni kartu se spinnerem a pak ji nahraď výsledkem. Loader funguje u webhooků i odpovědí na příkazy. V odpovědi na příkaz můžeš navíc dát uvažování modelu do thinking: členové místo stěny textu uvidí přepínač Show thinking.
Nejdřív: loader
Potom: odpověď, uvažování sbalené
{
"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 | Co dělá |
|---|---|---|
loader | boolean | true zobrazí spinner místo těla karty. |
loader_text | string | Řádek vedle spinneru, třeba „Přemýšlím…“. |
loader_sub_text | string | Menší řádek pod ním. |
thinking | string | Sbalené uvažování pod popisem, v markdownu. |
Když chceš loader vyměnit za odpověď, aktualizuj zprávu novou kartou bez loader. Jak na to, popisují živé aktualizace.
Dlouhé popisy
Popis může mít až 50 000 bajtů. Po prvních 1 000 členové uvidí začátek a tlačítko Show more, které načte zbytek, takže dlouhý report nezaplaví kanál.
Systémové zprávy
Nastav "type": "system_message" pro oznámení místo příspěvku bota: plánovanou údržbu, změny pravidel a cokoli, co mluví za samotnou komunitu. Bere stejná pole i tlačítka.
{
"message_container": {
"type": "system_message",
"color": "orange",
"title": "Maintenance tonight",
"description": "The build servers are down from 22:00 to 23:00."
}
}Barvy
Barva okraje je na kartě nejrychlejší signál. Pro stejný druh zpráv používej pokaždé stejnou barvu.
| Barva | Na co ji použít |
|---|---|
green | Úspěch: prošlo, nasazeno, hotovo |
red | Neúspěch: selhalo, výpadek, zamítnuto |
orange | Varování, na které je potřeba se podívat |
yellow | Čeká se na někoho: schválení, otázky |
blue | Informace, výchozí barva |
purple | Události v kódu nebo něco zvláštního |
Postav si svůj embed
Uprav pole nebo JSON payload: obojí zůstává synchronizované. Náhled ukazuje zprávu přesně tak, jak se objeví v kanálu. Tohle je skutečné tělo webhooku; zkopíruj ho, až bude vše sedět.