Hailory
登入

連結 Instagram 帳號

逐步引導你完成 IG Business 設定 · 自己測試約 30 分鐘 · 通過 Meta App Review 約 1–4 週

開始前先確認：
  1. 你的 IG 帳號是「商業帳號 (Business)」 — 不能是「創作者 (Creator)」。
    檢查路徑：IG App → 設定和隱私 → 帳號類型和工具 → 切換為商業帳號。
  2. 商業帳號要關聯一個 Facebook 粉專 — 沒有的話 IG App 會引導你建立一個（可選擇「品牌或產品」類型，簡單填寫即可）。
  3. 你是這個 Facebook 粉專的管理員身份（不是編輯者 / 廣告投放者）。
1

建立 Meta 開發者 App

前往 Meta for Developers，登入後右上角「我的應用程式」→「建立應用程式」。

  • 使用情境（Use case）：選 Other →「下一步」
  • 類型（App type）：選 Business →「下一步」
  • 應用程式名稱：Hailory-自動回覆 或自選
  • 聯絡信箱：填可收信的 email（Meta 會寄審核結果到這裡）
  • Business Portfolio（原 Business Manager）：如果已有就關聯，沒有可以先跳過
App ID 在建立完成後的 Dashboard 右上角會看到。後面步驟會用到，可以先記下來。
2

加入 Instagram 產品（使用 Instagram Login）

進入 App Dashboard → 左側選單「Add Products」→ 找到 Instagram 卡片，點「Set Up」。

進入 Instagram 設定後，選 Instagram Login 路線（不是 Facebook Login）。系統會引導你授權 IG 帳號 — 跳出來的 IG 登入畫面用你要管理的那個 IG 商業帳號登入。

⚠️ 路線選錯會卡死： 「Instagram API with Facebook Login」舊路線的 scope（instagram_manage_messages、pages_messaging）已在 2025/1/27 deprecated。 一定要選 Instagram Login 才是新版可用的。
3

申請權限（App Review）

左側選單 → App Review → Permissions and Features，搜尋並申請：

  • instagram_business_basic — 帳號資訊（自動通過）
  • instagram_business_manage_messages — 收發 DM（需錄影）
  • instagram_business_manage_comments — 留言觸發（需說明）
螢幕錄影必含的畫面：
  1. 你的 IG 商業帳號收到一則使用者私訊
  2. Hailory 後台收到該訊息的 log
  3. 自動回覆訊息送出
  4. 使用者 IG 端收到回覆
錄影長度 1–3 分鐘即可。建議用旁白說明「這是 Hailory 替商家自動回覆 IG DM 的真實使用場景」。

審核時程通常 1–4 週。在審核通過前，只有 App 角色（Admin / Developer / Tester）中的帳號可以觸發 webhook 測試 — 這就是為什麼要先把自己加入 Roles。

4

設定 Webhook

App Dashboard → Instagram → Webhooks 區塊，點「Edit Callback URL」：

  • Callback URL: https://{your-domain}/webhook/instagram
    （Hailory 部署時會給你這個 URL；本地測試可用 ngrok）
  • Verify Token: 自定義隨機字串 — 例：my-hailory-verify-2026
    記下來，之後要填到 Hailory 環境變數 META_VERIFY_TOKEN

訂閱欄位（Subscribed Fields）勾選：

  • messages — 一般 DM
  • messaging_postbacks — Quick Reply / 按鈕回傳
  • comments — 留言觸發 DM
常見錯誤：「The URL couldn't be validated」
  • Callback URL 必須 HTTPS（不接受 HTTP）
  • Hailory 服務必須已經啟動並能回應 GET 請求
  • Verify Token 兩邊（Meta + Hailory）要完全一樣
5

產生 Access Token

有兩種方式，建議用 System User Token（不會過期）。

方式 A：一般 User Token（60 天有效，可 refresh）

  1. App Dashboard → Instagram → Generate Token
  2. 選擇你的 IG 帳號
  3. 勾選步驟 3 申請的全部 scopes
  4. 複製 token（很長一串）

Hailory 的 token-refresh-worker 會自動每 6h 檢查並 refresh。

方式 B：System User Token（永久有效，建議）

  1. 到 Business Settings（不是 App Dashboard）→ Users → System Users
  2. 點「Add」建立一個 System User（取名 Hailory-bot）
  3. 指派給你的 Meta App，授予 Develop App 權限
  4. 指派該 System User 為 IG Business Account 的管理員
  5. 點「Generate New Token」→ 選擇你的 App → 勾選步驟 3 的 scopes → 產生
6

在 Hailory 連結帳號

回到 Hailory 的 「頻道管理」，點「+ 新增帳號」並填入：

  • Channel: ig
  • IG User ID — 從 App Dashboard → Instagram → 你的帳號右側 Account ID 複製
  • IG Username — 你的 IG 帳號名稱（不含 @）
  • Access Token — 步驟 5 拿到的 token

儲存後系統會自動驗證連線，並開始接收訊息。

建立完成後，建議到 私訊規則 → 點「 測試」輸入一個關鍵字確認規則命中正確 — 不會送出真實訊息，但能驗證設定。

常見障礙與排除

App Review 一直退件
· 螢幕錄影必須清楚展示真實 IG DM 自動回覆，不能只是後台截圖
· 避免「廣告」「行銷」「推銷」「DM 行銷」這類字眼，改用「客戶服務自動化」「FAQ 回覆」
· 提供官網 / 品牌 IG 連結佐證真實商業
· 如果是給客戶使用的工具（不是自家用），要附 SaaS 隱私權政策、服務條款連結
Webhook 收不到訊息
· 確認 App 在 Live Mode（雖然 Development Mode 下 App Role 中的帳號也能觸發）
· 確認 IG 帳號已切換為商業帳號
· 用 App Dashboard → Webhooks → Test 按鈕送測試請求看 Hailory 有沒有收到
· 檢查 /api/dev/system 的「Last Webhook」tile — 超過 1 小時無 inbound 就是有問題
回覆失敗 error code 10
· Meta 的 24 小時 messaging window 已過期 — 用戶最後一次互動後 24 小時內才能主動發訊息
· 過期後要靠 HUMAN_AGENT tag，且僅限人工客服（不能用自動化）
Token 突然失效
· 一般 User Token 60 天過期 — Hailory 會自動 refresh，但如果你修改過 App 權限會被無效化
· 用戶把 App 從 IG 設定的「已連結 App」中移除也會立即失效
· System User Token 永久有效，建議改用這個