停止 UnifyPort 訊息帳戶連線：避免自動復原程序重新啟動

如要暫時停止 UnifyPort 訊息帳戶的連線而不刪除帳戶，可向 POST /v1/accounts/{account_id}/runtime/stop 提交 {}。確認 runtime_status: stopped 才代表停止完成；stopping 仍需繼續核對。呼叫前，先讓應用程式的自動復原程序知道這是計劃停機，否則它可能會重新啟動連線。

重點

• 停止 runtime 會保留訊息帳戶，不等於刪除帳戶。
• 先持久化應用程式端的停機意圖，再停止連線。
• 實際 runtime_status 與是否允許復原，是兩個判斷。
• 恢復連線不代表停機期間的訊息已補齊。

正確的復原動作，也可能在錯誤時間執行

假設操作員為維護而停止訊息帳戶，健康檢查程序讀到 stopped，隨即按「保持在線」規則呼叫 start。兩個請求各自都可能符合 API 契約，卻與操作員的意圖衝突。這是設計情境，並非客戶事故紀錄。

解法不是重新登入，而是讓應用程式共同判斷帳戶目前是否應該在線。訊息帳戶執行狀態復原指南 處理的是本應在線卻發生故障的連線。計劃停機需要在該邏輯前加入控制條件。

這不是新的 API 設定。帳戶生命週期文件 分開定義帳戶 status、認證狀態及 runtime_status。本文的停機紀錄屬於應用程式自己的資料，不是 UnifyPort 新欄位，也不能推斷修改帳戶 status 就會提供相同行為。

先選擇真正需要停止的層級

目標	適合的控制方式
暫停 CRM 寫入或 AI 處理，但繼續接收訊息	暫停應用程式的消費者程序
停止此帳戶的即時連線，保留帳戶	Stop runtime
永久退役訊息帳戶資源	獨立的帳戶刪除流程

如只需維護下游系統，先參考 webhook 維護方案比較。停止連線不是可靠的訊息緩衝機制。

只有確實要退役時，才進入 帳戶刪除流程。停止 runtime 的契約不承諾退款、暫停訂閱、刪除原生平台帳戶或清除已儲存訊息。

先讓工作程序看見停機意圖

建議採用以下應用程式流程：

1. 確認工作空間、account_id、渠道、操作員及原因，分別讀取帳戶和認證狀態。
2. 持久化該帳戶的本地停機決定。自動復原及排程傳送程序都應在發出新請求前檢查。
3. 協調已執行的工作。剛寫入的標記不能取消已提交的 API 請求；使用自己的單帳戶協調機制，核對進行中的操作。
4. 保持 webhook 接收端可用，繼續驗證及儲存仍然到達的事件。不要將停止 runtime 視為 webhook 投遞已全部排空。
5. 提交一次經確認的停止請求，再檢查結果。

以下是應用程式偽代碼，不是 SDK 語法或新增端點：

自動執行 start 或 reconnect 前：
    讀取帳戶目前的本地運行意圖
    如操作員已要求暫停：
        不發出復原請求
    否則：
        檢查認證及 runtime 狀態
        選擇文件支援的復原動作

所有復原入口都要遵守相同條件，包括延遲工作和手動復原按鈕。協調暫停與恢復變更，避免舊啟動工作因之後一次畫面操作就重新取得執行資格。

停止一次，再核對實際結果

Stop runtime 參考文件 規定請求內容為空 JSON 物件。以下範例未實際執行；變數應來自後端已確認的帳戶選擇及受保護的 API 金鑰設定：

curl -X POST \
  "https://api.unifyport.ai/v1/accounts/${UNIFYPORT_ACCOUNT_ID}/runtime/stop" \
  -H "X-Api-Key: ${UNIFYPORT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

金鑰只留在伺服器端。記錄 HTTP 狀態與可取得的請求診斷資料，不記錄機密資料。

觀察結果	判讀及下一步
runtime_status: stopped	連線層停止完成；保留本地停機決定
runtime_status: stopping	正在轉換狀態，繼續核對
逾時或無法讀取回應	結果未知；再次修改前先讀取狀態
本地仍要求暫停，runtime 卻變為 running	排查競爭的 start 或 reconnect 路徑，不宣告維護準備完成

透過 讀取帳戶 或 刷新執行狀態 核對。Refresh 是同步狀態，不是重新啟動。在應用程式內設定有界的檢查與升級處理策略，不假定固定完成期限。

不要等待公開目錄未定義的 account.stopped 事件。生命週期文件指出，account.status.updated 不保證涵蓋每次請求觸發的狀態轉換。收件箱沒有新訊息也不是停止完成的證據。

將恢復視為獨立的確認操作

恢復前，繼續限制傳送工作並檢查帳戶的認證狀態。如需用戶操作，繼續對應認證流程；認證成功通常會自動啟動 runtime，因此不要在停機期間無意中重新認證。

如認證仍有效而 runtime 已停止，使用 Start runtime。讓這次明確恢復與本地控制協調一致，核對至實際 running；starting 不代表完成。

放行積壓工作前，檢查每項工作是否仍適合執行。傳送一則受控測試訊息，追蹤新事件的簽章驗證及儲存，再恢復相應消費者程序和自動復原策略。

UnifyPort 的非官方介面不保證重播錯過的資料，也不提供通用 REST 訊息歷史讀取 API。將停機區間記為可能的收集缺口。新訊息測試成功只能證明目前路徑恢復，不能證明缺口已補齊。

常見問題

Stop 會刪除訊息帳戶嗎？

不會。文件明確說明會保留帳戶，再次啟動是另一個動作。

健康檢查程序應啟動所有 stopped 帳戶嗎？

不應該。先確認應用程式是否希望該帳戶在線；實際狀態不能代表操作員意圖。

停止成功會取消排隊回覆或 webhook 投遞嗎？

不能如此推斷。應用程式工作需獨立管理，公開契約不承諾取消已提交工作或排空 webhook。

停止連線會暫停計費嗎？

runtime stop 契約沒有這項承諾，不應用連線狀態作為財務變更的證據。

下一步及來源

依照 Stop runtime 實作本地復原控制。建議測試競爭的復原程序、進行中的啟動、遺失的停止回應、stopping、明確恢復和過期的排隊回覆。這些是待執行驗收項目，不是已通過的結果。

資料核對日期：2026-11-04。

• UnifyPort：Stop runtime
• UnifyPort：帳戶生命週期
• UnifyPort：Webhook 投遞與復原限制