> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 即將推出的 API 變更

> 可能會影響你整合的 API 變更

以下 API 變更會於指定日期生效。
請仔細檢閱是否有潛在的破壞性變更。
所有新功能請見[更新公告](/whatsnew/latest)。

<Update label="June 15, 2026">
  <ul class="custom-bullets">
    <li>
      **Facebook：Meta 已停用 unique-impression（reach）與 3 秒影片觀看的 Insights 指標。** Meta 已在所有 Graph API 版本中移除這些指標，因此受影響的欄位不再回傳。詳情請見 [Meta Graph API v25 changelog](https://developers.facebook.com/blog/post/2026/02/18/introducing-graph-api-v25-and-marketing-api-v25/)。

      <ul class="custom-bullets">
        <li>
          [GET analytics/post](/apis/analytics/post) 不再回傳下列 Facebook 欄位：

          <ul class="custom-bullets">
            <li>impressionsUnique → 改用 `mediaView`</li>
            <li>impressionsFanUnique → 改用 `mediaView`</li>
            <li>impressionsOrganicUnique → 改用 `mediaView`</li>
            <li>impressionsPaidUnique → 改用 `mediaViewIsFromAds`</li>
            <li>videoViewsUnique → 使用 `videoViews` 取得非 unique 的 3 秒觀看數</li>
            <li>`totalVideoViews*Unique` 與 `totalVideoImpressions*` 系列欄位（例如 `totalVideoViewsOrganicUnique`、`totalVideoViewsPaidUnique`、`totalVideoViewsUnique`）</li>
          </ul>
        </li>

        <li>
          [GET analytics/social](/apis/analytics/social) 不再回傳下列 Facebook 欄位：

          <ul class="custom-bullets">
            <li>`pagePostsImpressions*` 系列欄位（`pagePostsImpressions`、`pagePostsImpressionsPaid`、`pagePostsImpressionsUnique`、`pagePostsImpressionsOrganicUnique`、`pagePostsImpressionsViral*`、`pagePostsImpressionsNonviral*`）→ 改用 `pageMediaView`</li>
            <li>pagePostsServedImpressionsOrganicUnique → 改用 `pageMediaView`</li>
            <li>pageVideoViewsUnique → 使用 `pageVideoViews` 取得非 unique 的 3 秒觀看數</li>
          </ul>
        </li>

        <li>
          reach 請改用 `mediaView` / `pageMediaView`。已規劃的 Total Unique Media Views 後續替代指標即將推出。仍受支援的欄位如 `reactionsByType`、`videoViews`、`mediaView`、`pagePostEngagements`、`pageVideoViews` 與 `pageVideoViewsPaid` 不受影響。
        </li>
      </ul>
    </li>
  </ul>
</Update>

<Update label="May 11, 2026">
  <ul class="custom-bullets">
    <li>
      **YouTube 暫時性失敗現在回傳 HTTP 503/504 而非 500：** 部分先前以 HTTP 500（`code: 176`）呈現的 YouTube 上傳失敗，現在改為回傳 HTTP 503（`code: 454`）或 HTTP 504（`code: 453`）。兩種回應皆包含 `retryAvailable: true`。若客戶整合是以 HTTP 500 過濾以重試 YouTube 上傳，應改為根據回應主體中的 `retryAvailable` 欄位過濾。詳情請見[錯誤碼](/errors/errors-ayrshare)。
    </li>
  </ul>
</Update>

<Update label="April 9, 2026">
  <ul class="custom-bullets">
    <li>
      **空的 Analytics 回傳 Error 187：** 當 [Social Analytics](/apis/analytics/social) 或 [Post Analytics](/apis/analytics/post) 請求沒有任何平台回傳資料時，現在會回傳 `{ "status": "error", "code": 187 }`，而非 `{ "status": "success" }`。請更新任何依賴先前「空的 success」行為的客戶端程式碼。
    </li>
  </ul>
</Update>

<Update label="March 31, 2026">
  <ul class="custom-bullets">
    <li>
      **X/Twitter BYO Key 要求：** 所有透過 Ayrshare 進行的 X/Twitter 操作都將需要你自己的 API 憑證。以 OAuth 連結 X 帳號後，於每次 X/Twitter 請求中包含 2 個標頭：`X-Twitter-OAuth1-Api-Key` 與 `X-Twitter-OAuth1-Api-Secret`。未提供有效憑證的請求會被拒絕。設定說明請見 [X BYO Key 設定指南](/dashboard/connect-social-accounts/x-twitter-byo-keys)。
    </li>

    <li>
      **RSS-to-X 停用：** 2026 年 3 月 31 日之後，RSS 自動發文至 X/Twitter 不再受支援。RSS feed 是按排程執行而不會逐次請求帶入憑證，這與 BYO key 模型不相容。RSS 自動發文至所有其他平台不受影響。
    </li>

    <li>
      **X 帳號活動 Webhook 停用：** 2026 年 3 月 31 日之後，X 帳號活動 webhook 動作（`accountActivity`）將不再提供。這包含所有已連結 X 帳號的即時事件通知（貼文、提及、私訊、按讚、追蹤、封鎖等）。
    </li>
  </ul>
</Update>

<Update label="November 14, 2025">
  <ul class="custom-bullets">
    <li>
      自 2025 年 11 月 14 日起，Facebook 將停用下列 [GET analytics/social](/apis/analytics/social) 欄位：

      <ul class="custom-bullets">
        <li>pageFans</li>
        <li>pageFansCity</li>
        <li>pageFansLocale</li>
        <li>pageFansCountry</li>
        <li>pageFansAdds</li>
        <li>pageFanAddsUnique</li>
        <li>pageFanRemoves</li>
        <li>pageFanRemovesUnique</li>
        <li>pageImpressions → 改用 `pageMediaView`</li>
        <li>pageImpressionsPaidUnique → 改用 `pageMediaViewIsFromAds`</li>
        <li>pageImpressionsUnique</li>
        <li>pageImpressionsViral</li>
        <li>pageImpressionsViralUnique</li>
        <li>pageImpressionsPaid → 改用 `pageMediaViewIsFromAds`</li>
      </ul>
    </li>

    <li>
      自 2025 年 11 月 14 日起，Facebook 將停用下列 [GET analytics/post](/apis/analytics/post) 欄位：

      <ul class="custom-bullets">
        <li>impressions 與 impressionsFanPaidUnique → 改用 `mediaView`。細部拆分可透過 `mediaViewIsFromAds`（廣告歸因的觀看）與 `mediaViewIsFromFollowers`（追蹤者歸因的觀看）取得。</li>
        <li>postImpressionsUnique（Reels）→ 使用 `blueReelsPlayCount` 取得 reel 播放次數，或使用 `postVideoViewTime` 取得總觀看時長。</li>
      </ul>
    </li>
  </ul>
</Update>

<Update label="September 1, 2025">
  <ul class="custom-bullets">
    <li>
      自 2025 年 9 月 1 日起，Instagram 的 [get comments](/apis/comments/get-comments)
      端點在回覆物件中將不再包含 `text` 欄位。請改用 `comment` 欄位
      存取回覆內容。
    </li>
  </ul>
</Update>

<Update label="June 1, 2025">
  <ul class="custom-bullets">
    <li>
      X (Twitter) [get comments](/apis/comments/get-comments) 端點將把使用者的公開
      指標移到新的 `publicMetrics` 物件。下列欄位將由最上層
      移至 `publicMetrics` 物件：

      <ul class="custom-bullets">
        <li>followersCount</li>
        <li>followingCount</li>
        <li>tweetCount</li>
        <li>listedCount</li>
        <li>mediaCount</li>
      </ul>
    </li>

    <li>
      Facebook 將停用下列 [GET
      analytics/social](/apis/analytics/social) 欄位：

      <ul class="custom-bullets">
        <li>pageVideoViews10S</li>
        <li>pageVideoViews10SAutoplayed</li>
        <li>pageVideoViews10SClickToPlay</li>
        <li>pageVideoViews10SOrganic</li>
        <li>pageVideoViews10SPaid</li>
        <li>pageVideoViews10SRepeat</li>
        <li>pageVideoViews10SUnique</li>
      </ul>
    </li>
  </ul>
</Update>

<Update label="May 7, 2025">
  <ul class="custom-bullets">
    <li>
      YouTube 已停用設定允許與封鎖區域的功能。你仍可以在 post 端點
      中加入允許與封鎖區域，但會被忽略。
    </li>
  </ul>
</Update>

<Update label="April 20, 2025">
  <ul class="custom-bullets">
    <li>
      下列 [Instagram 貼文分析](/apis/analytics/post) 指標將停用：

      REELS：

      <ul class="custom-bullets">
        <li>
          playsCount
        </li>

        <li>
          clipsReplaysCount
        </li>

        <li>
          igReelsAggregatedAllPlaysCount
        </li>
      </ul>

      FEED/STORY：

      <ul class="custom-bullets">
        <li>
          impressionsCount
        </li>
      </ul>
    </li>

    <li>
      若 `limit` 大於預設值 25，[history 端點](/apis/history/get-history) 將強制套用 1 分鐘的快取。
    </li>
  </ul>
</Update>

<Update label="March 1, 2025">
  TikTok 的 [get comments](/apis/comments/get-comments) 端點將標準化欄位名稱
  以與其他社群網路一致。

  <ul class="custom-bullets">
    <li>
      欄位 `replyList` 將重新命名為 `replies`，`profileImage` 將重新命名為
      `profileImageUrl`。
    </li>

    <li>兩個新欄位名稱皆已可用，可在整合中使用。</li>

    <li>
      TikTok 有下列更新：

      <ul class="custom-bullets">
        <li>
          [social analytics](/apis/analytics/social) 端點：即將有下列變更：
          • `durationAverage` 欄位將被停用並移除。• 由於 TikTok API
          的限制，`shareCountTotal`、`viewCountTotal` 與 `commentCountTotal`
          將只回傳過去 60 天的總計，而非全時期總計。• 若要即刻開始使用
          60 天總計，請在 API 請求主體中加入 `period60Days: true`。註：
          使用此參數將顯著改善回應時間。
        </li>

        <li>
          [history platform](/apis/history/history-platform) 與 [post
          analytics](/apis/analytics/post) 端點：未文件化的欄位 `caption`、`comments`、
          `shares`、`likes`、`shareUrl` 與 `itemsId` 將被移除——請改用 `post`、
          `commentsCount`、`sharesCount`、`likesCount`、`postUrl` 與 `id`。
        </li>
      </ul>
    </li>
  </ul>
</Update>

<Update label="February 1, 2025">
  [/user](/apis/user/profile-details) 端點將改變 API 使用量的回報方式：

  <ul class="custom-bullets">
    <li>
      `monthlyApiCalls` 欄位將擴充為計算所有 API 呼叫（貼文、留言、
      分析等）。
    </li>

    <li>如需針對貼文的計數，請使用新的 `monthlyPostCount` 欄位。</li>

    <li>
      `monthlyApiCallsQuota` 欄位將停用，並由新的 `monthlyPostQuota` 欄位
      取代。
    </li>
  </ul>
</Update>

<Update label="January 5, 2025">
  <ul class="custom-bullets">
    <li>
      Meta 將停用 Instagram [貼文分析
      端點](/apis/analytics/post)上的 `videoViews` 欄位。
    </li>

    <li>
      此外，`emailContactsCount`、`getDirectionClicks`、`profileViewsCount`、
      `textMessageClicks`、`websiteClicksCount` 與 `phoneCallClicksCount` 欄位將自
      Instagram [social analytics](/apis/analytics/social) 端點移除。
    </li>

    <li>這些欄位將於 2025 年 1 月 5 日移除。</li>
  </ul>
</Update>

<Update label="December 15, 2024">
  <ul class="custom-bullets">
    <li>
      為加強安全性，我們將防止 Profile Key 被當作 API Key 使用。如果你
      嘗試以 Profile Key 代替 API Key，系統會回傳錯誤。關於如何正確使用 Profile Key，[請見
      此處](/apis/overview#authorization)。
    </li>
  </ul>
</Update>

<Update label="November 15, 2024">
  <ul class="custom-bullets">
    <li>
      我們已更新 TikTok 排程 webhook 錯誤的回報方式。這些錯誤現在
      會出現在 errors 陣列中，與其他排程 webhook 類型的錯誤處理一致。
      註：目前的最上層錯誤仍會回傳，但我們鼓勵使用
      errors 陣列。
    </li>

    <li>
      history 端點現在會預設將回應以物件形式回傳。objResponse
      參數會自動設為 true。
    </li>

    <li>
      Get All History LinkedIn 會將 mediaUrls 物件回傳為陣列。先前若只有一個媒體
      項目會回傳物件，多個媒體項目才回傳陣列。現在即使只有單一媒體
      項目也一律回傳陣列。若你需要先前的行為，可以使用 `objResponse: false` 查詢參數。
    </li>
  </ul>
</Update>

<Update label="October 7, 2024">
  <ul class="custom-bullets">
    <li>
      media 端點將不再回傳 url\_1080。若確實需要縮放圖片，請
      參閱 [resize 端點](/apis/media/resize)。
    </li>
  </ul>
</Update>

<Update label="September 16, 2024">
  <ul class="custom-bullets">
    <li>
      **2024 年 9 月 25 日更新**：Meta（Facebook）已發布欄位停用，因此
      這些欄位的移除已生效。請參閱 [social
      analytics](/apis/analytics/social) 中更新後的回傳內容。
    </li>

    <li>
      Facebook 將[停用數個
      欄位](https://developers.facebook.com/docs/pages-api/changelog/)。[social analytics
      端點](/apis/analytics/social-by-id) 在 2024 年 9 月 16 日
      之後將不再回傳這些欄位。
    </li>
  </ul>
</Update>

<Update label="June 3, 2024">
  <ul class="custom-bullets">
    <li>
      [新的縮網址系統](/apis/links/overview)將取代 Google 已停用的
      舊縮網址端點。新的縮網址服務需要加購 [Max
      Pack](/additional/maxpack)。
    </li>

    <li>
      連結縮短預設為關閉（`false`）。若要自動縮短連結，請在 post 端點
      呼叫中使用 `shortenLinks: true`，其會使用新的[連結
      端點](/apis/links/overview)。
    </li>
  </ul>
</Update>

<Update label="April 22, 2024">
  <ul class="custom-bullets">
    <li>
      Meta 將停用其 Facebook Groups API。請參閱
      [公告](https://www.ayrshare.com/blog/facebook-removes-groups-api-access-impact-and-implications/)。
    </li>
  </ul>
</Update>

<Update label="April 16, 2024">
  <ul class="custom-bullets">
    <li>
      Instagram 已釐清 online followers 資料集的時間範圍。詳情請參閱
      [此處](/apis/analytics/instagram-follower-count)。
    </li>
  </ul>
</Update>

<Update label="April 1, 2024">
  <ul class="custom-bullets">
    <li>
      [依 comment ID 回覆留言](/apis/comments/reply-to-comment) 的預設回應會
      是文件所列的物件，而非陣列。若你希望保留陣列回應，可將 objResponse 參數
      設為布林值 `false`。
    </li>
  </ul>
</Update>

<Update label="January 25, 2024">
  <ul class="custom-bullets">
    <li>
      [重試貼文端點](/apis/post/retry-post) 將回傳「pending」而非
      「success」的 status，更能反映重試的狀態。
    </li>

    <li>
      關於 [scheduleDate 與
      createDate 的 API 變更](/whatsnew/upcoming-api-changes#changes-in-effect-june-17-2022) 將會發布。
    </li>
  </ul>
</Update>

<Update label="December 8, 2023">
  <ul class="custom-bullets">
    <li>
      `/history/instagram` 端點的 `caption`、`message`、`createdTime` 與 `timestamp`
      欄位已於 2023 年 4 月 1 日停用，即將移除。請改用 `post` 與
      `created` 欄位。
    </li>

    <li>
      `/history/linkedin` 端點的 `mediaUrls` 欄位將以陣列（而非物件）回傳，
      以支援多張圖片。你現在可以在 LinkedIn 查詢參數中加入 `?multiMedia=true` 強制回傳陣列。
      請注意，在 2023 年 12 月 1 日之前，必須使用 `multiMedia` 查詢參數才能取得
      多張圖片的媒體。2023 年 12 月 1 日之後，多張圖片將預設回傳。
    </li>

    <li>
      Scheduled Action TikTok webhook 將停用字串型別的 `platform`。請改用
      `platforms` 陣列欄位，與其他 Scheduled Action webhook 一致。
    </li>

    <li>刪除留言的文件已更正以符合正確回傳格式。</li>

    <li>
      TikTok 的 commentId 欄位將由 id 欄位取代，以與標準的
      留言刪除格式一致。
    </li>

    <li>
      Twitter 的刪除留言回傳將不再包含 `posts` 陣列，使回傳
      與標準的留言刪除格式一致。新的回傳格式如下：
    </li>
  </ul>
</Update>

<Update label="October 18, 2023">
  <ul class="custom-bullets">
    <li>
      下列 [social analytics 端點](/apis/analytics/social) 的 YouTube 欄位
      將回傳為數值而非字串。
    </li>
  </ul>
</Update>

<Update label="May 30, 2023">
  <ul class="custom-bullets">
    <li>
      我們已升級至 Twitter 新的 API version 2。Twitter 在 Version
      2 中已停用一些欄位，這會影響 /analytics/social 與 getAllHistory 端點。下列
      欄位在 2023 年 9 月 1 日之前仍會回傳，但值會是 0 或空字串。
    </li>
  </ul>
</Update>

<Update label="May 8, 2023">
  <ul class="custom-bullets">
    <li>
      我們很興奮地推出 [TikTok 直接發布](/apis/post/social-networks/tiktok)、留言
      管理與進階分析。使用者不再需要開啟 TikTok 手機
      App 就能發布並輸入內文。透過 Ayrshare 發送後，TikTok 影片與
      內文將直接發布。
    </li>

    <li>
      我們也推出新增、取得與刪除 TikTok 留言 + 人口統計分析
      資料。
    </li>

    <li>
      使用者需取消連結並重新連結其 TikTok 帳號以啟用直接發布。
      現有連線會繼續使用間接方式，需要 TikTok 手機 App 才能發布。
    </li>
  </ul>
</Update>

<Update label="February 17, 2023">
  <ul class="custom-bullets">
    <li>
      Google Business Profile 已變更可用的 social analytics 資料。新的
      可用欄位如下。舊欄位仍會存在但值為 0，並於
      2023 年 3 月 17 日完全移除。
    </li>
  </ul>
</Update>

<Update label="October 1, 2022">
  <ul class="custom-bullets">
    <li>Get All Posts 的 descriptions、text、message 欄位標準化為 `post` 欄位。</li>
  </ul>
</Update>

<Update label="September 12, 2022">
  <ul class="custom-bullets">
    <li>TikTok 欄位停用：`shareUrl`。請改用 `postUrl`。</li>
  </ul>
</Update>

<Update label="June 17, 2022">
  <ul class="custom-bullets">
    <li>
      所有 history 端點的 `createdAt`、`createdTime` 與 `timestamp` 欄位
      將被 `created` 欄位取代，其會以 UTC 格式回傳建立時間。
    </li>

    <li>
      `scheduleDate` 欄位將不再回傳物件，而以字串回傳 UTC 格式的
      排程時間。
    </li>

    <li>
      /history 上未文件化的 `created_date` 欄位將被移除。請改用 `created`。
    </li>
  </ul>
</Update>

<Update label="April 22, 2022">
  <ul class="custom-bullets">
    <li>
      [Facebook 貼文](/apis/analytics/post)的 Analytics 會以下列
      格式將 `reactions` 回傳為物件。
    </li>
  </ul>
</Update>

<Update label="April 1, 2022">
  <ul class="custom-bullets">
    <li>
      History 預設會回傳最近 20 則貼文。最多可透過 `lastRecords` 參數
      回傳 500 則。
    </li>
  </ul>
</Update>