` arrives as a code block ("it came out as code"), and columns padded with spaces or separated by `|` arrive as ragged text on a phone.
- **`sendRichMessage` can.** It takes `chat_id` (plus `message_thread_id` in a forum topic, exactly as for a reply) and `rich_message` — a JSON object carrying **exactly one** of `html`, `markdown` or `blocks`.
- **Use `html`.** A Markdown table renders too, but it is fragile: in the same workspace a working Markdown table turned back into plain text as soon as a summary line and emoji were added above it. The HTML form survived every later edit:

```html
Sales, 14 Oct
Total 1 245 300 ₸, margin 4.0%

Product
Qty
Revenue
Margin
Sugar 50 kg
12
318 000
3.1%
🔴 Oil 4.5 l
40
390 000
−1.2%

```

```python
import html, json, urllib.parse, urllib.request
cell = lambda v: f"{html.escape(str(v))}"   # escape every value you insert
body = urllib.parse.urlencode({
    "chat_id": chat_id,
    "rich_message": json.dumps({"html": report_html}, ensure_ascii=False),
}).encode()
req = urllib.request.Request(f"https://api.telegram.org/bot{token}/sendRichMessage", data=body, method="POST")
with urllib.request.urlopen(req, timeout=30) as r:    # ONE attempt — see step 5 above
    res = json.loads(r.read().decode())
if not res.get("ok"): raise SystemExit(res.get("description"))
```

What a table can and cannot do:

- **No colours.** There is no row or cell colour. Mark a row that needs attention with an emoji (🔴, ⚠️) and ``.
- **Cells take inline formatting only** — ``, ``, ``, a link. No lists or line-broken paragraphs inside a cell.
- `` attributes: `bordered`, `striped`, `compact`; a `
`; `colspan`/`rowspan`/`align`/`valign` on a cell. Around it: `
`–`
`, `
`, ``, ``, lists, `
`, `
` for a collapsible section.
- **Limits:** 32 768 UTF-8 characters of text, **500 blocks** (every table row counts as one), **20 columns**, 16 levels of nesting. A phone screen is narrower than that: past 6–8 columns, split the report into two tables or two messages rather than adding a 13th column.
- **Escape what you insert.** A product name containing `<` or `&` breaks the whole message; run each value through `html.escape` (Python) before putting it in a cell.
- **Not idempotent either.** The same rule as step 5: one attempt, and on a network error report it rather than resending — a retried report is a duplicated report.
- Before scheduling it, send it once to the person who asked and get a "yes, that's the layout". Columns are a business question (wholesale vs retail, per box vs per unit, which cost), and they are cheaper to settle before the schedule runs twice a day.

The full syntax is Telegram's own page: `https://core.telegram.org/bots/api/rich-messages` (append `.md` for a plain-text copy).

## Sending on a schedule (reminders & automations)

Everything above is for *replying* to incoming messages. A **scheduled task** that proactively sends a Telegram message (a daily reminder, a nightly report) is a different job with one failure mode to avoid: a scheduled agent can finish a run *believing* it sent a message without actually sending one. Build these so the send is a single, unavoidable command.

**1. Give the space one reusable send script.** Its only job is to send (and record a row, if this channel keeps a history). Save the bot token once in the vault as a shared item named «Telegram bot» (step 1 above); an older space may still hold `scripts/telegram/token.json` as `{"botToken":"…"}`, which the script falls back to. Then create `scripts/telegram/bot/send-message.py`:

