# Threads 官方 API 申請與連線指南

> 這份是給「使用者」看的操作手冊。照著做，就能把你的（多個）Threads 人設帳號接上官方 API，用來**更穩定地發文、回覆留言、同步成效、關鍵字海巡**。
>
> ⚠️ 官方 API 是**選用**的。不想申請也可以只用「瀏覽器登入（session）」模式運作，只是發文/海巡走無頭瀏覽器，較容易因改版或風控中斷。

---

## 0. 先搞懂一件事：一個 App，多個帳號

這是最多人搞錯的地方，先講清楚：

- **你只需要建立「一個」Meta App**（一組 App ID + App Secret），不是每個人設各建一個。
- App ID / App Secret 在本工具裡是**全部帳號共用**，只要在「連線設定」填一次。
- 但**每一個 Threads 人設帳號，都要各自「授權」一次**，每次授權會換到「那個帳號專屬的 access token」。
- 一把 token 只能操作它對應的那一個帳號，不能用同一把 token 發到不同帳號。

> 換句話說：**建 App / 申請權限 = 做一次；接帳號 = 每個人設各做一次。**

```
            ┌─────────────────────────────┐
            │   一個 Meta App（共用）       │
            │   App ID + App Secret        │
            └──────────────┬──────────────┘
                           │ 每個帳號各自 OAuth 授權一次
        ┌──────────┬───────┼───────┬──────────┐
       人設A      人設B    人設C   人設D       人設E
      (token A)  (token B)(token C)(token D)  (token E)
```

---

## 1. 申請流程總覽

1. 建立 Meta 開發者帳號
2. 建立一個 App，加入「Access the Threads API」用途
3. 取得 App ID 與 App Secret
4. 設定 OAuth Redirect URI（要跟本工具一致）
5. （測試階段）把你的每個人設帳號加為 **Threads Tester**
6. 在本工具「連線設定」填入 App ID / Secret
7. 在「帳號策略」頁，對每個人設各按一次「連線」完成授權
8. （要給非測試者帳號用、或要開 keyword search）才需要送 **App Review**

---

## 2. 詳細步驟

### Step 1 — 建立 Meta 開發者帳號

1. 前往 <https://developers.facebook.com/> 用你的 Facebook 帳號登入。
2. 第一次會要你完成「開發者註冊」（驗證手機 / Email）。

### Step 2 — 建立 App

1. 進入 <https://developers.facebook.com/apps/> → 點「**建立應用程式 / Create App**」。
2. 用途（Use case）選擇 **「存取 Threads API / Access the Threads API」**。
   - 找不到的話，選「Other」→ App 類型選「Business」，建立後再到 Products 加入 Threads。
3. 填 App 名稱（給自己看的，例如 `巡樓`）、聯絡 Email，建立。

### Step 3 — 取得 App ID 與 App Secret

1. 進入這個 App 的後台。
2. 左側 **App settings → Basic（基本資料）**。
3. 這頁就有：
   - **App ID**（Threads App ID）
   - **App Secret**（點「Show」要再輸入密碼才看得到）
4. 先複製下來，等下要貼進本工具。

> ⚠️ App Secret 等同密碼，**不要外流、不要 commit 進 git**。

### Step 4 — 設定 OAuth Redirect URI（最容易出錯）

1. 左側找到 **Threads / Threads API → Settings（設定）**。
2. 找到 **Redirect Callback URLs / OAuth Redirect URI** 欄位。
3. 填入本工具的 callback 網址，**結尾必須完全一致**：

   ```
   {你的網址}/api/threads/oauth/callback
   ```

   - 本機開發：`http://localhost:3000/api/threads/oauth/callback`
   - 有對外網域時：`https://你的網域/api/threads/oauth/callback`

> 本工具的「連線設定」頁會直接顯示**目前該填的 Redirect URI**，照抄最保險。
>
> 如果之後要在本機用 API 發「含圖片」的貼文，圖片需要一個 Meta 能存取的公開網址，這時要把 `APP_URL` 設成像 ngrok 的公開網址，Redirect URI 也要跟著改成那個網域。

### Step 5 —（測試階段）把每個人設加為 Threads Tester

App 在還沒通過 App Review 之前是「開發模式」，**只有被加為測試者的帳號才能授權**。所以你的 5 個人設都要加進來：

