SosoAPI 設定指南

揀你嘅起點

SosoAPI 將你已經用緊嘅 agent 同社交帳戶連接起來。Agent 幫你寫內容同審稿；SosoAPI 處理受支援嘅帳戶操作、排程同發佈結果。你亦可以喺 App 睇返同一批帖文，或者由自己嘅程式呼叫 API。

呢份指南由一個人、一個社交帳戶開始：連接本機或託管 MCP、揀授權範圍、核對社交帳戶、準備同批准帖文，再查實際結果。進階部分會講 CLI 同 HTTP API。完成設定唔需要發測試帖文。

• 交畀 Claude Code 或 Codex 設定：第 1 步
• 自己設定 MCP 客戶端：第 3 步
• 用終端機或自己嘅後端：第 9 步
• 修復連接：第 10 步

開始之前

你需要支援 MCP 嘅 AI 客戶端、SosoAPI 帳戶，同一個你有權管理嘅社交帳戶。登入頁開啟時可以即場註冊 SosoAPI。先諗定一篇真係想準備嘅內容。

本機 MCP 需要 Node.js 20 或以上、npm／npx，同你揀嘅 AI 客戶端。託管 MCP 需要客戶端支援 remote MCP、OAuth 同自動註冊客戶端，唔使喺電腦安裝 Node.js。可用功能亦可能受客戶端方案同管理員設定限制。

SosoAPI 可以連接 Instagram、Threads、Facebook 專頁、YouTube 同 X。要揀帳戶類型、權限同帖文格式都配合任務嘅帳戶。合資格嘅 Threads 帳戶適合用作第一篇純文字示例；Instagram 同 YouTube 嘅受支援發佈格式需要合適媒體。連接選單有某個平台，唔代表每個帳戶都做到所有操作。

設定時要查指定帳戶嘅可用能力。排程一批帖文之前，先喺 App 查目前方案同配額；X 另有 Organization 共用點數。某個平台用得嘅示例，唔代表其他平台都支援。

• 支援平台
• 發佈能力同帳戶要求

1. 將設定要求交畀你嘅 agent

喺你而家用緊嘅 Claude Code 或 Codex 對話貼上以下要求。

Agent 應先查有冇運作正常嘅 SosoAPI 連接，有就繼續用；冇就跟設定指引做，並話你知幾時需要喺瀏覽器登入或重啟客戶端。預期結果係目前對話用到 SosoAPI 工具；單憑安裝成功訊息未算。之後繼續登入同核對帳戶，或者去第 3 步自己設定。

請跟 https://sosoapi.ai/setup.md 設定 SosoAPI，保留我目前嘅內容同任務。需要時我會自己登入同批准授權。設定期間唔好發佈任何內容。

2. 登入同揀 agent 嘅授權範圍

用你原本打算用嘅帳戶：揀 Continue with Google，或者用電郵註冊並完成驗證。完成畫面上嘅帳戶或 Workspace 設定。如果你加入咗幾個 Workspace，要揀今次品牌或項目所屬嗰個。批准前核對要求嘅 Workspace 同操作，之後返同一個對話繼續。

保留 agent 提供嘅登入連結，等瀏覽器返到等緊批准嘅授權流程。你可以先由 App 開始，再返 agent 對話；唔好將等緊批准嘅連結換成另一條登入連結。

Workspace 角色同平台權限仍然生效：agent 有發佈權限，唔會令 viewer 變成 editor。發佈授權會喺你批准嘅範圍持續有效，SosoAPI 唔會強制每篇帖文再開瀏覽器批准。你要明確要求 agent 喺審稿時停低。一般 OAuth 設定唔需要將社交密碼或 API key 貼畀 agent。

預期結果：以正確身份完成登入，agent 讀到你授權嘅 Workspace。如果開咗錯嘅瀏覽器個人檔案，跟問題排解部分復原。

• 由 SosoAPI App 開始

3. 有需要先手動連接 agent

揀一種連接方法就夠。如果 agent 已經設好而且用到，就跳過呢部分。本機 MCP 要先檢查 Node.js 同 npx；Node.js 必須係 20 或以上。

node --version
npx --version

本機 MCP：Claude Code 或 Codex

只執行你個客戶端對應嘅指令：第一條係 Claude Code，第二條係 Codex。Core profile 包括日常發佈流程。Profile 只改變會顯示邊啲工具，唔會授予權限；已有運作正常嘅 full profile 連接就繼續用。

