Nachrichtenkarten gestalten
Alles, was ein Bot postet, ob per Webhook, als Befehlsantwort oder als Button-Update, ist eine Karte. Eine gute Karte sagt auf einen Blick, was passiert ist: ein farbiger Rand, ein Titel, ein Status, darunter die Details.
Was du damit machen kannst
- Einen Status zeigenEine farbige Pille wie Offen, Gemergt oder Bestanden, mit hinzugefügten und entfernten Zeilen.
- Die Details auflistenZeilen mit Label und Wert, die Mitglieder mit einem Tipp kopieren können.
- In Markdown schreibenFett, Inline-Code, Codeblöcke, Zitate und Checkboxen.
- Zeigen, dass du arbeitestEin Spinner, während dein Bot nachdenkt, und danach sein Denkprozess hinter einem Toggle.
In der App
Vier Karten, wie Mitglieder sie sehen. Jede besteht aus ein paar Zeilen JSON.
Aufbau einer Karte
Die Teile einer Karte, von oben nach unten. Lass weg, was du nicht brauchst: Eine Karte nur mit Titel ist in Ordnung.
- Kopfzeile„Nachricht von“ und ein Name: der Name des Webhooks oder, bei einer Befehlsantwort, der Name deiner Community. Eine Antwort kann ein
badgehinzufügen, etwa das Repository. - Titel und StatusDer
title, ein Link, wenn dutitle_urlsetzt, mit derstatus-Pille daneben. - UntertitelEine zweite fette Zeile,
sub_title. - BeschreibungDer Haupttext, in Markdown.
- FelderZeilen mit Label und Wert, mit einem Kopier-Button.
- FußzeileDie Uhrzeit und, wenn du sie mitsendest, hinzugefügte und entfernte Zeilen.
{
"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
}
}Alle Felder
Diese Felder gehören in message_container. Eine Karte braucht eine Beschreibung oder einen Loader. Felder mit dem Hinweis „Befehlsantworten“ fallen weg, wenn du über einen Webhook postest.
| Feld | Typ | Was es tut |
|---|---|---|
type | string | embed_message (Standard) oder system_message. |
badge | string | Ein kleiner Chip nach dem Namen in der Kopfzeile, etwa acme/web. Befehlsantworten |
avatar_url | string | Ein Bild über dem Symbol der Karte. |
color | string | Die Randfarbe. Siehe Farben unten. |
title | string | Die fette erste Zeile. |
title_url | string | Macht den Titel zu einem Link. |
sub_title | string | Eine zweite fette Zeile unter dem Titel. |
description | string | Der Haupttext, in Markdown. |
fields | array | [{ "field": "…", "value": "…" }]: Zeilen mit Label und Wert. |
image_url, image_base64 | string | Ein Bild auf der Karte. |
images | array | [{ "image_url": "…" }]: eine Galerie aus mehreren Bildern. |
status | object oder string | Eine farbige Pille neben dem Titel. Siehe unten. Befehlsantworten |
additions, deletions, files_changed | number | Diff-Statistik in der Fußzeile. Befehlsantworten |
loader, loader_text, loader_sub_text | boolean, string | Ein Spinner anstelle des Haupttexts. |
thinking | string | Denkprozess hinter einem Toggle Denken anzeigen. Befehlsantworten |
thinking verstehen Markdown: **bold**, _italic_, ~~strike~~, `inline code`, Codeblöcke mit Fences, > quotes, - [x]-Checkboxen, @Erwähnungen und :emoji:.Status und Diff-Statistik
Eine Status-Pille erzählt die Geschichte, bevor jemand den Text liest. Sie sitzt neben dem Titel oder, wenn es keinen Titel gibt, in der Fußzeile; die Diff-Statistik steht neben der Uhrzeit. Beides funktioniert in Befehlsantworten, und die eingebaute GitHub-Integration nutzt es. Ein Webhook lässt beides weg.
{
"message_container": {
"color": "red",
"title": "Build failed on main",
"status": { "label": "Failing", "color": "red" },
"description": "`search.test.js`: 2 of 212 tests failed."
}
}| Feld | Typ | Was es tut |
|---|---|---|
status | object oder string | Ein einfacher String ist das Label: "status": "Open". |
status.label | string | Der Text der Pille. Ohne ihn gibt es keine Pille. |
status.color | string | green, purple, red, orange, yellow, blue oder gray. |
status.icon | string | Ein optionales Symbol aus der Liste unten. |
additions | number | Hinzugefügte Zeilen, als grünes +86 angezeigt. |
deletions | number | Entfernte Zeilen, als rotes -12 angezeigt. |
files_changed | number | Geänderte Dateien, als 3 files angezeigt. |
Symbole
| Wert | Symbol | Typische Verwendung |
|---|---|---|
pull_request | git-pull-request | Ein Pull Request wurde geöffnet |
pull_request_closed | git-pull-request-closed | Ohne Merge geschlossen |
merge, merged | git-merge | Gemergt |
commit | git-commit | Ein gepushter Commit |
issue | circle-dot | Ein Issue wurde eröffnet |
issue_closed | circle-check | Ein Issue wurde geschlossen |
check | circle-check | Tests bestanden, ein Job erfolgreich |
Eine Zuordnung, die für GitHub funktioniert
Die eingebaute GitHub-Integration nutzt diese Werte; übernimm sie für deine eigenen Tools.
| Ereignis | Label | Farbe | Symbol |
|---|---|---|---|
| Pull Request geöffnet | Open | green | pull_request |
| Entwurf | Draft | gray | pull_request |
| Gemergt | Merged | purple | merged |
| Ohne Merge geschlossen | Closed | red | pull_request_closed |
| Issue eröffnet | Open | green | issue |
| Issue geschlossen | Closed | purple | issue_closed |
| Commit gepusht | Commit | gray | commit |
| Tests bestanden | Passing | green | check |
| Tests fehlgeschlagen | Failing | red | keins |
Loader und Denkprozess
Für alles, was einen Moment dauert, etwa eine KI-Antwort oder einen langen Job, postest du zuerst eine Karte mit Spinner und ersetzt sie dann durch das Ergebnis. Der Loader funktioniert bei Webhooks und Befehlsantworten. In einer Befehlsantwort kannst du außerdem den Denkprozess des Modells in thinking ablegen: Mitglieder sehen dann einen Toggle Denken anzeigen statt einer Textwand.
Zuerst: der Loader
Dann: die Antwort, der Denkprozess eingeklappt
{
"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…"
}
}| Feld | Typ | Was es tut |
|---|---|---|
loader | boolean | true zeigt den Spinner anstelle des Haupttexts. |
loader_text | string | Die Zeile neben dem Spinner, etwa „Denkt nach…“. |
loader_sub_text | string | Eine kleinere Zeile darunter. |
thinking | string | Eingeklappter Denkprozess unter der Beschreibung, in Markdown. |
Um den Loader gegen die Antwort zu tauschen, aktualisierst du die Nachricht mit einer neuen Karte ohne loader. Wie das geht, steht unter Live-Updates.
Lange Beschreibungen
Eine Beschreibung darf bis zu 50.000 Bytes lang sein. Nach den ersten 1.000 sehen Mitglieder den Anfang und einen Button Mehr anzeigen, der den Rest lädt, damit ein langer Bericht den Kanal nicht flutet.
Systemnachrichten
Setz "type": "system_message" für eine Mitteilung statt eines Bot-Posts: Wartungsfenster, geänderte Regeln, alles, was im Namen der Community selbst spricht. Sie nimmt dieselben Felder und Buttons an.
{
"message_container": {
"type": "system_message",
"color": "orange",
"title": "Maintenance tonight",
"description": "The build servers are down from 22:00 to 23:00."
}
}Farben
Die Randfarbe ist das schnellste Signal auf einer Karte. Nimm für dieselbe Art von Neuigkeit jedes Mal dieselbe Farbe.
| Farbe | Wofür |
|---|---|
green | Erfolg: bestanden, deployt, erledigt |
red | Fehlschlag: fehlgeschlagen, ausgefallen, abgelehnt |
orange | Eine Warnung, die sich jemand ansehen sollte |
yellow | Wartet auf jemanden: Freigaben, Fragen |
blue | Information, der Standard |
purple | Code-Ereignisse oder etwas Besonderes |
Bau dein Embed
Bearbeite die Felder oder den JSON-Payload. Beides bleibt synchron. Sieh zu, wie die Nachricht genau so dargestellt wird wie in einem Kanal. Das ist der echte Webhook-Body; kopiere ihn, wenn alles passt.