Botberichten

Overzicht

Bots plaatsen rijke berichten door een action_message te sturen. Het veld message_container.type bepaalt hoe de client het rendert:

• embed_message: een rijke kaart met gekleurd accent, bot-header, klikbare titel, markdown-body, statusbadge, diff-stats, loader en inklapbare redenering. Gemaakt voor GitHub-notificaties, CI-resultaten, deploys en AI-assistenten.
• system_message: een geverifieerde systeemkaart met interactieve knoppen die triggerketens uitvoeren.

Embed-berichten

Een embed rendert met een gekleurd linkeraccent, een header "Message from {bot} · {badge}", een klikbare titel, een subtitel en een markdown-beschrijving.

{
  "type": "action_message",
  "channel_guid": "...",
  "server_guid": "...",
  "message_container": {
    "type": "embed_message",
    "bot_name": "Github Notifications",
    "avatar_url": "https://avatars.githubusercontent.com/u/310687?v=4",
    "badge": "acme/acme-core",
    "color": "purple",
    "title": "alex opened pull request #144",
    "title_url": "https://github.com/acme/acme-core/pull/144",
    "sub_title": "Resolve outlying hamlet to dominant nearby city",
    "description": "A hamlet is the smallest OSM settlement class ...",

    "status": { "label": "Open", "color": "green", "icon": "pull_request" },
    "additions": 86,
    "deletions": 38,
    "files_changed": 2
  }
}

Containervelden

Statusbadge & diff-stats

Allemaal optioneel. De status-badge rendert naast de titel; de diff-stats staan in de footer, rechts van de tijd. Elke combinatie kan; laat je alles weg, dan ziet de embed er precies uit als voorheen. Zonder title valt de statusbadge terug in de footergroep.

status.icon-waarden

Aanbevolen kleurmapping (GitHub)

Loader-status

Wanneer loader op true staat, toont de kaart een spinner met optionele teksten: een placeholder in "AI denkt na…"-stijl terwijl de bot nog werkt. title en description mogen in deze staat volledig weggelaten worden (ze renderen nog wel als ze aanwezig zijn).

{
  "message_container": {
    "type": "embed_message",
    "bot_name": "Assistant",
    "color": "blue",
    "loader": true,
    "loader_text": "Thinking…",
    "loader_sub_text": "Searching your documents"
  }
}

De bot wist de loader door een UPDATE_MESSAGE te sturen met een vervangen message_container zonder loader en mét de definitieve inhoud; de client rendert de kaart op zijn plek opnieuw.

Thinking (inklapbare redenering)

Wanneer thinking een niet-lege string is, verschijnt onder de beschrijving een ingeklapte Show thinking-rij. Klikken klapt hem client-side uit. Zelfde markdown-ondersteuning als description. Typisch gebruik: de bot plaatst een loader-kaart en bewerkt die daarna tot het definitieve antwoord, met de redenering van het model achter de toggle.

{
  "message_container": {
    "type": "embed_message",
    "bot_name": "Assistant",
    "color": "blue",
    "sub_title": "marius: how late is the standup?",
    "description": "Standup is at **09:30**.",
    "thinking": "Checked the channel history for the recurring invite…"
  }
}

Voorbeelden

{
  "message_container": {
    "type": "embed_message",
    "bot_name": "Github Notifications",
    "badge": "acme/acme-core",
    "color": "gray",
    "title": "alex pushed to master",
    "title_url": "https://github.com/acme/acme-core/commit/1a2b3c4",
    "sub_title": "Fix reverse-geocode city resolution for outlying hamlets",
    "status": { "label": "Commit", "color": "gray", "icon": "commit" },
    "additions": 86,
    "deletions": 38,
    "files_changed": 2
  }
}

{
  "message_container": {
    "type": "embed_message",
    "bot_name": "CI",
    "badge": "acme/acme-core",
    "color": "green",
    "title": "Build passed on master",
    "status": { "label": "Passing", "color": "green", "icon": "check" }
  }
}

Interactieve action messages