客戶端要求時先重新連接或重啟，之後核對目前對話用唔用到 SosoAPI 工具。未登入嘅話，第一次需要認證嘅呼叫會啟動瀏覽器登入。

claude mcp add sosoapi -e SOSOAPI_TOOL_PROFILE=core -- npx -y sosoapi

codex mcp add sosoapi --env SOSOAPI_TOOL_PROFILE=core -- npx -y sosoapi

其他本機 MCP 客戶端

客戶端用 mcpServers JSON 嘅話，將以下項目加到現有設定，保留其他 server。用另一種格式嘅客戶端，就喺佢嘅 MCP 設定填返相同 command、args 同環境變數。

{
  "mcpServers": {
    "sosoapi": {
      "command": "npx",
      "args": [
        "-y",
        "sosoapi"
      ],
      "env": {
        "SOSOAPI_TOOL_PROFILE": "core"
      }
    }
  }
}

• 安裝參考同套件選擇

託管 MCP：相容嘅瀏覽器或遠端客戶端

喺客戶端嘅自訂 connector 或 remote MCP 設定，加一個叫 SosoAPI 嘅連接，server URL 用下面網址。如果有相關選項，揀 OAuth 同自動註冊客戶端。登入 SosoAPI、揀容許嘅 Workspace 同操作，再返對話；客戶端要求時啟用連接，叫 agent 核對已授權帳戶。

新託管連接用 https://sosoapi.ai。舊端點 https://gqeshlawtcexsapabaui.supabase.co/functions/v1/remote-mcp 仍然受支援。已有正常運作嘅本機或託管連接就保留，唔使為咗換網址而重新設定。

唔需要貼 API key、client ID 或 client secret。ChatGPT 自訂 MCP app 會受客戶端方案、開發者模式同管理員設定限制。呢度講緊自訂連接，唔係 app 目錄上架。託管 MCP 讀唔到電腦本機檔案；媒體要用公開網址匯入，或者改用本機 MCP 上載本機檔案。

https://sosoapi.ai

• 自訂 OAuth 客戶端註冊同 token 指引

可選：喺終端機檢查登入

本機連接先執行 auth status。只有顯示未登入時先執行 auth login，完成瀏覽器流程後再查一次狀態。指令唔會印出 token。呢個檢查只代表本機 CLI 登入，唔代表另一個託管 connector 嘅登入狀態。

npx -y sosoapi auth status

npx -y sosoapi auth login

4. 連接你嘅社交帳戶

開啟連接帳戶頁，或者用下面本機指令。有需要可以將 threads 換成 instagram、facebook、youtube 或 x。呢個操作只會開啟連接流程，唔會發佈內容。

先核對畫面上嘅 Organization 同 Workspace。揀平台，經平台授權頁登入，再揀指定帳戶、專頁或頻道。完成同意授權，返到 SosoAPI 時完成所需嘅帳戶選擇確認。之後叫 agent 重新讀取指定 Workspace 嘅已連接帳戶。

已有健康連接就繼續用。如果屬於另一個 Organization 或 Workspace，要喺 App 釐清選擇，唔好當一般設定就斷開或搬走。預期結果：正確帳戶出現喺指定 Workspace，並有目前連接健康同能力資料。單憑 callback 成功，未能證明有發佈權限。

npx -y sosoapi connect threads

• 連接帳戶

5. 唔發帖，先核對存取權

喺已連接嘅 agent 對話貼上以下要求。

Agent 可以用 sosoapi_get_workspace_context 同 sosoapi_list_connected_accounts，沿用已知資料，並明確傳入所選 workspace_id。帳戶初始化可能會建立你第一個 Workspace；呢個設定檢查唔會建立社交帖文。

繼續之前，確認 Workspace 同發佈帳戶正確、你嘅角色同 agent 授權容許該操作，以及目的地支援擬用格式。有一項唔符合就去問題排解；重新安裝套件唔會補返欠缺嘅平台權限。

請檢查我嘅 SosoAPI 設定，唔好發佈或排程任何內容。
列出我可以用嘅 Workspace，再列出我揀嗰個 Workspace 嘅社交帳戶。
就我揀嘅帳戶，顯示平台、帳戶名稱、連接健康狀態，同擬用格式嘅發佈能力。
如果有幾個 Workspace 或帳戶都可能符合，先問我揀邊個。
內部 ID 留畀工具呼叫用，唔好叫我自己搵或作出 ID。

6. 準備同批准你嘅第一篇帖文

