Threads API / Instagram API 申請教學：由設定 App 到第一次成功讀取

Threads API / Instagram API 申請涉及帳戶、App、權限和 token。第一次設定時，畫面上有很多選項，很容易把「建立好 App」和「已經可以讀取資料」看成同一步。

我為自己的內容同步整理這套設定時，先確認一篇內容可以正確讀取，再處理歷史內容、分頁和數據。每完成一個小步驟，就有一個可以核對的結果。

本文以讀取自己的 Threads 內容，以及透過 Instagram Login 讀取 Instagram Professional 帳戶為範圍。官方文件核對日期為 2026 年 10 月 28 日；Meta 的畫面、權限和版本會更新，設定時仍要對照當前文件。

Threads API / Instagram API 申請前，要先選甚麼？

先寫下要讀取哪個帳戶，以及要取得哪類資料。這兩個答案會決定登入方式、所需權限和測試範圍。以下 Threads 步驟是依當前官方文件整理的起步路線；文中的實際排查經驗來自這次 Instagram 設定。

Threads API 有自己的 App 設定和權限。Instagram 這篇採用 Instagram Login，服務對象是 Business 或 Creator 等 Professional 帳戶。這條路線毋須連結 Facebook Page。Meta 亦提供 Facebook Login 和 Unified Login 等路線，各自有帳戶連結及設定要求。跟着其中一條路完成，較容易排查問題。

這張表只涵蓋本文使用的路線。發佈內容、管理留言和訊息各有獨立權限，待實際需要才加入。Facebook Login 亦有另一套權限與 Page 要求，不宜把兩條路的設定混用。

Instagram 官方文件區分 Standard Access 和 Advanced Access：讀取自己或自己管理、並已加入 App Dashboard 的 Professional 帳戶，可以先按 Standard Access 開發。為其他業務提供服務，則要檢查 Advanced Access、App Review 和適用的驗證要求。這個分別會直接影響你要準備的資料。

參考：Instagram App Review、Instagram Insights。

怎樣建立 App，並讓測試帳戶真正生效？

建立 App 之後，還要完成測試角色和帳戶端的邀請接受。只在開發者後台加入名字，未必代表整個測試授權已完成。

步驟 1：選擇對應的 use case

Threads 在建立 App 時選擇 Access the Threads API use case，再按當前文件完成 Threads 設定。

Instagram 官方文件目前列出的建立路線是 Create App，選 Other use case、Business，再加入 Instagram。Instagram Login 的設定會隨之加入。實際顯示仍以你當時的 App Dashboard 為準。

我設定 Instagram App 時，最初的名稱包含 Instagram，系統未有接受。改用自己擁有的中性名稱後才繼續。可以由自己的工具或產品名稱開始，再按系統顯示的命名要求修正。

步驟 2：加入測試角色，接受邀請及條款

按所用產品的測試角色流程加入帳戶，再到帳戶端接受相關邀請及條款。Instagram 設定文件目前要求加入公開的 Instagram 帳戶作測試，先核對測試帳戶的可見性與資格。Threads 文件列出 Threads Testers；Instagram 則按 Instagram Login 的帳戶及角色設定處理。

完成後，回到 App Dashboard 核對帳戶是否已加入，再用該帳戶進行授權。我當時有核對邀請及條款的接受狀態，才進行後面的 token 測試。

商業驗證與 App 上線要求要另外處理。它們會影響對外提供服務的階段；開發初期可以先完成官方允許的測試步驟。

參考：建立 Threads App、建立 Instagram App。

redirect URI 和 OAuth，要怎樣逐步檢查？

OAuth 是讓帳戶授權 App 存取指定資料的流程。這一步的檢查重點，是登入方式、權限，以及前後一致的 redirect URI。

步驟 3：登記一個完全一致的 callback

在 App 設定登記 redirect URI，然後確保授權請求及交換 code 時使用同一個值。協定、網域、路徑和尾斜線都要逐字核對。

