IG Harness × LINE Harness 連携 完全セットアップガイド

Instagram のコメント → DM → フォローゲート → LINE 友だち追加 → フォーム送信までを両プラットフォームで 1:1 紐付けるエンドツーエンド実装のセットアップ記録。2026年4月の E2E 検証で引っかかった落とし穴を全部載せ。

アーキテクチャ概要

[IG user] コメント "テストIG"
   ↓ webhook
[IG Harness Worker] CTA DM 送信 → postback → フォロー確認 → reward DM
   ↓ URL tap
[LINE Harness Worker] /r/:ref?ig=<IGSID>&form=<ID>
   ↓ redirect
[LIFF] 友だち追加 → UUID 確定 → form 送信
   ↓ linkIgIgsid()
[LINE DB] friends.ig_igsid = IGSID
   ↓ HMAC 署名付き POST /api/followers/link-line
[IG DB] followers.line_friend_uuid = UUID

IGSID と LINE UUID の両方向リンクを両 D1 に persist する。

必要な secret

IG Harness 本番 (ig-harness)

Secret	用途
IG_ACCESS_TOKEN	Meta Graph API 呼び出し用（60日長期トークン）
IG_USER_ID	Instagram Business Account ID
IG_APP_SECRET	Webhook 署名検証
IG_VERIFY_TOKEN	Webhook 登録時の challenge 認証
LINE_HARNESS_LINK_SECRET	LINE Harness から飛んでくる callback の HMAC 検証
API_KEY	管理 API 認証

LINE Harness 側

Secret	用途
IG_HARNESS_URL	https://<your-ig-worker>.workers.dev 等
IG_HARNESS_LINK_SECRET	上と同じ値（shared secret）

Meta Dashboard 設定

1. アプリ作成 — developers.facebook.com → Instagram でメッセージとコンテンツを管理
2. Instagram ビジネスアカウント追加 — テスターロール招待 → 承認
3. アクセストークン生成 — そのアカウントで「トークンを生成」
4. Webhook 設定
   • コールバック URL: https://<worker-name>.workers.dev/webhook
   • トークンを認証: Worker 側の IG_VERIFY_TOKEN と一致させる
   • サブスクライブするフィールド: messages, messaging_postbacks, comments, mentions
5. アカウントレベルサブスクリプション — アプリレベル Webhook と別に、アカウント単位でも登録必要:

   curl -X POST "https://graph.instagram.com/v25.0/{IG_USER_ID}/subscribed_apps?subscribed_fields=messages,messaging_postbacks,comments,mentions&access_token={TOKEN}"
   

6. App を Live に — Standard Access permissions を全て取得しておけば、App Review なしで一般ユーザーからも webhook が飛ぶ（テスター以外も OK）

よくある落とし穴

1. Worker リネームで Webhook URL が古いまま

Worker 名を変更（例: instagram-harness → ig-harness）すると .workers.dev サブドメインが変わる。Meta Dashboard の Webhook URL は自動更新されない → コメントが飛んでも届かない。

症状: messages_log が空、Meta 側にはコメント存在、IG API で取得可能だが Worker 側にイベントなし。

対策: Meta Dashboard → Instagram → Webhooks → コールバック URL を新 URL に書き換え + 再認証。

2. CF Workers secret の末尾改行

echo "value" | wrangler secret put X でセットすると \n が値に含まれる。

fetch(`${env.IG_HARNESS_URL}/api/followers/link-line`)
 → fetch("https://<your-ig-worker>.workers.dev\n/api/followers/link-line")
 → URL 内の \n が %0A にエンコードされ、不正パスで 404 + Cloudflare エラーコード 1042

対策: printf '%s' "value" | wrangler secret put X を使う。echo -n でも可。

3. 既存友だちが LIFF 経由で ig_igsid が書かれない

LINE Harness の /auth/callback でしか ig_igsid を書いていない初期実装では、既にテスト公式を友だち追加済みのユーザーが reward URL をタップしても OAuth フローをバイパスして LIFF 直行するため ig_igsid が書かれない（= 両 DB の cross-link が断裂）。

対策: linkIgIgsid() ヘルパーを抽出して /api/liff/link と /api/liff/send-form-link からも呼ぶ（xh パラメータの既存実装と同じパターン）。LIFF client 側も各 API 呼び出しの body に ig: params.get('ig') || '' を追加。

4. UPDATE が no-op でも IG Harness に notify すると不整合

UPDATE friends SET ig_igsid = ? WHERE ... AND (ig_igsid IS NULL OR ig_igsid = ?) は既に別 IGSID が入っている友だちだと書き込みせず 0 rows changed で返る。ここで何も考えずに IG Harness に {igsid, line_friend_uuid} を POST すると、LINE 側は元の IG を指し、IG 側は新しい IGSID の follower に別の LINE UUID を指すという食い違いが発生。

対策: result.meta.changes を確認、または直後に SELECT で現在値が送信値と一致するかチェックし、一致時のみ notify する。

5. 60日の IG トークン失効

Meta の long-lived token は 60日で失効し、手動更新不要にするには /refresh_access_token を定期的に叩いて D1 に新 token を保存する仕組みが必要。

実装パターン:

• ig_token_state テーブル (singleton row) に access_token, expires_at, refreshed_at
• Cron (5分毎でも OK) で expiry が 14 日以内なら refresh を試みる
• 保存 token → 失敗したら env secret で再試行（recovery パス）
• 全 IG API 呼び出し箇所は getIGAccessToken() ヘルパー経由（D1 優先 → env fallback）

検証方法

-- LINE 側
SELECT id, display_name, ig_igsid FROM friends WHERE ig_igsid IS NOT NULL;

-- IG 側
SELECT igsid, username, line_friend_uuid FROM followers WHERE line_friend_uuid IS NOT NULL;

両方が一致する (IGSID, LINE UUID) ペアを持っていれば E2E 成功。

Reward URL テンプレート

https://<your-line-worker>.workers.dev/r/<ref>?form=<form_id>&ig={IGSID}

{IGSID} は IG Harness が送信時に実 IGSID へ置換するプレースホルダー（リテラル文字列として gate 設定に入れる）。