179 lines
8.3 KiB
Markdown
179 lines
8.3 KiB
Markdown
# 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 不放環境變數——它是每個帳號各自的，授權後存在本機資料庫的對應帳號上。
|