由一篇真實帖文、一個目的地開始，先填好起草提示入面嘅方括號欄位。Agent 負責寫作；SosoAPI 提供連接同發佈操作。內容聲稱、用字、連結同媒體都要由你親自核對。

未來帖文要指定日期、當地時間同 IANA 時區。遇到夏令時間令同一個當地時間出現兩次，要提交前講明用邊次。呢階段嘅預期結果係一份可供你審核嘅完整草稿，未提交任何發佈要求。

請用 SosoAPI 幫我準備一篇產品公告。

產品：[公開產品名稱]
已核實資料：[今日已經提供嘅功能]
受眾：[幫到邊啲人]
目的地：[帳戶名稱同平台]
語言：[語言]
想用嘅當地日期同時間：[YYYY-MM-DD HH:mm]
時區：[IANA 時區，例如 Asia/Hong_Kong]
媒體：[冇、本機檔案，或者公開媒體網址]

只用我提供嘅事實，並檢查目的地嘅格式要求。
列出完整草稿、媒體、帳戶、日期、時間同時區畀我審核。
暫時唔好排程或發佈。

核准完整帖文後先排程

所有資料都正確先用下面提示明確下達指示。呢一步會建立真實排程，之後可以公開發佈；只用你真係打算發嘅內容同帳戶。即時發佈亦要喺核對同一批資料之後明確要求。

預期結果：取得 Scheduled Post ID、指定帳戶、已接納時間同目前狀態。排程獲接納，唔代表平台已經發佈。

請將以下已批准嘅完整帖文，按指定日期、時間同時區排程到指定帳戶。

[貼上最終內容、媒體、帳戶、日期、時間同時區。]

先查有冇已存在嘅相同排程。只提交一次，然後讀返已儲存結果，回報 ID、目的地、已接納時間同目前狀態。如果結果未明，先查原有要求，再決定下一步。

7. 查結果、改期或取消

叫 agent 用 sosoapi_get_scheduled_post 讀返同一篇 Scheduled Post。你亦可以用有權限嘅帳戶登入，再開 https://app.sosoapi.ai/scheduled-posts/<post-id>。多帳戶要求要逐個目的地核對，因為可能有啲成功，有啲仲需要處理。

請讀取 Scheduled Post [已回傳 ID] 嘅目前結果。
列出目的地、排程時間、目前狀態同發佈結果。
確認已發佈嘅話，有公開連結就一併提供。
唔好重試、改期或另建帖文。

管理未完成帖文，同之後再查

要改未完成帖文，就提供 ID 同新資料。Agent 必須先讀目前版本同可用操作，再用受支援嘅更新或取消功能。可唔可以取消取決於發送階段，開始發送後可能已經唔得。取消排程亦唔會刪除平台上已發佈嘅帖文。

取得未來排程嘅已儲存資料後，你可以離開對話，之後再查返同一篇帖文。除非另外設好相關功能，唔好預期已關閉嘅 agent 對話會自行喚醒或通知你。

8. 加入圖片或影片，再重用流程

先完成單篇帖文流程，再準備大批內容。話畀 agent 知媒體係本機檔案、公開網址，定現有 SosoAPI 素材。

本機檔案：本機 MCP 可以用 sosoapi_upload_asset，檔案必須喺容許嘅上載資料夾入面。路徑超出範圍時，工具會說明可用位置。託管 MCP 讀唔到你電腦嘅檔案。

公開網址：先用 sosoapi_import_asset_url，再用 sosoapi_get_asset_import_status 並設 include_asset=true，等素材準備好。用現有素材亦要核對佢屬於指定 Workspace，而且已適合所選格式。

一般排程要求要一齊用已登記嘅素材 ID 同正式素材 URL；暫時預覽網址或原始外部網址都唔可以代替。受支援嘅單張圖片網址流程，可以用 sosoapi_post_image_url 一次處理匯入同提交。呢個係發佈操作，要先批准完整帖文。處理中要保留已接納嘅帖文 ID，唔好為咗繼續而另開一次匯入。

X 支援無媒體嘅原創 TEXT 帖文，或者 VIDEO：只可以有一個已準備好、已登記嘅 MP4 影片素材，最短 0.5 秒，並符合 500 MiB 上載上限。影片要指定帳戶有已核實嘅 can_publish_video；只有文字權限唔夠。舊連接可能要你批准重新連接，先取得影片上載權限。文字、hashtag 同連結仍要符合 X 嘅加權字數上限。暫時唔支援相片、回覆、引用、轉發或串文發佈。獲接納上載或處理影片，唔等於已發佈。

