Berichtkaarten ontwerpen
Alles wat een bot post, via een webhook, als antwoord op een commando of als update na een knopdruk, is een kaart. Een goede kaart laat in één oogopslag zien wat er is gebeurd: een gekleurde rand, een titel, een status en de details eronder.
Wat je kunt doen
- Een status tonenEen gekleurde pill zoals Open, Gemerged of Geslaagd, met toegevoegde en verwijderde regels.
- De details op een rijRegels met een label en een waarde, die leden met één tik kunnen kopiëren.
- In markdown schrijvenVet, inline code, codeblokken, citaten en vinkjes.
- Laten zien dat je bezig bentEen spinner terwijl je bot nadenkt, en daarna zijn redenering achter een schakelaar.
In de app
Vier kaarten zoals leden ze zien. Elke kaart is een paar regels JSON.
De opbouw van een kaart
De onderdelen van een kaart, van boven naar beneden. Laat weg wat je niet nodig hebt: een kaart met alleen een titel is prima.
- Kop"Bericht van" en een naam: de naam van de webhook, of de naam van je community bij een antwoord op een commando. Een antwoord kan er een
badgeaan toevoegen, zoals de repository. - Titel en statusDe
title, een link als jetitle_urlinvult, met destatus-pill ernaast. - SubtitelEen tweede vetgedrukte regel,
sub_title. - BeschrijvingDe hoofdtekst, in markdown.
- VeldenRegels met een label en een waarde, met een kopieerknop.
- VoettekstDe tijd, en de toegevoegde en verwijderde regels als je die meestuurt.
{
"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 velden
Deze horen in message_container. Een kaart heeft een beschrijving nodig, of een loader. Velden met "antwoorden op commando's" vallen weg als je via een webhook post.
| Veld | Type | Wat het doet |
|---|---|---|
type | string | embed_message (standaard) of system_message. |
badge | string | Een klein label na de naam in de kop, zoals acme/web. Antwoorden op commando's |
avatar_url | string | Een afbeelding over het icoon van de kaart. |
color | string | De kleur van de rand. Zie kleuren hieronder. |
title | string | De vetgedrukte eerste regel. |
title_url | string | Maakt van de titel een link. |
sub_title | string | Een tweede vetgedrukte regel onder de titel. |
description | string | De hoofdtekst, in markdown. |
fields | array | [{ "field": "…", "value": "…" }]: regels met een label en een waarde. |
image_url, image_base64 | string | Een afbeelding op de kaart. |
images | array | [{ "image_url": "…" }]: een galerij met meerdere afbeeldingen. |
status | object of string | Een gekleurde pill naast de titel. Zie hieronder. Antwoorden op commando's |
additions, deletions, files_changed | number | Diff-stats in de voettekst. Antwoorden op commando's |
loader, loader_text, loader_sub_text | boolean, string | Een spinner in plaats van de hoofdtekst. |
thinking | string | Redenering achter een schakelaar Toon denkproces. Antwoorden op commando's |
thinking begrijpen markdown: **bold**, _italic_, ~~strike~~, `inline code`, codeblokken tussen backticks, > quotes, - [x]-vinkjes, @vermeldingen en :emoji:.Status en diff-stats
Een statuspill vertelt het verhaal al voordat iemand de tekst leest. Hij staat naast de titel, of in de voettekst als er geen titel is; diff-stats staan naast de tijd. Allebei werken ze in antwoorden op commando's, en de ingebouwde GitHub-integratie gebruikt ze. Een webhook laat ze weg.
{
"message_container": {
"color": "red",
"title": "Build failed on main",
"status": { "label": "Failing", "color": "red" },
"description": "`search.test.js`: 2 of 212 tests failed."
}
}| Veld | Type | Wat het doet |
|---|---|---|
status | object of string | Een losse string is het label: "status": "Open". |
status.label | string | De tekst in de pill. Zonder label geen pill. |
status.color | string | green, purple, red, orange, yellow, blue of gray. |
status.icon | string | Een optioneel icoon uit de lijst hieronder. |
additions | number | Toegevoegde regels, getoond als groene +86. |
deletions | number | Verwijderde regels, getoond als rode -12. |
files_changed | number | Gewijzigde bestanden, getoond als 3 files. |
Iconen
| Waarde | Icoon | Typisch gebruik |
|---|---|---|
pull_request | git-pull-request | Een pull request geopend |
pull_request_closed | git-pull-request-closed | Gesloten zonder merge |
merge, merged | git-merge | Gemerged |
commit | git-commit | Een gepushte commit |
issue | circle-dot | Een issue geopend |
issue_closed | circle-check | Een issue gesloten |
check | circle-check | Tests geslaagd, een taak gelukt |
Een indeling die werkt voor GitHub
De ingebouwde GitHub-integratie gebruikt deze; neem ze over voor je eigen tools.
| Gebeurtenis | Label | Kleur | Icoon |
|---|---|---|---|
| Pull request geopend | Open | green | pull_request |
| Draft | Draft | gray | pull_request |
| Gemerged | Merged | purple | merged |
| Gesloten zonder merge | Closed | red | pull_request_closed |
| Issue geopend | Open | green | issue |
| Issue gesloten | Closed | purple | issue_closed |
| Commit gepusht | Commit | gray | commit |
| Tests geslaagd | Passing | green | check |
| Tests mislukt | Failing | red | geen |
Loader en denkproces
Voor alles wat even duurt, zoals een AI-antwoord of een lange taak, post je eerst een kaart met een spinner en vervang je die daarna door het resultaat. De loader werkt vanuit webhooks en in antwoorden op commando's. In een antwoord op een commando kun je de redenering van het model ook in thinking zetten: leden zien dan een schakelaar Toon denkproces in plaats van een muur van tekst.
Eerst: de loader
Daarna: het antwoord, met de redenering ingeklapt
{
"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…"
}
}| Veld | Type | Wat het doet |
|---|---|---|
loader | boolean | true toont de spinner in plaats van de hoofdtekst. |
loader_text | string | De regel naast de spinner, zoals "Denkt na…". |
loader_sub_text | string | Een kleinere regel eronder. |
thinking | string | Ingeklapte redenering onder de beschrijving, in markdown. |
Om de loader te vervangen door het antwoord, werk je het bericht bij met een nieuwe kaart zonder loader. Hoe dat gaat lees je bij live-updates.
Lange beschrijvingen
Een beschrijving mag tot 50.000 bytes zijn. Voorbij de eerste 1.000 zien leden het begin en een knop Meer tonen die de rest laadt, zodat een lang rapport het kanaal niet overspoelt.
Systeemberichten
Zet "type": "system_message" voor een mededeling in plaats van een botbericht: onderhoudsvensters, beleidswijzigingen, alles waarin de community zelf aan het woord is. Het kent dezelfde velden en knoppen.
{
"message_container": {
"type": "system_message",
"color": "orange",
"title": "Maintenance tonight",
"description": "The build servers are down from 22:00 to 23:00."
}
}Kleuren
De randkleur is het snelste signaal op een kaart. Gebruik voor hetzelfde soort nieuws elke keer dezelfde kleur.
| Kleur | Gebruik je voor |
|---|---|
green | Succes: geslaagd, uitgerold, klaar |
red | Mislukt: kapot, onbereikbaar, afgewezen |
orange | Een waarschuwing waar iemand naar moet kijken |
yellow | Wacht op iemand: goedkeuringen, vragen |
blue | Informatie, de standaard |
purple | Code-events, of iets bijzonders |
Bouw je embed
Bewerk de velden of de JSON payload. Beide blijven in sync. Zie het bericht renderen precies zoals in een kanaal. Dit is de echte webhook body; kopieer hem als het goed staat.