什麼是社群媒體排程 API？

社群媒體排程 API 讓其他系統把準備好的內容送進發布 queue，發布到 Instagram、Threads、Facebook Pages、Bluesky、TikTok 或 YouTube 等頻道。

但實用的 API 不只是 POST /posts。實際排程工作包含帳號連接、權限、media 規則、排程時間、重試、失敗原因、Webhook 與狀態查詢。

簡單說：

社群排程 API 管理的是發布工作的生命週期，而不只是第一個 request。

為什麼不直接呼叫各平台 API？

如果範圍很窄，直接呼叫原生平台 API 可能合理。只需要一個平台，而且團隊能維護 integration，這可能是正確選擇。

支援多個頻道後，難度會增加：

• OAuth 連接與 token refresh
• provider 之間的帳號、page、profile mapping
• 圖片、影片、carousel、link preview 規則
• 排程時間與時區
• rate limit 與 provider 故障
• 某個頻道成功、另一個頻道失敗的 partial failure
• provider post ID 與發布歷史
• 將結果送給其他系統的 Webhook

因此 scheduling API 應吸收重複的營運工作，而不只是包裝原生 endpoints。

最小組成

實用 API 至少需要：

• 帳號連接
• 穩定 payload，包含文字、media、連結、頻道與時間
• 可行時在執行前進行驗證
• 狀態模型：accepted、queued、publishing、published、failed
• idempotency，避免重複發文
• 給外部系統的 Webhook
• 可行動的失敗原因，指出 token、media、policy 或 rate limit

缺少這些，API 看起來簡單，但真正工作會回到操作人員身上。

狀態是核心

accepted -> queued -> publishing -> published
                              -> failed

• accepted：API 已保存通過驗證的工作。
• queued：job 正等待時間或 worker。
• publishing：正在呼叫 provider。
• published：provider 接受發布。
• failed：權限、media、rate limit 或 provider 讓 post 停止。

如果不分這些狀態，「API request 成功」很容易被誤解成「post 已發布」。

為什麼 Webhook 重要

如果 CMS、AI 工具、內部 dashboard 或客戶系統需要結果，有兩種選項。

Polling 會一次又一次查詢狀態。容易開始，但很吵，而且通常知道得太晚。

Webhook 則在狀態改變時送出 event。

{
	"type": "content.publish.failed",
	"brandRef": "acme",
	"contentId": "cnt_123",
	"sns": "instagram",
	"reason": "MEDIA_VALIDATION_FAILED"
}

Webhook 重要，因為自動化通常是一條鏈：AI 準備內容，API 接受工作，scheduler 稍後發布，另一個系統需要結果。

Ankk 的看法

Ankk 將社群排程視為 dashboard、CLI、API 與簽署 Webhook 共用的一個營運流程。

ankk contents publish --brand-ref acme --file payload.json

這個 command 應代表「Ankk 已接受發布工作」，而不是「provider 已經發布」。真正的 provider 發布稍後發生，並應透過狀態變化可見。

請參考 Ankk CLI/API 指南與Ankk 價格中的 API/Webhook 範圍。

檢查表

比較 scheduling API 時，請確認：

• 是否區分 request accepted 與 provider published？
• 是否能查詢目前狀態？
• 失敗原因是否可行動？
• 是否避免重複 post？
• 是否能送出 Webhook？
• 是否保留各頻道限制？
• 價格是否符合頻道數與自動化量？

有 API 只是開始。營運問題是：這個 API 是否足夠清楚地顯示發布生命週期，讓你能信任它。