所有文章
    SMSDevelopersAPI

    可編程 SMS API:真正重要嘅整合細節

    決定一個 SMS API 整合可唔可以長期維護嘅關鍵決定:request 契約、幂等性、編碼、status mapping、webhook 處理、retry 同退出能力。

    Flowstates Team·客戶 messaging operation2026年5月20日 · 9 分鐘閱讀

    保持穩定嘅內部契約,唔好直接叫供應商 SDK

    最重要嘅早期決定係應用程式碼會唔會直接叫供應商 SDK。較好嘅做法係定義一個內部契約:發送 request 帶目的地、訊息內容或 template、traffic class、發送方標識同客戶端 reference;狀態 callback 帶返呢個 reference、規範狀態同規範原因,供應商原始 payload 只係用嚟 debug。所有供應商專屬嘅細節都封裝喺 adapter 層背後。

    認證、客戶端 reference 同幂等性

    憑證應該放喺 secret manager 度,並且支援唔使停機嘅輪換。每條訊息喺提交之前都要生成自己嘅客戶端 reference 並儲存,因為最棘手嘅失敗情況係 request timeout——訊息可能已經發送、已經送達,亦可能冇。應該優先用供應商支援嘅 idempotency key,其次係按 reference 查詢,最後先係針對每個 traffic class 嘅明確 policy。

    發送方標識同 traffic class

    發送方標識唔係發送時隨便填嘅字串,而係要睇目的地市場嘅已註冊字母數字發送方 ID、長號碼或短碼,註冊週期通常以週計。traffic class 一定要係每次發送嘅必填欄位,因為佢決定發送方揀選、路由同限速。

    編碼同分段

    SMS 內文用 GSM-7(單段 160 字元)或者 Unicode(單段 70 字元)編碼,一個字元就可以令成條訊息切換去 Unicode,改變計費段數同送達行為。段數計算應該喺提交之前完成,並喺 template 儲存時驗證。

    規範狀態映射、webhook 同 retry

    供應商嘅狀態同錯誤應該對應去一個自己擁有嘅細規範集合,保留原始值用嚟 debug,並對未映射嘅值發出告警。Webhook 需要驗證簽名、防重播、容忍重複同亂序到達、異步處理,仲要配合定期對數任務。Retry 策略應該由一個地方統一決定,設定有限次數同硬性限期。

    吞吐量、結果量度同退出能力

    吞吐量需要按路由限速排隊,並按 traffic class 分開隊列。送達回執係結果嘅弱代理指標,更啱用貫穿業務事件、發送、callback 同 click 嘅 correlation ID 喺應用層量度結果。退出能力係可以驗證嘅:可唔可以透過配置將某個國家、渠道或 traffic class 切換去另一個供應商,程式碼裡面有冇殘留供應商專屬嘅狀態字串或者 SDK 類型,有冇保存可以匯出嘅訊息歷史、consent 同 suppression 記錄。

    Flowstates 提供訊息路由,亦可以營運呢度講嘅呢一層;客戶都可以透過 BYOV 保留自己嘅供應商合約,或者用混合模式,統一喺一個合約同一個營運負責人之下。

    SMS 嘅安全邊界

    普通 SMS 並唔係端到端加密,訊息內容喺送達鏈路嘅中間環節係可見嘅,並以明文形式存喺手機度。絕對唔應該發送密碼、完整帳戶資料或者有長期存取權限嘅憑證;一次性驗證碼應該保持短時效、綁定 session,並對發放同驗證都做限速。

    想一齊梳理你嘅 messaging stack?

    預約一次 30 分鐘 review。冇 sales deck,我哋會睇你現有 setup,指出 operation risk 喺邊度。