Blocks Overview

Blocks are the building bricks of every card. Each block has a type field and type-specific fields. Blocks are passed as an array when creating or updating cards.

All Block Types

Type	Description	Interactive
text	Paragraph or heading text	No
badge	Colored status pill	No
kv	Key/value table	No
image	Embedded image	No
button	One or more action buttons	Yes
divider	Horizontal separator line	No
input	Text/number/email/URL input	Yes
select	Single-select dropdown	Yes
multiselect	Multi-select dropdown	Yes
toggle	Boolean on/off toggle	Yes

Interactive blocks fire input_change interactions to your webhook when the user modifies them (requires channel mode: "interactive").

Block Structure

Every block must have a type field. All other fields are type-specific.

{
  "type": "text",
  "content": "Hello, world!"
}

Optionally include an id for patching later:

{
  "id": "status-badge",
  "type": "badge",
  "label": "Running",
  "variant": "pending"
}

If id is omitted, a UUID is auto-generated.

A Complete Card Example

{
  "status": "pending",
  "blocks": [
    {
      "id": "title",
      "type": "text",
      "content": "New Order Received",
      "size": "lg",
      "bold": true
    },
    {
      "id": "status-badge",
      "type": "badge",
      "label": "Processing",
      "variant": "pending"
    },
    {
      "type": "divider"
    },
    {
      "id": "order-details",
      "type": "kv",
      "rows": [
        { "key": "Order #", "value": "1234" },
        { "key": "Customer", "value": "Jane Smith" },
        { "key": "Total", "value": "$89.99" }
      ]
    },
    {
      "type": "image",
      "url": "https://example.com/product.jpg",
      "alt": "Product image"
    },
    {
      "id": "actions",
      "type": "button",
      "buttons": [
        { "id": "approve", "label": "Approve", "style": "primary" },
        { "id": "reject", "label": "Reject", "style": "danger" }
      ]
    }
  ]
}

Card Status

The top-level status field controls the card's border color. It's separate from block content.

Value	Color
"default"	Neutral (no highlight)
"success"	Green
"warning"	Yellow/Amber
"error"	Red
"pending"	Blue/Grey

Patching Blocks

When updating a card, send only the blocks you want to change using the patch format:

{
  "blocks": [
    {
      "id": "status-badge",
      "patch": {
        "label": "Approved",
        "variant": "success"
      }
    }
  ]
}

See the Cards API for full patch details.