> ## Documentation Index
> Fetch the complete documentation index at: https://developers.workchats.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Blocks

> Rich message layout, and how it rolls out

`blocks` let you send a richer layout than plain `text` — a title, a
label/value grid, buttons — on top of the required `text` fallback. Blocks
ship in stages:

| Phase | What happens |
| - | - |
| **Now** | `blocks` are validated and stored on the message. People see `text`; clients don't render blocks yet, and push notifications always use `text`. |
| **Next (Phase 1b)** | Workchats clients (web, desktop, mobile) render the six block types below. Link buttons work. Action buttons stay hidden — no card shows a dead button. |
| **Later (Phase 2)** | Action buttons become clickable and send an `interaction` callback. See [Callbacks & signature verification](/guides/callbacks-and-signature-verification). |

Always send `text`. It's what people and push notifications see until
rendering ships, and it stays as the fallback after.

## Block types

At most 50 blocks per message, 16 KB total. An unknown type or a field a
type doesn't accept returns `400 invalid_blocks`.

<AccordionGroup>
  <Accordion title="header">
    ```json theme={null}
    { "type": "header", "text": "New lead from Meta Lead Ads" }
    ```

    A bold title line.
  </Accordion>

  <Accordion title="section">
    ```json theme={null}
    { "type": "section", "text": "**Sarah Chen** · Head of Ops at **Acme Ltd**" }
    ```

    A body paragraph. `text` supports a Markdown subset: `**bold**`,
    `_italic_`, `[label](url)`, and line breaks.
  </Accordion>

  <Accordion title="fields">
    ```json theme={null}
    {
      "type": "fields",
      "fields": [
        { "label": "Email", "value": "sarah@acme.com" },
        { "label": "Campaign", "value": "Meta Lead Ads (Paid)" }
      ]
    }
    ```

    A two-column label/value grid. 1 to 10 fields.
  </Accordion>

  <Accordion title="actions">
    ```json theme={null}
    {
      "type": "actions",
      "elements": [
        { "type": "button", "text": "Open in Leadey", "url": "https://app.leadey.ai/dashboard/leads/lead_mul0oe5wo0dgol", "style": "primary" },
        { "type": "button", "text": "Claim", "action_id": "lead.claim", "value": "lead_mul0oe5wo0dgol" }
      ]
    }
    ```

    A row of 1 to 5 buttons. Each button is either a **link** (`url` — opens in
    the browser, no callback) or an **action** (`action_id` + optional `value` —
    sends an `interaction` callback once clicks ship in Phase 2). Never both on
    the same button. `style` is `primary`, `danger`, or omitted.
  </Accordion>

  <Accordion title="context">
    ```json theme={null}
    { "type": "context", "text": "Leadey · Corpwise · just now" }
    ```

    A small grey footer line.
  </Accordion>

  <Accordion title="divider">
    ```json theme={null}
    { "type": "divider" }
    ```

    A horizontal rule. Takes no other fields.
  </Accordion>
</AccordionGroup>

Full field-level schema on [Block types](/reference/block-types).

## Editing

`PATCH /v1/messages/{id}` replaces the whole `blocks` array — there's no
partial update. Leaving `blocks` out of an edit clears them.