訊息生命周期狀態與低到達率對策手冊

訊息生命周期狀態與低到達率對策手冊。

API 接受與初始排隊狀態

當 API 客戶端將 SMS 請求提交至訊息端點時，平台會執行語法驗證與帳戶餘額授權。無論發送交易型 OTP 警示或行銷通知，目標號碼皆須嚴格遵守 E.164 國際格式(例如 +886 區碼開頭)。在將訊息移入狀態機之前，系統引擎會驗證帳戶是否維持所需的 20 美元預付低標門檻(USD 20 floor)。若預付錢包餘額低於此門檻，API 會立即拒絕請求並回傳特定錯誤碼，防止潛在的帳戶透支與服務中斷。

處理狀態與電信商交接機制

一旦完成排隊，內部調度程式會將記錄轉移至外發調度管線。在此階段，引擎會評估目標路由規則、寄件者識別碼合規性及網路可用性。同時，系統會嚴格執行當地法規要求的靜音時間(quiet hours)防護機制，自動攔截或排程在非打擾時段發出的行銷訊息。若外發流量需要專用寄件者身分，系統會執行即時配置，將可用位址連結至工作階段，且不會產生手動供應延遲。

非同步 DLR 轉換與錯誤代碼

從 '已發送' 轉換為最終終端狀態的過程，是透過傳入的交付報告 (DLR) 非同步進行的。下游行動電信商會回傳狀態收據，顯示如 '已交付'、'未交付' 或 '失敗' 等結果。在訊息傳遞架構中，DLR 與 Webhook 回呼被視為最終真實來源(single source of truth)。若手機關機或無法接通，DLR 將保持掛起狀態，直到電信商重試計時器逾期並返回具體錯誤代碼為止。

預付帳本凍結與平台閾值

每個狀態轉換皆直接連結至財務帳本事件，包含號碼的每月定期成本與簡訊發送費。初始提交會根據目標前綴費率與簡訊片段計數觸發預付錢包額度暫掛凍結。當收到終端 DLR 時，系統會結算實際費用並釋放多餘的凍結金額。若訊息最終發送失敗，系統會根據原因自動將預扣資金退款至可用餘額，確保資金管理完全透明，同時嚴格維護 20 美元餘額底線。

狀態機可觀測性與 Webhook 整合

將狀態追蹤整合至客戶應用程式邏輯中，需要設定即時 HTTP Webhook。隨著訊息從排隊轉移到已發送，最後到達 DLR 回條，平台會發送包含訊息識別碼、狀態時間戳記與錯誤原因的已簽署回呼。此外，當終端使用者回覆 STOP 等關鍵字時，系統會觸發即時退訂同步(opt-out sync)，自動更新全局黑名單資料庫，以防後續不合規訊息被誤發。

相關閱讀: 佇列中的訊息應凍結資金而非直接扣除發送額度 · 佇列中與已發送：IOSOR 中的單一訊息路徑 · 首次扣款前的預付資金保留.

從 IOSOR 開始

請開啟 IOSOR 主控台，將系統的訊息請求處理常式直接對應至狀態機的回呼端點。請確保應用程式邏輯會在更新內部訊息記錄狀態（從排隊中轉為已發送）之前，先驗證網路鉤子簽章。請針對模擬的非同步交付狀態回報酬載來測試事件處理常式，以確認帳本保留能在不阻塞並行請求的情況下進行核對。

IOSOR 要點

訊息處理運作如同一部具決定性的有限狀態機，其中每個轉換都反映了已驗證的技術事件，而非抽象的遞送指標。從初始 API 提交與佇列驗證，到電信商交接與最終的非同步交付狀態回報回呼，隔離狀態機制能提供事件管線與錯誤對應的完整能見度。

請建構將每個狀態轉換視為以已簽署網路鉤子收據與帳本保留為後盾之嚴格合約的應用程式邏輯。切勿將狀態機執行與遞送率調校混為一談——請將生命週期狀態追蹤視為基礎架構中的可靠管線。