停止 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 投遞與復原限制