Bot Messages

Overview

Bots post rich messages by sending an action_message. The message_container.type decides how the client renders it:

• embed_message: a rich card with a colored accent, bot header, clickable title, markdown body, status badge, diff stats, loader and collapsible reasoning. Built for GitHub notifications, CI results, deploys and AI assistants.
• system_message: a verified system-style card with interactive buttons that run trigger chains.

Embed Messages

An embed renders with a colored left accent, a "Message from {bot} · {badge}" header, a clickable title, a subtitle, and a markdown description.

{
  "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
  }
}

Container Fields

Status Badge & Diff Stats

All optional. The status badge renders inline next to the title; the diff stats render in the footer, right of the timestamp. Provide any combination; omit them all and the embed looks exactly as before. If there is no title, the status badge falls back into the footer group.

status.icon values

Suggested color mapping (GitHub)

Loader State

When loader is true the card shows an animated spinner with optional texts: an "AI thinking…" style placeholder while the bot is still working. title and description may be omitted entirely in this state (they still render if present).

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

The bot clears the loader by sending an UPDATE_MESSAGE with a replaced message_container that omits loader and carries the final content; the client re-renders the card in place.

Thinking (Collapsible Reasoning)

When thinking is a non-empty string, a collapsed Show thinking toggle row renders below the description. Click expands it client-side. Same markdown support as description. Typical use: the bot posts a loader card, then edits it into the final answer with the model's reasoning tucked behind the 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…"
  }
}

Examples

{
  "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" }
  }
}

Interactive Action Messages

Action messages carry clickable buttons that trigger multiple sequential actions. They appear with system verification badges and support conditional execution based on previous action results.

{
  "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"
}

Required Fields

Optional Fields

Visual Styling

Container colors

• orange: amber warning style
• green: success / positive action style
• red: error / destructive action style
• blue: information / neutral style
• purple: special / premium style
• yellow: caution / attention style

Button colors

• Primary (green, blue, purple): prominent action buttons
• Secondary (red, orange, yellow): secondary or destructive actions

Trigger System

Buttons execute multiple actions sequentially using the triggers array. Each trigger runs in order, with conditional execution based on the previous trigger's success or failure.

WebSocket Actions

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

Message Updates

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

Managing buttons on update:

• Include "actions": [] to remove all buttons after completion
• Include "actions": [...] to replace buttons with new ones
• Omit the actions field to keep existing buttons unchanged

Message Removal

{
  "action": "local:remove_message"
}

Conditional Execution

Triggers can execute conditionally based on the previous trigger's result:

{
  "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"
      }
    }
  ]
}

Expiration Timers

Messages can include countdown timers using expire_in_seconds. The client formats the remaining time automatically:

• Under 60 seconds: "45 seconds"
• Under 60 minutes: "5 minutes 30 seconds"
• Over 60 minutes: "1 hour 15 minutes"
• Expired: "This message has expired"; expired messages cannot be interacted with

Live Updates

Both message types update in place. The common pattern for AI-style bots:

See it happen

The whole loop in one place: a command fires your webhook, your reply becomes a card, a button tap comes back to you, and your callback update lands in place.

Best Practices

Errors & Limits

Error handling

• Failed triggers stop the execution chain unless a failure condition is met
• WebSocket errors are logged and treated as failures
• Message update failures are logged and treated as failures
• Triggers with failure conditions (previous:failed, failed) execute on errors

Limitations

• Maximum recommended triggers per button: 10
• Message updates cannot change the message_container.type field
• WebSocket payload size limits apply to trigger payloads
• Expired messages cannot be interacted with