Skip to main content
GET
透過 Comment API,使用 Ayrshare Post ID、Social Post ID、Ayrshare Comment ID 或 Social Comment ID 取得貼文的留言。 不同 ID 類型的詳情請參閱留言概觀。
若使用 Ayrshare Post ID,則不需要任何查詢參數。

額外的留言細節

  • 除了 X 以外的所有平台,留言資料每 10 分鐘更新一次。由於 X API 的限制,X 的留言資料採用指數退避(exponential backoff)策略重新整理,代表更新間隔會隨時間逐漸拉長。
  • 在 X 上,若請求的貼文本身是一則回覆,會回傳該貼文底下的回覆。自行開啟對話的 X 貼文則維持不變,仍會回傳整個對話中的回覆。
  • 在 Facebook 回應中,對回覆的回覆一律具有相同的 parent.id。
  • 若要取得 LinkedIn 對留言的回覆,請將 "commentId": true 與 "searchPlatformId": true 查詢參數設好,並在路徑參數中提供 Social Comment ID。
  • Facebook 與 Instagram 最多會回傳貼文最近的 1,000 則留言。如需 Enterprise 方案提高上限的資訊,請與我們聯絡。
  • 對於仍在處理中的 TikTok 貼文(其 id 為 "pending"),get-comments 會回傳明確的「仍在處理中」錯誤(code: 288,HTTP 400),而非通用失敗。請等到 tikTokPublished webhook 觸發,或 /history 顯示已解析的 video id 後再重試。

多平台讀取與部分成功

當你使用 Ayrshare Post ID 請求留言時,該貼文可能涵蓋多個平台。Ayrshare 會為每個平台展開一個請求(「分支」),並在部分分支成功而部分失敗時回傳部分成功——正常平台的留言資料一定會回傳,且每個失敗的分支會在最上層的 errors[] 陣列中逐一列出。
  • 部分平台成功,部分平台失敗:回應為 HTTP 200 且 status: “partial”。正常平台的區塊照常回傳,最上層的 errors[] 陣列則列出每個失敗的分支,包含其 platform、status、code、message 與 id。
  • 所有平台皆失敗:回應為 status: “error”,並包含完整的 errors[] 陣列。HTTP 狀態會由代表性的最上層錯誤碼對應而來。Code 485 對應到 HTTP 404;其他代表性代碼則使用各自的對應關係。
  • 所有平台皆成功:回應維持不變——HTTP 200、status: “success”,且沒有 errors[] 這個鍵。
行為變更——請檢查 errors[],不要以 HTTP 狀態做分支判斷。 由於現在多平台讀取中若有分支失敗時會回傳 HTTP 200,而不是把整個回應摺疊為錯誤,整合者應該一律檢查最上層是否有 errors[] 陣列來偵測個別平台的失敗,而不是只依賴 HTTP 狀態碼。

已過期或無法使用的 Instagram / Facebook Story 留言

已過期或無法使用的 Instagram 或 Facebook Story 留言分支——因此其留言無法取得——會出現在 errors[] 中,並帶有 code 485。一則代表性的 Instagram 訊息為 “Instagram Story expired or unavailable — comments/insights cannot be retrieved.” 若另一個平台成功,該平台的留言仍會回傳,且整體回應為 HTTP 200。全部失敗的回應中,代表性的 code 485 對應到 HTTP 404;其他代表性代碼則使用各自的對應關係。請以 code(485)比對,而非以完整訊息文字比對。

範例:部分成功回應

200: 部分成功

X 計費與速率限制失敗

X 的留言讀取可能因你自己的 X Developer 帳號而失敗,最常見的原因是帳號已沒有 API 點數,或已達到 X 的速率限制。這類失敗會回傳具類型的錯誤,而非空的留言清單,因此帳號問題絕不會被誤判為貼文沒有留言。
  • X 回傳 HTTP 402(沒有 API 點數):Ayrshare 會回傳 code: 416 與 HTTP 402。
  • X 回傳 HTTP 429(速率限制):Ayrshare 會回傳 code: 364 與 HTTP 429。若 X 的 429 表示帳號點數已用完,Ayrshare 則改為回傳 code: 416,因為等待並無法解決此問題。
  • 授權失敗會回傳 code: 272,其他任何 X 失敗則回傳 code: 219,兩者皆搭配 HTTP 400。
在多平台讀取中,回應的最上層為 status: “partial”,失敗的 X 分支會出現在 errors[] 中並帶有 status: “error”,與上方說明完全相同;單一平台讀取則會在最上層回傳錯誤。當 X 直接拒絕請求時,該失敗不會被快取,因此你再次請求留言時就會立即重試讀取。 已刪除的 X 貼文,或你的 X 憑證無法查看的貼文,仍會回傳空陣列且不帶錯誤。

標頭參數

路徑參數

查詢參數

boolean
預設值:false
若要取得透過 Ayrshare 發布之貼文的留言並使用 Ayrshare Post ID,請勿包含此欄位——預設為 false。若要以社群網路產生的 ID(即 Social Post ID 或 Social Comment ID)取得留言,請設為 true。
boolean
預設值:false
若要以 Social Comment ID(即社群網路產生的留言 ID)取得留言,請設為 true。若使用 Ayrshare Post ID 或 Social Post ID 取得留言,請勿包含此欄位——預設為 false。
使用 commentId 查詢參數時,也必須將 searchPlatformId 設為 true。
string
當 searchPlatformId 或 commentId 為 true 時為必填。何時使用:
  • 使用 Social Post ID 並將 "searchPlatformId": true 時。支援平台:bluesky、facebook、instagram、linkedin、threads、tiktok、twitter、youtube。
  • 使用 Social Comment ID 並將 "searchPlatformId": true 與 "commentId": true 時。支援平台:facebook、instagram、linkedin。
  • 若使用 Ayrshare Post ID,請勿包含此欄位——會從原始貼文所發布的所有平台回傳留言。

取得留言請求範例