Oblikuj kartice sporočil
Vse, kar objavi bot, iz webhooka, kot odgovor na ukaz ali ob posodobitvi po pritisku gumba, je kartica. Dobra kartica na prvi pogled pove, kaj se je zgodilo: barvni rob, naslov, stanje, spodaj pa podrobnosti.
Kaj lahko narediš
- Pokaži stanjeBarvna oznaka, kot so Open, Merged ali Passing, z dodanimi in odstranjenimi vrsticami.
- Naštej podrobnostiVrstice z nazivom in vrednostjo, ki jih člani kopirajo z enim dotikom.
- Piši v markdownuKrepko, koda v vrstici, bloki kode, citati in potrditvena polja.
- Pokaži, da delašIndikator nalaganja, medtem ko bot razmišlja, nato pa njegovo razmišljanje za stikalom.
V aplikaciji
Štiri kartice, kot jih vidijo člani. Vsaka je le nekaj vrstic JSON-a.
Zgradba kartice
Deli kartice, od zgoraj navzdol. Izpusti, česar ne potrebuješ: tudi kartica s samim naslovom je v redu.
- Glava„Message from“ in ime: ime webhooka ali, pri odgovoru na ukaz, ime tvoje skupnosti. Odgovor lahko doda
badge, na primer repozitorij. - Naslov in stanje
title, ki postane povezava, ko nastavištitle_url, ob njem pa oznakastatus. - PodnaslovDruga krepka vrstica,
sub_title. - OpisVsebina, v markdownu.
- PoljaVrstice z nazivom in vrednostjo, z gumbom za kopiranje.
- NogaČas ter dodane in odstranjene vrstice, če jih pošlješ.
{
"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
}
}Vsa polja
Ta polja gredo v message_container. Kartica potrebuje opis ali indikator nalaganja. Polja z oznako „Odgovori na ukaze“ se izpustijo, ko objavljaš prek webhooka.
| Polje | Tip | Kaj naredi |
|---|---|---|
type | string | embed_message (privzeto) ali system_message. |
badge | string | Majhna značka za imenom v glavi, na primer acme/web. Odgovori na ukaze |
avatar_url | string | Slika čez ikono kartice. |
color | string | Barva roba. Glej barve spodaj. |
title | string | Krepka prva vrstica. |
title_url | string | Naslov spremeni v povezavo. |
sub_title | string | Druga krepka vrstica pod naslovom. |
description | string | Vsebina, v markdownu. |
fields | array | [{ "field": "…", "value": "…" }]: vrstice z nazivom in vrednostjo. |
image_url, image_base64 | string | Slika na kartici. |
images | array | [{ "image_url": "…" }]: galerija več slik. |
status | object ali string | Barvna oznaka ob naslovu. Glej spodaj. Odgovori na ukaze |
additions, deletions, files_changed | number | Statistika sprememb v nogi. Odgovori na ukaze |
loader, loader_text, loader_sub_text | boolean, string | Indikator nalaganja namesto vsebine. |
thinking | string | Razmišljanje, skrito za stikalom Show thinking. Odgovori na ukaze |
thinking razumeta markdown: **bold**, _italic_, ~~strike~~, `inline code`, večvrstične bloke kode, > quotes, potrditvena polja - [x], @omembe in :emoji:.Stanje in statistika sprememb
Oznaka stanja pove zgodbo, še preden kdo prebere besedilo. Stoji ob naslovu ali, če naslova ni, v nogi; statistika sprememb se prikaže ob času. Oboje deluje v odgovorih na ukaze in uporablja ju vgrajena integracija z GitHubom. Webhook ju izpusti.
{
"message_container": {
"color": "red",
"title": "Build failed on main",
"status": { "label": "Failing", "color": "red" },
"description": "`search.test.js`: 2 of 212 tests failed."
}
}| Polje | Tip | Kaj naredi |
|---|---|---|
status | object ali string | Golo besedilo je oznaka: "status": "Open". |
status.label | string | Besedilo oznake. Brez njega oznake ni. |
status.color | string | green, purple, red, orange, yellow, blue ali gray. |
status.icon | string | Neobvezna ikona s spodnjega seznama. |
additions | number | Dodane vrstice, prikazane kot zeleno +86. |
deletions | number | Odstranjene vrstice, prikazane kot rdeče -12. |
files_changed | number | Spremenjene datoteke, prikazane kot 3 files. |
Ikone
| Vrednost | Ikona | Tipična uporaba |
|---|---|---|
pull_request | git-pull-request | Odprt pull request |
pull_request_closed | git-pull-request-closed | Zaprt brez združitve |
merge, merged | git-merge | Združeno |
commit | git-commit | Potisnjen commit |
issue | circle-dot | Odprt issue |
issue_closed | circle-check | Zaprt issue |
check | circle-check | Testi so uspeli, opravilo je uspešno končano |
Preslikava, ki deluje za GitHub
Vgrajena integracija z GitHubom uporablja te vrednosti; prekopiraj jih za svoja orodja.
| Dogodek | Oznaka | Barva | Ikona |
|---|---|---|---|
| Odprt pull request | Open | green | pull_request |
| Osnutek | Draft | gray | pull_request |
| Združeno | Merged | purple | merged |
| Zaprt brez združitve | Closed | red | pull_request_closed |
| Odprt issue | Open | green | issue |
| Zaprt issue | Closed | purple | issue_closed |
| Potisnjen commit | Commit | gray | commit |
| Testi uspešni | Passing | green | check |
| Testi neuspešni | Failing | red | nobena |
Nalaganje in razmišljanje
Za vse, kar traja nekaj časa, kot UI-odgovor ali dolgo opravilo, najprej objavi kartico z indikatorjem nalaganja, nato jo zamenjaj z rezultatom. Indikator nalaganja deluje iz webhookov in v odgovorih na ukaze. V odgovor na ukaz lahko v thinking dodaš tudi razmišljanje modela: člani namesto stene besedila vidijo stikalo Show thinking.
Najprej: indikator nalaganja
Nato: odgovor, razmišljanje skrito
{
"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…"
}
}| Polje | Tip | Kaj naredi |
|---|---|---|
loader | boolean | true prikaže indikator nalaganja namesto vsebine. |
loader_text | string | Vrstica ob indikatorju, na primer „Razmišljam…“. |
loader_sub_text | string | Manjša vrstica pod njo. |
thinking | string | Skrito razmišljanje pod opisom, v markdownu. |
Da indikator nalaganja zamenjaš z odgovorom, posodobi sporočilo z novo kartico brez loader. Kako, piše na strani posodobitve v živo.
Dolgi opisi
Opis je lahko dolg do 50.000 bajtov. Po prvih 1000 člani vidijo začetek in gumb Show more, ki naloži preostanek, zato dolgo poročilo ne preplavi kanala.
Sistemska sporočila
Nastavi "type": "system_message" za obvestilo namesto objave bota: vzdrževalna okna, spremembe pravil, vse, kar govori v imenu same skupnosti. Sprejme ista polja in gumbe.
{
"message_container": {
"type": "system_message",
"color": "orange",
"title": "Maintenance tonight",
"description": "The build servers are down from 22:00 to 23:00."
}
}Barve
Barva roba je najhitrejši signal na kartici. Za isto vrsto novic vedno uporabi isto barvo.
| Barva | Uporabi za |
|---|---|
green | Uspeh: uspelo, nameščeno, končano |
red | Neuspeh: ni uspelo, ne deluje, zavrnjeno |
orange | Opozorilo, ki ga je treba pogledati |
yellow | Čaka na nekoga: odobritve, vprašanja |
blue | Informacija, privzeto |
purple | Dogodki v kodi ali nekaj posebnega |
Sestavi svoj embed
Uredi polja ali JSON payload. Oboje ostaja usklajeno. Predogled pokaže sporočilo natanko tako, kot bo prikazano v kanalu. To je pravo telo webhooka; kopiraj ga, ko je videti prav.