Text and formatting

Format a message with a list of entities, or with a small subset of HTML. Both end up as the same entities, which the app renders.

Length#

Message text: 1–4,096 characters (Unicode code points), after HTML parsing.
Captions of photos, videos and documents: up to 1,024 characters.
At most 100 entities per message.

Entities#

{"chat_id": 4503600212045337,
 "text": "Order #4411 is on its way. Track it",
 "entities": [{"type": "bold", "offset": 0, "length": 11},
              {"type": "text_link", "offset": 27, "length": 8, "url": "https://shop.example.com/t/4411"}]}

offset and length count UTF-16 code units, as in Telegram: an emoji outside the Basic Multilingual Plane counts 2. JavaScript string indexes already are UTF-16; in Python use len(s.encode("utf-16-le")) // 2.

type	Notes
`bold`, `italic`, `underline`, `strikethrough`, `spoiler`
`code`	Inline code. Nothing may be nested inside.
`pre`	A code block; optional `language` (`[A-Za-z0-9_+#.-]{1,32}`). Nothing may be nested inside.
`text_link`	`url` required: `https://`, a host, no user name or password, at most 2,048 characters.
`url`, `mention`, `bot_command`	Marks text that already is a URL, an `@handle` or a `/command`.

Rules: every entity lies inside the text and has a length of at least 1; two entities either do not overlap, or one contains the other; unknown types are refused. Any violation answers 422 invalid_entities.

Entities in messages people send are not passed on, except the leading bot_command and any mentions, which Qivuna computes for you.

HTML#

{"chat_id": 4503600212045337, "parse_mode": "HTML",
 "text": "<b>Order #4411</b> is on its way. <a href=\"https://shop.example.com/t/4411\">Track it</a>"}

Tag	Entity
`<b>`, `<strong>`	bold
`<i>`, `<em>`	italic
`<u>`	underline
`<s>`	strikethrough
`<code>`	code
`<pre>`	pre (no language in HTML mode)
`<a href="https://…">`	text_link (`href` is the only attribute, https only)
`<span class="spoiler">`	spoiler

Other tags, other attributes, unclosed tags and stray < or > are refused (422 invalid_entities): write them as < and >.
HTML character references (&, ", …) are decoded.
Send entities or parse_mode, not both. "HTML" is the only parse mode.

Content rules#

Everything a bot publishes in plaintext — messages, edits, button labels and URLs, captions, file names, descriptions and moderation reasons — passes Qivuna's anti-phishing check before anything is stored. It refuses:

asking for verification, login or SMS codes, passwords or PINs, in English or Hebrew;
asking for wallet seed or recovery phrases (“12 words”) or private keys;
links to hosts that imitate Qivuna (any host whose name reads as “qivuna” or “qivbot” other than qivuna.com itself).

The check sees through look-alike letters, spacing and invisible characters. The answer is 422 content_blocked with the message “This message cannot be sent.” and never says which rule matched. Each refusal adds a strike to the owner's account, at most one a day; strikes slow down quota growth and block verification. Bots must never ask people for such secrets — see the Developer Terms.