callback 收到授權結果後，伺服器需要驗證這次請求與原本發起的流程相符，例如核對 state，再處理 code。App Secret 和 token 留在伺服器或安全的 credential storage，讀者瀏覽器只接收流程結果。

步驟 4：只要求當前需要的權限

我曾使用 Instagram Dashboard 的 Generate token。當時它要求的權限包括訊息、留言、發佈和 Insights，之後遇到 HTTP 429。

後來採用只要求 instagram_business_basic 的專用 OAuth 流程，先完成基本讀取。這是當次設定的處理方法；HTTP 429 的根本原因未有足夠證據確認，不能把每次 429 都歸因於權限數量。遇到限流時，也要檢查回應、當前限制和重試安排。

Meta 官方文件的權限命名說明：基本讀取使用 instagram_business_basic。這是文件截圖，沒有展示我的 App 設定或 token；按實際需要選擇權限。

步驟 5：由伺服器交換 code，再交換長效 token

帳戶授權後，callback 會收到 authorization code。Threads 和 Instagram 的相關文件均列出 code 有效期為一小時、只能使用一次。Instagram 文件另外提醒，要在處理 code 時移除尾隨的 #_。

伺服器用對應 App 的 ID、Secret、code 和相同 redirect URI 交換 token。Threads 與 Instagram 使用不同的交換端點及 grant，實作時可以分開命名設定，避免拿錯 App 的資料。

本文不展示真實授權連結、callback、App ID 或 token。完整交換參數可直接對照官方文件：

• Threads 存取 token 與權限
• Instagram Business Login

取得 token 後，第一次應該讀甚麼？

先讀取帳戶身份，再讀一篇內容。這樣能確認 token 屬於預期帳戶、基本權限有效，以及回傳欄位符合預期。

以下是伺服器端執行的示意，先把身份讀取回傳的 user_id 保存為 IG_USER_ID。所有變數都要由你自己的安全設定提供。IG_API_VERSION 請按正在使用的官方版本設定；不要把真實 token 貼進文章、截圖或共用終端紀錄。執行前亦要確認 HTTP client 和記錄系統會遮蔽 Authorization header。

# Threads：先核對身份，再讀一篇內容
curl --get 'https://graph.threads.com/me' \
  --header "Authorization: Bearer ${THREADS_ACCESS_TOKEN}" \
  --data-urlencode 'fields=id,username'

curl --get 'https://graph.threads.com/me/threads' \
  --header "Authorization: Bearer ${THREADS_ACCESS_TOKEN}" \
  --data-urlencode 'fields=id,text,permalink,timestamp' \
  --data-urlencode 'limit=1'

# Instagram Login：按所選版本讀取身份和內容
curl --get "https://graph.instagram.com/${IG_API_VERSION}/me" \
  --header "Authorization: Bearer ${IG_ACCESS_TOKEN}" \
  --data-urlencode 'fields=user_id,username'

curl --get "https://graph.instagram.com/${IG_API_VERSION}/${IG_USER_ID}/media" \
  --header "Authorization: Bearer ${IG_ACCESS_TOKEN}" \
  --data-urlencode 'fields=id,caption,media_type,permalink,timestamp' \
  --data-urlencode 'limit=1'

檢查回應時，可以核對：帳戶是否正確、內容 ID 和 permalink 是否對得上原文，以及 caption 或 text 是否完整。limit=1 是這個測試主動設定的數量。端點與欄位可對照 Threads 讀取內容 及 Instagram 首次 API 呼叫。

我最初只匯入一篇 Instagram 內容，目的是驗證整條路能否運作。這個結果不能用來推斷 API 只容許取得一篇。

加了 Insights 權限，為甚麼還是讀不到數據？

新增權限後，要讓帳戶重新授權，並確認實際執行中的 credential 已經換成新 token。App 後台的設定，與目前 token 持有的授權，要分開檢查。

