Blocks reference

Blocks are a JSON array that Ketvia renders natively as a card on web and mobile. A message posted with POST /messages, PATCH /messages/{id} or an incoming webhook can carry blocks next to its text.

text is always required. It is what notifications, search and clients that cannot render a block show, so write it as a complete sentence and do not repeat it in the blocks.

Example

Weekly deploy report

12 deploys to production this week. Details on the status page.

12

Deploys

91.7%

Success rate

€184.50

CI cost

Team

Platform

Week

2026-W40

Service	Deploys
api	7
web	5

• Rollback on Tuesday
  api 2.14.1, 4 minutes

---

Generated by Acme CI

This is a simplified static rendering; the Ketvia clients render the same JSON with the app’s own styles and format numbers in the viewer’s language. A live previewer comes in a later phase.

blocks.json

[
  {
    "type": "header",
    "text": "Weekly deploy report"
  },
  {
    "type": "section",
    "text": {
      "type": "mrkdwn",
      "text": "*12 deploys* to production this week. Details on the [status page](https://status.acme.example)."
    }
  },
  {
    "type": "metrics",
    "items": [
      {
        "key": "deploys",
        "label": "Deploys",
        "value": 12,
        "format": "integer",
        "primary": true
      },
      {
        "key": "success",
        "label": "Success rate",
        "value": 0.917,
        "format": "percent",
        "primary": false
      },
      {
        "key": "cost",
        "label": "CI cost",
        "value": 184.5,
        "format": "currency",
        "currency": "EUR",
        "primary": false
      }
    ]
  },
  {
    "type": "fields",
    "fields": [
      {
        "label": "Team",
        "value": "Platform"
      },
      {
        "label": "Week",
        "value": "2026-W40"
      }
    ]
  },
  {
    "type": "table",
    "columns": [
      {
        "key": "service",
        "label": "Service",
        "align": "left"
      },
      {
        "key": "deploys",
        "label": "Deploys",
        "align": "right"
      }
    ],
    "rows": [
      {
        "service": "api",
        "deploys": "7"
      },
      {
        "service": "web",
        "deploys": "5"
      }
    ]
  },
  {
    "type": "list",
    "items": [
      {
        "title": "Rollback on Tuesday",
        "subtitle": "api 2.14.1, 4 minutes",
        "url": "https://ci.acme.example/runs/881"
      }
    ]
  },
  {
    "type": "divider"
  },
  {
    "type": "context",
    "elements": [
      {
        "type": "plain",
        "text": "Generated by Acme CI"
      }
    ]
  }
]

Limits

Limit	Value
Blocks per message	50
Serialized size	16 KB
Text per field	3000 characters
actions blocks	5
Interactive elements in total	25
blockId (optional, on every block)	^[A-Za-z0-9_.-]{1,64}$

Text

Where a block takes a text object, it is { "type": "plain" | "mrkdwn", "text": "…" }. Other strings are plain text.

mrkdwn is a safe Markdown subset: bold, italic, code, links (https only), lists, and the mentions <@userId> and <#conversationId>, which each viewer’s client resolves under that viewer’s own access. Nothing else is interpreted.

Block types

Type	Fields	Notes
header	text (plain, 1–150)	A title line.
section	text (text object), optional accessory	The accessory can be an image; buttons and selects are interactive (see below).
fields	fields: 1–10 of { label (1–60), value (1–200) }	Label/value pairs, plain text.
metrics	items: 1–4 of { key, label (1–60), value: number, format?, currency?, primary: boolean }	The only block with typed numbers. format: integer, decimal, currency, percent. currency (ISO 4217, for example EUR) is required for currency. Clients format the value in the viewer’s language. key matches ^[A-Za-z][A-Za-z0-9_]{0,39}$.
table	columns: 1–6 of { key, label (1–60), align: left | center | right }; rows: ≤ 20 objects of strings (≤ 200)	Read-only; every row key must be a declared column key.
list	items: 1–20 of { title (1–150), subtitle? (1–300), url? (https) }
context	elements: 1–10 text objects	Small secondary text, such as a source line.
divider	none	A horizontal rule.
image	fileId (uuid), alt (1–200, required)	A Ketvia file only; remote image URLs are not allowed.
actions	elements: 1–5 buttons, selects or overflow menus	Interactive (see below).

Images

An image block or image accessory references a Ketvia file by fileId, and in messages the file must be visible in the same conversation. Upload it first with POST /files (a user token in v1). Remote image URLs are not allowed, so a message can never load content from another server.

Interactive elements

Blocks define interactive elements: button (actionId, text, value, style: default, primary or danger, optional url and confirm; a danger button requires confirm), static_select (up to 100 options) and overflow (up to 5 options). Messages posted through the Web API or an incoming webhook keep these elements only when the manifest declares interactivity; otherwise Ketvia removes actions blocks and button or select accessories.

Validation

The Web API and incoming webhooks validate Blocks and answer 400 validation_error with the path of the first problem. The schema is part of the OpenAPI document (BlockInput).