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). Interactivity comes in a later phase: in v1, Ketvia removes actions blocks and button or select accessories from messages posted through the Web API or an incoming webhook.

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).