Social Automation API 文件：IG／FB 留言自動回覆 REST API

Crescendo Lab 漸強實驗室MCP 設定 →

重點摘要

Base URL 是 https://social-automation.cresclab.com/api/v1，用 Authorization: Bearer 帶 API key。可以列出連結的帳號與近期貼文、建立與更新活動（觸發條件、關鍵字、公開回覆、私訊內容）、啟用或暫停，以及讀取觸發紀錄與每日統計。完整規格在 /openapi.json；要給 AI agent 用，請看 MCP 設定。

快速開始

1. 在後台帳號選單的 API 與 AI 連接 建立 key（選「讀取與修改」）。2. 確認 key 可以用：

bash
curl https://social-automation.cresclab.com/api/v1/me \
  -H "Authorization: Bearer sa_live_YOUR_KEY"

3. 建立活動。沒有帶 status 時一律是草稿，什麼都不會發送：

bash
curl -X POST https://social-automation.cresclab.com/api/v1/activities \
  -H "Authorization: Bearer sa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "ACCOUNT_ID", "name": "+1 → product link", "trigger": "ig_comment", "keywords": [ "+1", "want" ], "public_replies": [ "Sent you a DM 💌", "Check your DMs!" ], "dm": [ { "type": "text", "text": "Here is the link you asked for 👇" }, { "type": "button", "title": "Shop now", "url": "https://shop.example.com/serum" } ], "post_scope": "next_post" }'

4. 確認設定沒問題後啟用。啟用之後，你的帳號會開始公開回覆並私訊真正留言的人：

bash
curl -X PATCH https://social-automation.cresclab.com/api/v1/activities/ACTIVITY_ID \
  -H "Authorization: Bearer sa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"active"}'

認證與權限

  • 每個請求帶標頭 Authorization: Bearer sa_live_...。
  • key 有兩種權限：只能讀取（GET）與 讀取與修改（GET、POST、PATCH、DELETE）。
  • key 代表建立它的人：團隊成員的 key 只能看到、修改被授權的帳號。建立者被停用或離開工作區，key 就失效。
  • 撤銷 key 在後台同一頁，立即生效。

端點

所有路徑接在 https://social-automation.cresclab.com/api/v1 後面。

方法路徑權限說明
GET/me讀取這把 key 所屬的工作區、方案、用量
GET/accounts讀取已連結的 IG／FB 粉專／Threads 帳號
GET/accounts/{id}/posts讀取帳號近期貼文（即時向 Meta 讀取）；?kind=story 讀限動
GET/activities讀取活動列表與成效
POST/activities修改建立活動（預設草稿）
GET/activities/{id}讀取單一活動 ＋ 近 14 天趨勢
PATCH/activities/{id}修改更新設定；status 改成 active／paused 即啟用／暫停
DELETE/activities/{id}修改刪除活動與它的觸發紀錄
GET/logs讀取觸發紀錄（誰留言、回覆或私訊成功與否、失敗原因）
GET/stats讀取每日公開回覆、私訊、失敗數

活動的格式

建立活動時必填 account_id 與 trigger，其他都可以省略。更新時只改有帶的欄位，陣列（keywords、public_replies、dm）會整個取代。

json
{
  "account_id": "ACCOUNT_ID",
  "name": "+1 → product link",
  "trigger": "ig_comment",
  "keywords": [
    "+1",
    "want"
  ],
  "public_replies": [
    "Sent you a DM 💌",
    "Check your DMs!"
  ],
  "dm": [
    {
      "type": "text",
      "text": "Here is the link you asked for 👇"
    },
    {
      "type": "button",
      "title": "Shop now",
      "url": "https://shop.example.com/serum"
    }
  ],
  "post_scope": "next_post"
}

觸發類型

trigger平台公開回覆私訊說明
ig_commentinstagram可以可以IG 貼文或 Reels 的留言
ig_storyinstagram—可以IG 限時動態的回覆或提及（post_ids 填限動 id）
ig_liveinstagram可以可以IG 直播中的留言（只在直播進行中觸發）
fb_commentfacebook可以可以FB 粉專貼文的留言，私訊走 Messenger
fb_livefacebook可以可以FB 直播中的留言（只在直播進行中觸發）
fb_messagefacebook—可以粉絲傳到粉專 Messenger 的訊息，用 Messenger 回覆
threads_replythreads可以—Threads 貼文的回覆；只能公開回覆（Meta 沒有 Threads 私訊 API），Beta 陸續開放

私訊內容的三種形狀

  • 文字 ＋ 最多 3 顆連結按鈕：有按鈕時文字最多 640 字，沒有按鈕最多 1,000 字。
  • 單張圖片：一個 image 區塊，不能混文字或按鈕。圖片網址要能直接讀到圖檔（Google 雲端硬碟、Dropbox 的分享頁會被拒絕）。
  • 圖卡輪播：1–10 張 card，每張最多 3 顆按鈕，不能混其他區塊。
這些組合規則會直接擋下，不會像手動設定時悄悄丟掉一部分內容。圖片網址與貼文網址在存檔時會實際檢查，所以建立與更新可能要幾秒。

錯誤與限制

錯誤一律是同一個格式。action_url 是使用者可以解決問題的地方（連結帳號、升級方案、建立 key）：

json
{
  "error": {
    "code": "trial_expired",
    "message": "The 7-day trial has ended. Upgrade the plan to keep creating and activating activities.",
    "action_url": "https://social-automation.cresclab.com/dashboard/workspace"
  }
}
  • 400 invalid_request：欄位不合法，error.field 指出哪一個。
  • 401 unauthorized：沒帶 key 或 key 無效。
  • 403 insufficient_scope／trial_expired／contract_expired／plan_limit。
  • 404 not_found／account_not_found。
  • 429 rate_limited：每把 key 每分鐘最多 120 次，回應帶 Retry-After。

給 AI agent 用：MCP

同樣的功能也以 MCP 工具提供，可以直接接 Claude Code、Cursor、Codex。設定方式見 MCP 設定。

常見問題

有沒有 OpenAPI 規格？

有，在 /openapi.json（OpenAPI 3.1），可以直接貼給 Cursor 或 Claude Code 產生 client。

可以用 API 連結新的 Instagram 帳號嗎？

不行。連結帳號要在瀏覽器完成 Meta 登入授權，請在後台的社群連結頁操作；API 的 connect_url 會帶你過去。

API 有 webhook 通知嗎？

目前沒有。要追蹤觸發結果，請定期讀取 GET /logs。

API 要另外付費嗎？

不用。API 與 MCP 包含在所有方案裡，7 天試用期間也能用。