Progetta le card dei messaggi
Tutto ciò che un bot pubblica, da un webhook, da una risposta a un comando o dall’aggiornamento di un pulsante, è una card. Una buona card dice cosa è successo in un colpo d’occhio: un bordo colorato, un titolo, uno stato, i dettagli sotto.
Cosa puoi fare
- Mostra uno statoUna pillola colorata come Aperta, Unita o Superata, con le righe aggiunte e rimosse.
- Elenca i dettagliRighe di etichetta e valore che i membri possono copiare con un tocco.
- Scrivi in markdownGrassetto, codice inline, blocchi di codice, citazioni e caselle di spunta.
- Mostra che stai lavorandoUno spinner mentre il tuo bot pensa, e poi il suo ragionamento dietro un interruttore.
Nell'app
Quattro card come le vedono i membri. Ognuna è qualche riga di JSON.
Anatomia di una card
Le parti di una card, dall’alto in basso. Ometti ciò che non ti serve: anche una card con il solo titolo va bene.
- Intestazione“Messaggio da” e un nome: il nome del webhook, o il nome della tua community per la risposta a un comando. Una risposta può aggiungere un
badge, come il repository. - Titolo e statoIl
title, un link se impostititle_url, con accanto la pillolastatus. - SottotitoloUna seconda riga in grassetto,
sub_title. - DescrizioneIl corpo, in markdown.
- CampiRighe di etichetta e valore, con un pulsante per copiare.
- Piè di paginaL’orario, e le righe aggiunte e rimosse se le invii.
{
"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
}
}Tutti i campi
Vanno in message_container. Una card ha bisogno di una descrizione, o di un loader. I campi segnati “risposte ai comandi” vengono scartati quando pubblichi tramite un webhook.
| Campo | Tipo | Cosa fa |
|---|---|---|
type | string | embed_message (predefinito) o system_message. |
badge | string | Un piccolo chip dopo il nome nell’intestazione, come acme/web. Risposte ai comandi |
avatar_url | string | Un’immagine sopra l’icona della card. |
color | string | Il colore del bordo. Vedi i colori più sotto. |
title | string | La prima riga, in grassetto. |
title_url | string | Trasforma il titolo in un link. |
sub_title | string | Una seconda riga in grassetto sotto il titolo. |
description | string | Il corpo, in markdown. |
fields | array | [{ "field": "…", "value": "…" }]: righe di etichetta e valore. |
image_url, image_base64 | string | Un’immagine sulla card. |
images | array | [{ "image_url": "…" }]: una galleria di più immagini. |
status | object o string | Una pillola colorata accanto al titolo. Vedi più sotto. Risposte ai comandi |
additions, deletions, files_changed | number | Statistiche diff nel piè di pagina. Risposte ai comandi |
loader, loader_text, loader_sub_text | boolean, string | Uno spinner al posto del corpo. |
thinking | string | Il ragionamento dietro un interruttore Mostra il ragionamento. Risposte ai comandi |
thinking capiscono il markdown: **bold**, _italic_, ~~strike~~, `inline code`, blocchi di codice delimitati, > quotes, caselle di spunta - [x], @menzioni e :emoji:.Stato e statistiche diff
Una pillola di stato racconta la storia prima che qualcuno legga il testo. Sta accanto al titolo, o nel piè di pagina quando non c’è un titolo; le statistiche diff compaiono accanto all’orario. Entrambe funzionano nelle risposte ai comandi, e l’integrazione GitHub inclusa le usa. Un webhook le scarta.
{
"message_container": {
"color": "red",
"title": "Build failed on main",
"status": { "label": "Failing", "color": "red" },
"description": "`search.test.js`: 2 of 212 tests failed."
}
}| Campo | Tipo | Cosa fa |
|---|---|---|
status | object o string | Una semplice stringa è l’etichetta: "status": "Open". |
status.label | string | Il testo della pillola. Senza, la pillola non c’è. |
status.color | string | green, purple, red, orange, yellow, blue o gray. |
status.icon | string | Un’icona facoltativa, dall’elenco qui sotto. |
additions | number | Righe aggiunte, mostrate in verde come +86. |
deletions | number | Righe rimosse, mostrate in rosso come -12. |
files_changed | number | File toccati, mostrati come 3 files. |
Icone
| Valore | Icona | Uso tipico |
|---|---|---|
pull_request | git-pull-request | Una pull request aperta |
pull_request_closed | git-pull-request-closed | Chiusa senza merge |
merge, merged | git-merge | Unita |
commit | git-commit | Un commit inviato |
issue | circle-dot | Una issue aperta |
issue_closed | circle-check | Una issue chiusa |
check | circle-check | Test superati, un job riuscito |
Una mappatura che funziona per GitHub
L’integrazione GitHub inclusa usa queste; copiale per i tuoi strumenti.
| Evento | Etichetta | Colore | Icona |
|---|---|---|---|
| Pull request aperta | Open | green | pull_request |
| Bozza | Draft | gray | pull_request |
| Unita | Merged | purple | merged |
| Chiusa senza merge | Closed | red | pull_request_closed |
| Issue aperta | Open | green | issue |
| Issue chiusa | Closed | purple | issue_closed |
| Commit inviato | Commit | gray | commit |
| Test superati | Passing | green | check |
| Test falliti | Failing | red | nessuna |
Loader e ragionamento
Per tutto ciò che richiede un momento, come una risposta dell’IA o un lavoro lungo, pubblica prima una card con uno spinner, poi sostituiscila con il risultato. Il loader funziona dai webhook e dalle risposte ai comandi. In una risposta a un comando puoi anche mettere il ragionamento del modello in thinking: i membri vedono un interruttore Mostra il ragionamento invece di un muro di testo.
Prima: il loader
Poi: la risposta, con il ragionamento ripiegato
{
"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…"
}
}| Campo | Tipo | Cosa fa |
|---|---|---|
loader | boolean | true mostra lo spinner al posto del corpo. |
loader_text | string | La riga accanto allo spinner, come “Sto pensando…”. |
loader_sub_text | string | Una riga più piccola sotto. |
thinking | string | Ragionamento ripiegato sotto la descrizione, in markdown. |
Per sostituire il loader con la risposta, aggiorna il messaggio con una nuova card che omette loader. Come si fa è spiegato in aggiornamenti live.
Descrizioni lunghe
Una descrizione può arrivare a 50.000 byte. Oltre i primi 1.000, i membri vedono l’inizio e un pulsante Mostra di più che carica il resto, così un report lungo non inonda il canale.
Messaggi di sistema
Imposta "type": "system_message" per un avviso invece che per un post del bot: finestre di manutenzione, cambi di regole, tutto ciò che parla a nome della community stessa. Accetta gli stessi campi e pulsanti.
{
"message_container": {
"type": "system_message",
"color": "orange",
"title": "Maintenance tonight",
"description": "The build servers are down from 22:00 to 23:00."
}
}Colori
Il colore del bordo è il segnale più rapido su una card. Usa lo stesso colore per lo stesso tipo di notizia, ogni volta.
| Colore | Usalo per |
|---|---|
green | Successo: superato, distribuito, fatto |
red | Fallimento: fallito, offline, rifiutato |
orange | Un avviso che merita un’occhiata |
yellow | In attesa di qualcuno: approvazioni, domande |
blue | Informazione, il colore predefinito |
purple | Eventi del codice, o qualcosa di speciale |
Crea il tuo embed
Modifica i campi o il payload JSON. Restano sempre sincronizzati. Guarda il messaggio apparire esattamente come in un canale. Questo è il vero body del webhook; copialo quando ti convince.