1. 左側 **App roles → Roles（角色）**，或 Threads API 設定頁的測試者區塊。
2. 找到 **Threads Testers**，點「Add People / 新增」。
3. 輸入該人設的 **Threads 使用者名稱（@username）**，送出邀請。
4. **重點**：用那個人設帳號登入 Threads / Instagram，到
   <https://www.threads.net/settings/account>（或設定 → 帳號 → 網站權限 / Invites）**接受測試者邀請**。
5. 5 個人設各做一次。

> 沒接受邀請的帳號，授權時會出現「權限不足 / invalid_scope / 無法授權」之類的錯誤。

### Step 6 — 在本工具填入 App ID / Secret（做一次）

1. 開本工具 → 左側 **連線設定**。
2. 在「官方 API」區塊填入 **Meta App ID** 與 **Meta App Secret**。
3. 確認頁面顯示的 **OAuth Redirect URI** 已經填回 Step 4 的 Meta 後台。

> 也可以改用環境變數（見最後一節），填了環境變數就不必在 UI 重填。

### Step 7 — 每個人設各自連一次（重複 N 次）

1. 在左下角**帳號切換器**選到要連的人設（例如「人設 A」）。
2. 到 **帳號策略** 頁，找到「連線狀態」卡片。
3. 按「官方 API → 連線」，會跳轉到 Meta 授權頁，登入/確認後跳回。
4. 卡片變成「已授權連線」就完成了。
5. **切到下一個人設，重複 2–4**，直到 5 個都連好。

> 系統會自動把每個 token 綁到「當下選中的帳號」，彼此不會互相覆蓋。

### Step 8 —（選用）送 App Review

只有在以下情況才需要：

- 想讓**非測試者**的帳號也能授權（例如要給別人用）。
- 想開啟 **關鍵字海巡（keyword search）**：`threads_keyword_search` 屬於進階權限，需要審核。

審核通常需要準備：

- 一段 **螢幕錄影**：完整示範 OAuth 登入 → 發文 / 使用該權限的流程。
- **隱私權政策網址**。
- **資料刪除說明網址 / 回呼**。
- 對每個申請權限說明用途。
- 審核大約 **3–5 個工作天**。

本工具預設會要求這些 scope：
`threads_basic`、`threads_content_publish`、`threads_read_replies`、`threads_manage_replies`、`threads_manage_insights`、`threads_keyword_search`。
測試階段只用測試者帳號就能跑前五個；`threads_keyword_search` 通常要過審才會生效。

---

## 3. 連好之後，哪些功能會用官方 API？

到「連線設定」可以分開開關：

| 開關 | 影響 |
| --- | --- |
| **用官方 API 發布** | 開啟後，發布走 API（較穩、可同步 media id）；沒連線或關閉時自動退回瀏覽器發文。 |
| **用官方 API 找靈感** | 用 `keyword_search` 海巡（需要該權限過審）。 |
| 成效同步 / 回覆 | 連線後即可用 API 抓自己貼文成效、回覆留言。 |

所有動作都以「目前選中的帳號」的 token 進行；換帳號前記得先在左下角切換。

---

## 4. 常見錯誤排查

| 現象 | 可能原因 / 解法 |
| --- | --- |
| 授權跳回後顯示 `redirect_uri` 不符 | Meta 後台的 Redirect URI 沒和本工具完全一致（注意 http/https、結尾、有無斜線）。 |
| `no_active_account` | 還沒建立或選定帳號。先到帳號策略建立人設並切到它，再連線。 |
| 授權頁說權限不足 / 無法授權 | 該人設沒被加為 Threads Tester，或沒接受邀請（Step 5）。 |
| 找靈感（API）沒結果或報錯 | `threads_keyword_search` 尚未過審；先關掉「用官方 API 找靈感」，改用瀏覽器海巡。 |
| 含圖貼文 API 發布失敗 | 圖片需公開網址；設定 `APP_URL` 為對外網域（如 ngrok），或先發純文字。 |
| token 過期 | 系統會在快到期時自動刷新長效 token；若失敗就到該帳號重新「連線」一次。 |

---

## 5. 用環境變數設定（可選）

不想在 UI 填 App ID/Secret，可在 `.env` 設定（UI 仍可覆蓋）：

```bash
THREADS_APP_ID=你的_App_ID
THREADS_APP_SECRET=你的_App_Secret
# 對外網址（影響 OAuth Redirect URI 與含圖發布）
APP_URL=http://localhost:3000
```

> Token 不放環境變數——它是每個帳號各自的，授權後存在本機資料庫的對應帳號上。