```python
#!/usr/bin/env python3
import argparse, json, os, pathlib, sys, urllib.parse, urllib.request
from datetime import datetime, timezone
ROOT = pathlib.Path(__file__).resolve().parents[3]
TOKEN = ROOT / "scripts/telegram/token.json"
# Absent = this channel keeps no message history, and this script writes nothing.
HISTORY = ROOT / "scripts/telegram/history.json"   # {"table": "telegram_messages"}

def record(row):
    if not HISTORY.exists(): return
    table = (json.loads(HISTORY.read_text()) or {}).get("table")
    env = {k: os.environ.get(k) for k in
           ("PLANK_API_URL", "PLANK_INTERNAL_API_KEY", "PLANK_WORKSPACE_ID", "PLANK_USER_ID")}
    if not table or not all(env.values()): return
    url = (f"{env['PLANK_API_URL']}/internal/workspaces/{env['PLANK_WORKSPACE_ID']}"
           f"/app-data/{urllib.parse.quote(table)}/bulk-insert")
    data = json.dumps({"rows": [row], "onConflict": "ignore"}).encode()
    req = urllib.request.Request(url, data=data, method="POST")
    req.add_header("Authorization", f"Bearer {env['PLANK_INTERNAL_API_KEY']}")
    req.add_header("X-On-Behalf-Of", env["PLANK_USER_ID"]); req.add_header("Content-Type", "application/json")
    try:
        with urllib.request.urlopen(req, timeout=30) as r: r.read()
    except Exception as e:
        print(f"history not recorded: {e}", file=sys.stderr)   # never fail a sent message over its record

def bot_token():
    # The vault first (Credentials, item "Telegram bot"), then the env var, then
    # the token.json an older space may still hold.
    try:
        from plank_vault import get
        return get("Telegram bot")
    except Exception:
        pass
    if os.environ.get("TELEGRAM_BOT_TOKEN"): return os.environ["TELEGRAM_BOT_TOKEN"]
    return json.loads(TOKEN.read_text()).get("botToken")

def main():
    p = argparse.ArgumentParser()
    p.add_argument("chat_id"); p.add_argument("text")
    p.add_argument("--thread-id"); p.add_argument("--event-type", default="scheduled_message")
    a = p.parse_args()
    tok = bot_token()
    payload = {"chat_id": a.chat_id, "text": a.text, "disable_web_page_preview": "true"}
    if a.thread_id: payload["message_thread_id"] = a.thread_id
    body = urllib.parse.urlencode(payload).encode()
    req = urllib.request.Request(f"https://api.telegram.org/bot{tok}/sendMessage", data=body, method="POST")
    with urllib.request.urlopen(req, timeout=30) as r: res = json.loads(r.read().decode())
    sent = res.get("result", {}) if res.get("ok") else {}
    if sent.get("message_id"):
        # Telegram's 'date' is a Unix second; the column is a timestamptz.
        at = datetime.fromtimestamp(sent.get("date") or 0, timezone.utc) if sent.get("date") else datetime.now(timezone.utc)
        record({"provider_message_id": f"{a.chat_id}:{sent['message_id']}", "chat_id": str(a.chat_id),
                "direction": "out", "sent_at": at.isoformat(), "body": a.text})
    print(json.dumps(res, ensure_ascii=False)); return 0 if res.get("ok") else 1
if __name__ == "__main__": sys.exit(main())
```

It takes the message as an argument and always sends. If — and only if — this channel keeps a message history, it also writes its own `direction:"out"` row, keyed on the id Telegram just gave the message, so a schedule never has to hand-build a send or a separate recording step. With no `scripts/telegram/history.json` it records nothing, which is the default. A record that fails never fails the send: the message went out, and saying otherwise would make a schedule retry it.

**2. Write the schedule's prompt so the send IS the task.** The assistant still composes the message; it just has to finish by running the command. In the `create_schedule` prompt:

- name the **exact command** to run: `python3 scripts/telegram/bot/send-message.py  '' --event-type `
- say plainly: **"Sending the message IS the task. Actually run the command. Never use a dry run."**
- put any *condition* before the send ("if there are no open items, send nothing to that group"), never as a way the whole run can end without sending.

Good — the send is an explicit command:

> Every day at 09:00, read `telegram/todo.md`, compose a short Russian summary of the open items, then send it: `python3 scripts/telegram/bot/send-message.py -1001234567890 '' --event-type daily_reminder`. Sending it IS the task — actually run the command, never a dry run.

Avoid — "how to send" is left undefined:

> Every day at 09:00, send a reminder of open items using the Telegram bot token.

A scheduled agent given the vague version will often read a few files, decide it's "done," and never send anything.

**3. Never give a scheduled send script a `--dry-run`/preview flag.** If one exists, a scheduled run will often take it and send nothing. A send script should send.

## Good to know

- **Your bot's @username is public and cannot be hidden.** Anyone can start a chat with it. The allowlist from Step 2 is the only thing stopping a stranger's message from reaching an assistant that can read your files — set it before you share the bot's name with anyone.
- **Adding someone to a group does not give them a private line to the bot.** Group members can also DM your bot directly, and that DM is a *different* chat with a different id. If you want a colleague to be able to message the bot privately too, ask the assistant to add their DM chat to the allowlist as well.
- **For groups, privacy must be disabled (and the bot re-added) to read all messages**; DMs need nothing.
- **Who the assistant answers.** To add someone, ask the assistant — it finds the chat among those that recently messaged the bot and adds it; you never need a chat id. To remove someone, open the trigger's page (**Agents** → **On an event** → the trigger) and tap **Remove** under **Who it answers** — only you can shrink the list, so neither the assistant nor a crafted incoming message can do it. To switch the bot to answering everyone, delete the trigger on that page and set the channel up again. The same page has the on/off switch, and the assistant can pause it or change its standing instructions when you ask.
- **Rotate the token if it leaks.** Anyone with the bot token can read and send everything the bot can. Send `/revoke` to @BotFather, then ask the assistant to re-wire with the new token.

See also: [Automations](/help/automations) for the schedules-and-triggers overview, and [Connecting WhatsApp](/help/connecting-whatsapp) for the same setup on WhatsApp Business.