deliver-format-fallback

name

deliver-format-fallback

description

Use when sending markdown/rich-text formatted messages through a strict wire-format channel API (Telegram, Slack, Discord, SMS/WhatsApp). Triggers — hardening a bot reply path, a message that "sometimes doesn't arrive", or literal *asterisks*/backticks showing in delivered messages. On any parse/entity 4xx, retry with a degraded payload so a malformed render never silently drops a reply on a critical notification channel.

Deliver-Format Fallback

Overview

Strict-wire-format channel APIs (Telegram parse_mode, Slack mrkdwn, Discord markdown) reject a message whose formatting doesn't parse (unbalanced *, an unescaped _ in an identifier). If you treat that 4xx as a hard failure, the reply is dropped whole on a critical notification channel. Degrade the payload, don't drop it.

When to use

• Rendering markdown/rich text into a channel send (sendMessage with parse_mode, Slack blocks, Discord embeds).
• A reply "sometimes doesn't arrive," or delivered messages show literal *asterisks*/backticks.

The core rule

On the channel's SPECIFIC parse/entity-error signature, retry with a more-degraded representation — most-faithful-first — and only treat it as a real failure after the plain-text attempt.

def send_rich(client, base_payload, raw_text):
    # 1. try formatted (rendered)
    resp = client.post(url, json={**base_payload, "text": render(raw_text), "parse_mode": "HTML"})
    if resp.status_code < 400:
        return resp
    # 2. parse error -> resend RAW, no parse_mode (can't fail on entities) => never dropped
    return client.post(url, json={**base_payload, "text": raw_text})

Escalation chain: (1) fully formatted → (2) re-escape reserved chars, retry once → (3) strip parse_mode/formatting, resend raw → only THEN a real send failure feeding your durable-delivery path.

Guardrails

• Detect the SPECIFIC signature (Telegram: 400 + description can't parse entities). A 403 (permissions) or 429 (rate-limit) needs backoff/alert, NOT a format downgrade.
• Cap at ~2 retries and make each idempotent/replacing (edit-in-place or a single terminal send) — never an infinite or duplicate-send loop.
• Where the platform supports an entities-array (offset/length spans, Telegram), prefer it over parse_mode string-markup — it sidesteps the whole escaping class deterministically.

Common mistakes

• Treating every 4xx as fatal → drop a message that a plain-text resend would have delivered.
• Retrying the SAME formatted payload → same parse error, still dropped.
• A naive parse_mode flip with no fallback → 400s on the _ in identifiers (my_user_name) and drops the message.

Real-world impact

A strict-format messaging API needs this discipline: a render + retry-plain-on-4xx fix renders light markdown but NEVER drops on a malformed entity. This is the send-time partner to channel-adapter-pattern (design-time medium threading) and deliver-durably (crash-survivable outbox). Exa-confirmed against multiple production bots on strict-wire-format channels implementing the exact escape → re-escape → strip-and-resend-plain chain.