提交 X 帖文前，用指定 workspace_id 同最終文字讀取 sosoapi_get_x_usage。佢嘅可用點數同成本，跟一般方案配額分開。唔好靠重複提交繞過點數限制；結果未明時要先核實原有發佈，再考慮下一次發送。

準備一批待審內容，同如實讀取成效

第一篇成功之後，可以試下面產品發布提示。你批准完整表格之後，先按方案限額核對成批內容。已接納同被拒嘅目的地要分開回報，並保留每篇已接納帖文嘅身份。

發佈權限同分析權限可以唔同。之後檢視成效時，讀唔到嘅指標要標明未能取得，唔好作成零，亦唔好因為帖文已發佈就推斷所有指標都讀到。

沿用同一個已核實設定，按我提供嘅公開資料準備七篇產品公告草稿，每日一篇。用審核表逐行列出草稿、目的地、媒體、當地日期、時間同時區。全部七篇都先保留做草稿，等我批准完整表格先繼續。

9. CLI 同 API 實作步驟

想明確控制要求檔案，或者做後端整合，就用呢條可選路線；一般 agent 用戶可以跳過。示例沿用 MCP 嘅帳戶、Workspace 同發佈權限。

先查已安裝套件嘅說明同內置合約；查合約唔使登入。合約列出該套件附帶嘅操作同 schema。欄位名要跟返佢，唔好照搬另一個供應商嘅要求格式。

npx -y sosoapi --help
npx -y sosoapi api contract --summary
npx -y sosoapi api contract --route /studio-api/scheduled-posts/

CLI：第一次讀取已認證嘅 Workspace 資料

完成 auth login。用文字編輯器將下面 JSON 儲存成 workspaces.json，再執行指令。要求內容用檔案傳入，唔好將內容直接拼入 shell 指令。

CLI 會回傳 schema_version、http_status 同 body。成功回應包括 body.active_workspace_id 同 body.workspaces。要由回應揀今次指定 Workspace；目前 active Workspace 唔代表新任務可以默認用佢。新帳戶第一次呼叫可能會初始化第一個 Workspace。

要查 http_status 同 body，唔好只睇 shell 結束碼。指令可以正常回傳 HTTP 錯誤封套，但 API 操作並冇成功。

{}

npx -y sosoapi api post /identity-api/workspace/list < workspaces.json

CLI：揀已連接嘅社交帳戶

用你帳戶回傳嘅 Workspace ID 儲存 accounts.json，再執行指令。由 body.accounts 揀指定帳戶。排程用嘅 social_account_id 係 SosoAPI 帳戶 ID，唔可以用用戶名或平台專頁 ID 代替。

{
  "workspace_id": "<YOUR_WORKSPACE_ID>"
}

npx -y sosoapi api post /identity-api/user/social-accounts/list < accounts.json

CLI：為一篇已批准嘅 Threads 文字帖文排程

呢個係要求範本，唔係可以直接執行嘅帖文。用檔案編輯器儲存 post.json，將每個方括號值換成你自己已獲批准嘅資料。揀未來 ISO 時間戳，要有明確 UTC 偏移，或者用 Z 表示 UTC。display_timezone 係顯示時間用嘅 IANA 時區，唔會自動補全有歧義嘅當地時間。

產生唯一 idempotency_key，例如 UUID，連同完整要求內容保留。重試完全相同要求要用返同一個 key；回應慢唔係另開 key 嘅理由。改咗帖文就係另一個要求，要先查原有結果，再決定新身份。

核對內容、帳戶、時間、權限同目前配額之後，先執行 create 指令。呢個會建立真實排程。獲接納後保留 body.post.id，並讀 body.post.status、body.post.scheduled_at 同 body.post.destination。body.deduped 表示有冇重用原有要求。獲接納唔等於平台確認已發佈。

{
  "workspace_id": "<YOUR_WORKSPACE_ID>",
  "social_account_id": "<YOUR_THREADS_ACCOUNT_ID>",
  "caption": "<YOUR_APPROVED_POST_TEXT>",
  "hashtags": [],
  "media": [],
  "provider_payload": {
    "platform": "threads",
    "publish_options": {
      "post_type": "TEXT"
    }
  },
  "scheduled_at": "<FUTURE_ISO_8601_TIME_WITH_OFFSET>",
  "display_timezone": "Asia/Hong_Kong",
  "idempotency_key": "<NEW_STABLE_REQUEST_KEY>"
}

npx -y sosoapi api post /studio-api/scheduled-posts/create < post.json

CLI：讀返已儲存帖文同結果