我後來加入 Instagram metrics 時，就遇到系統仍使用快取中的 basic token。處理時先驗證候選的新 credential 屬於正確帳戶，並實際讀到 Views，才把已加密儲存的 credential 替換。

Instagram Login 的 Insights 文件現時要求 instagram_business_basic 和 instagram_business_manage_insights。Threads 的 Insights 則需要 threads_basic 及 threads_manage_insights。帳戶層級和內容層級的 endpoint，以及各種 media type 可用的 metric，也要按文件分開核對。

缺少 metric 時，先保留「未有資料」的狀態，避免直接填成 0。升級後的檢查可以由一個確定有資料的 metric 開始。讀得到之後，再逐項增加需要的數據，並記錄每個數字的定義和時間範圍。

參考：Instagram Insights 權限與限制、Threads App 權限設定。

長效 token 可以用多久？需要怎樣更新？

長效 token 仍有到期日。Threads 文件列出短效 token 為一小時，長效 token 為 60 日；Instagram 的長效 token 亦為 60 日。兩者的長效 token 都要已建立至少 24 小時而且尚未到期，才符合文件列出的 refresh 條件。成功 refresh 後，有效期重新計為 60 日。

可以記錄 token 取得時間、預計到期時間、最近一次成功更新時間，以及更新失敗時的處理方法。排程要留出重試空間，並安排失效後重新授權的路線。

截至這次設定的紀錄，新的 Instagram 授權尚未滿足可進行 refresh 的時間條件，長效 token 交換已測試，但該次新授權的完整 refresh 週期仍未實際觀察。這一點需要在後續運作中再驗證。

參考：Threads 長效 token、Instagram token 交換與更新。

可以讀取之後，怎樣避免同步中斷和重複資料？

把 API 連線與批次同步分開驗證，再逐步增加批次大小。每批保存 cursor，並以平台內容 ID 判斷記錄是否已存在，就能在中斷後繼續核對。

我曾把 Instagram 同步批次設為 25 篇，工作在五分鐘後逾時。改成每批一篇，保存 cursor 並接續執行，最後完成當時帳戶的 7 篇內容與 73 個 carousel items。這裏的五分鐘是當次執行環境的 timeout，並非 Instagram API 的通用限制。

當次後續數據檢查確認了 7 個唯一內容 ID，以及七項 metrics 合共 49 個數值；沒有新增重複記錄或刪除原有記錄，原文亦保留。這些是當次帳戶與執行的結果，不能直接推算其他帳戶的數量或所有 metrics 的可用性。

如果要建立自己的同步流程，可以先採用以下做法：

1. 以平台及內容 ID 作為唯一鍵，重跑時更新同一筆記錄。
2. 每批成功後保存 checkpoint 和 cursor，下一批從已確認的位置繼續。
3. 分開記錄新增、更新、跳過和失敗數量，並核對原文。
4. 對 429、暫時性錯誤及 timeout 安排有上限的退避重試。
5. 一次讀不到資料時，保留原有記錄，再檢查分頁、權限和錯誤。

我現在會先確認內容、權限和執行紀錄都對得上，再考慮增加自動化範圍。若你正在整理 AI 與工具之間的交接，也可以參考 AI 工具分工，先寫清楚來源、執行者和成果位置。

小練習：今天先完成哪一個可核對的結果？

選一個自己管理的測試帳戶，在私人設定紀錄寫下登入路線、最少權限、redirect URI 的核對結果，以及第一次身份讀取和單篇內容讀取是否成功。

先把這個小測試完成，再加入 Insights 或整批歷史內容。每一步都有結果，之後遇到問題就有地方往回查。

常見問題（FAQ）

這次設定讓我更習慣把「取得權限」和「驗證結果」連在一起。先讀到正確的一篇，再慢慢增加範圍，往後維護時也較容易知道問題出在哪一步。