Telegram 訊息加了格式,怎麼就送不出去了?
通知內容都整理好了,卻卡在最後一步,送到 Telegram 時收到 400。明明只是一段文字,加個標題、放個版本號,怎麼連送出去都成了問題。
我做每日推播的小工具時,就修過這種錯誤。當時開啟了 Telegram 舊版 Markdown 格式,讓文字可以顯示粗體等排版,內容裡的特殊字元卻讓整則訊息被拒收。後來的修正包含兩件事,改用 MarkdownV2,並在送出前把內容轉成它接受的寫法。
光換模式還不夠,文字也得跟著處理。
文字裡的符號,也可能是格式指令
平常看 build_2.0,會覺得它只是個版本名稱。但開啟格式解析後,底線可能有斜體的意思,星號可能是粗體的開始,方括號則可能進入連結語法。程式認為自己在傳文字,Telegram 卻會依照指定的模式,把其中一些符號當成排版指令。
都叫 Markdown,寫法卻不一定相同。Telegram 的 Markdown 是保留相容性的舊模式,MarkdownV2 有另一套規則;平常在 Markdown 文件裡寫的 **粗體**,到了 Telegram MarkdownV2,粗體要用的是 *粗體*。
我這次遇到的錯誤發生在舊模式。改用 V2 後,一般文字裡的底線、方括號、半形句點等符號仍要處理,不能把它當成「比較新,所以什麼文字都吃得下」。完整規則可以查 Telegram Bot API 的 Formatting options。
把要排版的部分和一般文字分開
處理這些符號的方法叫做「跳脫」,也就是在符號前加上反斜線 \,告訴解析器,這裡要顯示符號本身。下面都以 MarkdownV2 解析,第一列保留粗體格式,其餘幾列則把符號當成一般文字。
| 原始內容 | 送給 Telegram 的內容 | 手機上預期看到 |
|---|---|---|
**通知**,想顯示粗體 |
*通知* |
通知 |
build_2.0,只是版本名稱 |
build\_2\.0 |
build_2.0 |
[測試],只是文字標籤 |
\[測試\] |
[測試] |
完成!,保留半形驚嘆號 |
完成\! |
完成! |
表格中間那欄是實際送出的文字,反斜線會在 Telegram 解析時被消耗。寫進程式碼時,還要依照使用語言的字串規則處理反斜線。
我的每日推播需求很少,主要是保留粗體,其他部分當一般文字。所以轉換時先找出粗體段落,把外層的 ** 換成 *,段落內的一般文字照樣跳脫;剩下沒有排版需求的內容,也一起跳脫。這樣既能保留標題的粗體,又不會把版本號裡的底線當成格式。
格式失敗時,再試一次純文字
除了每日推播,我也做了一個透過 Telegram 回覆訊息的聊天工具。在這個工具裡,我多加了純文字補送,先轉成 MarkdownV2 發送;如果發送套件回報 BadRequest 例外,表示這次請求無法處理,就再用原始文字試一次,這次關掉格式解析。
這裡要拿回轉換前的原始文字。如果把已經加滿反斜線的內容拿來當純文字送,Telegram 不會再幫忙消耗那些符號,手機上就會看到 build\_2\.0。粗體標記也可能保留下來,雖然排版比較樸素,至少有機會先收到內容。
被拒絕不全是格式問題,像訊息太長也可能失敗,所以純文字補送只是一次備援嘗試。兩次都失敗時,仍要留下錯誤紀錄,不能把重試當成已經送達。
先用純文字縮小問題範圍
下次碰到這類問題,我會先看錯誤說明,再檢查發送時的 parse_mode,也就是控制格式的設定。把同一份原始內容關掉格式解析後送出,如果成功,就回頭查格式轉換;如果仍然失敗,就繼續查長度、發送目標等其他原因。
修完後,再用包含粗體、版本號和方括號的文字實際送一次,確認訊息有送達,手機上的符號和排版也符合預期。