用已回傳 ID 儲存 post-status.json。讀取 body.post、body.delivery、body.actions 同 body.outcomes，確認有已發佈結果先報成功。如果 create 回應遺失，要用已保留嘅身份找回原有要求，唔好用新 key 另建排程。

{
  "id": "<RETURNED_POST_ID>"
}

npx -y sosoapi api post /studio-api/scheduled-posts/get < post-status.json

CLI：目前結果容許時先取消

如果最新讀取結果容許取消，而且你真係想取消，就用已回傳 ID 同目前數值 body.post.version 儲存 cancel.json。示例嘅 1 只係說明，要換成你啱啱讀到嘅版本。之後執行指令，再確認結果。

版本改咗或者唔容許取消，就重新讀同一篇帖文，按實際可用操作處理。唔好繞過版本衝突，亦唔好將取消排程當成刪除已發佈帖文。

{
  "id": "<RETURNED_POST_ID>",
  "expected_version": 1
}

npx -y sosoapi api post /studio-api/scheduled-posts/cancel < cancel.json

HTTP：由你自己嘅後端呼叫

做伺服器整合，可以喺 Connection → API 建立 API key，並將 secret 存入伺服器秘密設定。目前畫面只要求名稱，冇 Workspace 或能力選擇器。用戶建立嘅 key 預設可喺該用戶有權存取嘅 Workspace 執行 operate、publish 同 engage；要先核對呢個授權範圍係咪適合你嘅整合。API 合約亦支援明確限制 capabilities 同 workspace_ids 嘅 key。

一般 agent 設定用 OAuth，唔需要做呢個 API key 步驟。示例嘅 SOSOAPI_ACCESS_TOKEN 係你後端自己設定、用嚟裝 key 嘅變數，唔係 SosoAPI CLI 設定。CLI 可選嘅 personal access token 變數叫 VICKY_API_KEY。

沿用上面嘅 workspaces.json。直接 HTTP 會回傳端點內容，冇 CLI 嘅 http_status／body 封套，要睇實際 HTTP 狀態同 JSON。憑證要留喺後端，唔好放入瀏覽器程式、提示、截圖或共用要求檔案。

將社交帳戶連接嵌入你嘅產品、畀自己客戶使用，係另一項整合工作。呢個單帳戶示例唔代表客戶 onboarding 流程已經準備好。

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${SOSOAPI_ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data-binary @workspaces.json \
  'https://gqeshlawtcexsapabaui.supabase.co/functions/v1/identity-api/workspace/list'

• 管理 API key：Connection → API
• API 參考文件
• 建立 API key 同明確授權範圍
• 登入同權限
• CLI 參考文件

10. 問題排解

按實際錯誤，同你今次檢查緊嘅連接處理。擴大權限或重複提交，唔係所有失敗嘅解決方法。

更新、撤銷授權或求助

下面第一條指令會查最新套件說明，唔會啟動 MCP server。如果客戶端儲存嘅指令鎖定咗版本，要有意識地更新嗰條指令。更新另一份全域安裝，唔會更新客戶端鎖定嘅版本。

要撤銷本機裝置，可以去 Connection → Agent，或者執行下面 auth logout。託管 connector 亦喺 Connection → Agent 撤銷對應授權。API key 另喺 Connection → API 管理。撤銷 agent 存取唔會取消已接納排程，嗰啲帖文要另外處理。

求助時提供客戶端同套件版本、失敗步驟、畫面錯誤，同時間／時區。有需要先私下向支援提供相關要求或帖文 ID。唔好傳憑證、授權連結，或者可能有 token 嘅原始紀錄。

npx -y sosoapi@latest --help

npx -y sosoapi auth logout

• 管理 agent 客戶端：Connection → Agent
• 管理 API key：Connection → API
• 問題排解參考
• 聯絡 SosoAPI 支援

設定完成清單

唔提交帖文都可以完成連接設定。如果你有發帖，就要另外查實際結果，先確認第一次發佈流程成功。

• 客戶端用到 SosoAPI 工具，或者 CLI／API 做到已授權要求。
• 我已用正確帳戶登入，並揀咗指定 Workspace。
• 社交帳戶已顯示，而且有任務需要嘅能力。
• 我清楚 agent 只可以準備內容，定亦可以排程同發佈。
• 我可以準備草稿，並核對完整目的地、內容同時間。
• 如果有提交帖文，我已保留 ID，並識得分辨獲接納同確認已發佈。
• 我知道點樣查失敗原因、管理未完成排程同撤銷授權。