Action messages bevatten klikbare knoppen die meerdere acties na elkaar uitvoeren. Ze verschijnen met een systeemverificatiebadge en ondersteunen conditionele uitvoering op basis van eerdere actieresultaten.

{
  "type": "action_message",
  "message_container": {
    "type": "system_message",
    "color": "orange",
    "title": "Message Title",
    "description": "Message description"
  },
  "actions": [
    {
      "type": "button",
      "color": "green",
      "text": "Button Text",
      "triggers": [
        {
          "action": "ws:send",
          "payload": {
            "method": "SOME_METHOD",
            "data": "value"
          }
        }
      ]
    }
  ],
  "expire_in_seconds": 300,
  "id": "unique-message-id"
}

Verplichte velden

Optionele velden

Visuele stijl

Containerkleuren

• orange: amber waarschuwingsstijl
• green: succes / positieve actie
• red: fout / destructieve actie
• blue: informatie / neutraal
• purple: speciaal / premium
• yellow: opgelet / aandacht

Knopkleuren

• Primair (green, blue, purple): prominente actieknoppen
• Secundair (red, orange, yellow): secundaire of destructieve acties

Triggersysteem

Knoppen voeren meerdere acties na elkaar uit via de triggers-array. Elke trigger draait op volgorde, met conditionele uitvoering op basis van het succes of falen van de vorige trigger.

WebSocket-acties

{
  "action": "ws:send",
  "payload": {
    "method": "YOUR_METHOD_NAME",
    "param1": "value1",
    "param2": "value2"
  }
}

Berichtupdates

{
  "action": "local:update_message",
  "message_container": {
    "color": "green",
    "title": "Updated Title",
    "description": "Updated description"
  },
  "actions": []
}

Knoppen beheren bij een update:

• Stuur "actions": [] mee om alle knoppen te verwijderen na afronding
• Stuur "actions": [...] mee om knoppen te vervangen door nieuwe
• Laat het actions-veld weg om bestaande knoppen te behouden

Bericht verwijderen

{
  "action": "local:remove_message"
}

Conditionele uitvoering

Triggers kunnen conditioneel draaien op basis van het resultaat van de vorige trigger:

{
  "type": "button",
  "text": "Process Request",
  "color": "green",
  "triggers": [
    {
      "action": "ws:send",
      "payload": {
        "method": "PROCESS_DATA",
        "request_id": "12345"
      }
    },
    {
      "condition": "previous:success",
      "action": "local:update_message",
      "message_container": {
        "color": "green",
        "title": "Processing Complete",
        "description": "Your request was processed successfully"
      }
    },
    {
      "condition": "previous:failed",
      "action": "local:update_message",
      "message_container": {
        "color": "red",
        "title": "Processing Failed",
        "description": "There was an error processing your request"
      }
    }
  ]
}

Verlooptimers

Berichten kunnen een afteltimer bevatten via expire_in_seconds. De client formatteert de resterende tijd automatisch:

• Onder 60 seconden: "45 seconds"
• Onder 60 minuten: "5 minutes 30 seconds"
• Boven 60 minuten: "1 hour 15 minutes"
• Verlopen: "This message has expired"; met verlopen berichten kan niet meer worden geklikt

Live updates

Beide berichttypes worden op hun plek bijgewerkt. Het gebruikelijke patroon voor AI-achtige bots:

Zie het gebeuren

De hele loop op één plek: een commando vuurt je webhook af, je reply wordt een kaart, een knop-tik komt bij jou terug en je callback-update landt op zijn plek.

Best practices

Fouten & limieten

Foutafhandeling

• Gefaalde triggers stoppen de keten, tenzij een faalconditie matcht
• WebSocket-fouten worden gelogd en behandeld als falen
• Mislukte berichtupdates worden gelogd en behandeld als falen
• Triggers met faalcondities (previous:failed, failed) draaien juist bij fouten

Limieten

• Aanbevolen maximum aantal triggers per knop: 10
• Berichtupdates kunnen het veld message_container.type niet wijzigen
• WebSocket-payloadlimieten gelden ook voor trigger-payloads
• Met verlopen berichten kan niet meer worden geklikt