---
title: "Card dei messaggi: cosa può mostrare un messaggio bot su mssgs"
description: "Progetta i messaggi bot di mssgs: titoli, markdown, campi, immagini, pillole di stato con diff, loader, ragionamento e colori. Con un builder dal vivo."
canonical: https://docs.mss.gs/it/bots
language: it
---

# 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 stato** Una pillola colorata come Aperta, Unita o Superata, con le righe aggiunte e rimosse.

- **Elenca i dettagli** Righe di etichetta e valore che i membri possono copiare con un tocco.

- **Scrivi in markdown** Grassetto, codice inline, blocchi di codice, citazioni e caselle di spunta.

- **Mostra che stai lavorando** Uno spinner mentre il tuo bot pensa, e poi il suo ragionamento dietro un interruttore.

Nell'app

#### Pull request #212 aperta

Ricerca più veloce nell’elenco dei canali

#### Build #1847 riuscita

#### api.acme.com è offline

Quattro card come le vedono i membri. Ognuna è qualche riga di JSON.

- [Anatomia](#anatomy)

- [Tutti i campi](#fields)

- [Stato e statistiche diff](#status)

- [Loader e ragionamento](#ai)

- [Messaggi di sistema](#system)

- [Colori](#colors)

- [Creane una](#try)

## 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.

#### Pull request #212 aperta

Ricerca più veloce nell’elenco dei canali

- **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 stato** Il title , un link se imposti title_url , con accanto la pillola status .

- **Sottotitolo** Una seconda riga in grassetto, sub_title .

- **Descrizione** Il corpo, in markdown.

- **Campi** Righe di etichetta e valore, con un pulsante per copiare.

- **Piè di pagina** L’orario, e le righe aggiunte e rimosse se le invii.

```json
{
  "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 |

## 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.

#### Pull request #212 unita

#### Build fallita su main

#### maya ha fatto push su main

```json
{
  "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

maya: a che ora è lo standup?

Poi: la risposta, con il ragionamento ripiegato

```json
{
  "message_container": {
    "type": "embed_message",
    "color": "blue",
    "loader": true,
    "loader_text": "Thinking…",
    "loader_sub_text": "Reading the last 50 messages"
  }
}
```

```json
{
  "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](https://docs.mss.gs/it/live-updates).

## 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.

```json
{
  "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.

## Continua a costruire