Instagram 連携セットアップ手順 (ViralForge)

本書は ViralForge で Instagram への自動投稿 (Feed / Reel / Carousel) を有効化するための、クライアント様側の作業手順です。

運用モードは 2 通り

モード	App Review	Business Verification	投稿可能な IG アカウント	所要期間
テストユーザー運用 (推奨初期構成)	不要	不要	App 管理者 + Tester Role に追加した IG アカウントのみ	30 分〜半日
公開サービス運用	必須 (`instagram_content_publish` 等)	必須	任意の Instagram Business アカウント	2 週間〜1 ヶ月

自社 SNS 運用や顧客少数に限定する用途であれば テストユーザー運用で十分 です。本書はまずテストユーザー運用を前提に進め、公開サービス化したい場合の追加手順を §4 にまとめます。

重要な前提

ViralForge の Instagram 連携は Instagram Graph API (Facebook Graph API 経由) を使用します。Instagram Basic Display API ではありません。

必須条件:

Instagram アカウントが Business または Creator (個人アカウントでは投稿不可)
Facebook ページを保有し、上記 Instagram アカウントと リンク済み
Meta Business Suite で両者の紐付けが完了
テストユーザー運用の場合: 投稿対象 IG にリンクした Facebook ページ管理者が Meta Developers App の Tester Role に招待・承認済み
公開サービス運用の場合: 上記 + App Review 通過 + Business Verification 完了

個人アカウントの場合は、Instagram アプリ内 設定 → アカウント → プロアカウントに切り替える で Business に変換してください。

1. 仕組み概要

Instagram Graph API への投稿は 3 step:

Media Create / Container 作成 — 画像・動画 URL と caption を Meta に渡し container ID を受け取る
Status Polling (Reel / Carousel のみ) — 非同期処理完了を status_code = FINISHED まで待機
Publish — container ID を指定して /media_publish で公開

ViralForge では services/instagram_client.py が自動実行します。

対応する投稿タイプ

タイプ	説明	上限
Feed	静止画 1 枚 + caption	JPEG 8MB、比率 4:5 / 1:1 / 1.91:1
Reel	縦型動画 + caption	MP4 1GB 以内、3〜90 秒、9:16 推奨
Carousel	画像 + 動画混在可能	最大 10 media

2. 事前準備チェックリスト

テストユーザー運用で必須

[ ] Instagram を Business / Creator に切り替え済
[ ] Facebook ページ (公開済) を保有
[ ] Facebook ページ 設定 → Instagram で IG とリンク済
[ ] Meta Business Suite で両者が同じ Business Portfolio に
[ ] Meta Developers アカウント作成済 (https://developers.facebook.com/)
[ ] 投稿対象 IG にリンクされた Facebook ページ管理者の Meta Developer 用メールアドレス

公開サービス運用で追加必須

[ ] プライバシーポリシー URL / 利用規約 URL (ViralForge 運用のため以下の URL を使ってください):
- Privacy Policy URL: https://viral-forge.net/privacy.html
- Terms of Service URL: https://viral-forge.net/terms.html
[ ] 法人登記書類 / 事業者確認書類 (Business Verification 用)

3. Meta Developers で App 作成

3.1. App 作成

https://developers.facebook.com/ にログイン
My Apps → Create App
Use case = Other、App type = Business
App 名、連絡先メール、紐づける Business Portfolio を入力

3.2. Products の追加

App Dashboard 左メニュー Add Products から:

Instagram → Set Up
Facebook Login for Business → Set Up
Instagram Graph API (UI 上 Instagram Platform と表示されることあり)

3.3. App ID / App Secret の確認

App Settings → Basic から App ID (数値) と App Secret (Show ボタンで表示) を控えます。App Secret は第三者に共有しないでください。

3.4. Permissions

必要な権限 4 つ:

instagram_basic
instagram_content_publish
pages_show_list
pages_read_engagement

テストユーザー運用: Standard Access のまま Tester Role で招待したユーザーに対してすべて動作。App Review 不要。

公開サービス運用のみ: App Review → Permissions and Features から Request Advanced Access で申請 (§4 参照)。

3.5. Tester Role 追加 (テストユーザー運用の核心)

App Dashboard 左メニュー App Roles → Roles
Testers タブで Add Testers
投稿対象 IG にリンクされた Facebook ページ管理者の Meta Developer アカウントを招待
招待された本人側で https://developers.facebook.com/requests/ にアクセスし Accept Tester Invitation

OAuth は招待 Accept したユーザーで行う必要があります。他ユーザーでログインすると This app is still in development エラーになります。

4. 公開サービス運用のみ: App Review + Business Verification

テストユーザー運用で十分な場合は §4 はスキップしてください。

4.1. App Review

instagram_content_publish 等の Advanced Access を一般公開 IG アカウントに対して使うには App Review 通過が必要。提出物:

Screencast 動画 (ViralForge 管理画面での投稿フロー、音声不要・英語字幕推奨)
ビジネス用途説明 (英語 250〜500 words)
プライバシーポリシー URL / Terms of Service URL (以下の URL を使ってください):
- Privacy Policy URL: https://viral-forge.net/privacy.html
- Terms of Service URL: https://viral-forge.net/terms.html
App Icon / App Category

審査は通常 3〜7 営業日、差し戻しで 2〜3 往復、全体 2〜4 週間を見込んでください。

4.2. Business Verification

Meta Business Manager の https://business.facebook.com/settings/security から Start Verification。法人登記簿謄本 / 納税証明書 / 公共料金請求書などを提出。審査 3〜14 日程度。

5. Access Token の仕組み

Instagram Graph API のトークンは 3 段階で交換されます。

Short-lived User Token (1 時間)
Long-lived User Token (60 日)
Page Access Token (永続) — これが ViralForge が保存するトークン

この交換は ViralForge が自動で行います。運用者は OAuth ボタンを押すだけです。

6. ViralForge 管理画面での設定

ViralForge の Instagram 連携は、全体設定 (Admin) に登録した Instagram App を organization 経由で OAuth 接続する構成です。

Admin が 全体設定 → SNSアプリ認証 → Instagram に §3.3 の App ID / App Secret を登録 (済の場合はスキップ)
組織ユーザーは 組織設定 を開き、Instagram 行の 「+ Instagramアカウントを追加」 ボタンを押下
アカウント名を入力すると Facebook の OAuth 画面に遷移。対象 Facebook ページと Instagram アカウントを選択して承認
ViralForge に戻ると Page Access Token が保存され、組織内で利用可能になります
プラン編集画面の Instagram タブを有効化

7. 投稿制限

24 時間あたり 50 post / account (Instagram Graph API 共通の上限)
Reel: MP4、1GB 以内、3〜90 秒、9:16 推奨
Carousel: 最大 10 media、image + video 混在可
Feed 画像: JPEG 8MB 以内、比率 4:5 / 1:1 / 1.91:1
caption: 最大 2,200 文字、ハッシュタグ 30 個まで

8. よくあるエラー

エラー	原因	対処
`OAuthException (code 190)`	Access Token 期限切れ / 失効	組織設定から再認証。Page Token は通常永続だがパスワード変更等で失効する
`This app is still in development`	認証ユーザーが Tester Role に未追加	§3.5 の手順で招待 + Accept
`Business Discovery Feature Limited`	公開サービス運用で App Review 未通過	審査申請状況を確認 (テストユーザー運用なら不要)
`Media ID not found`	Reel/Carousel の container が publish 前に ready にならなかった	動画サイズ・比率を確認。ViralForge 側で自動リトライ (30 秒 polling × 最大 5 回)
`Rate limit exceeded`	24h 50 post 超過	スケジュール見直し、1 時間以上空ける
`Not an Instagram Business Account`	個人アカウントのまま	Business / Creator に切り替えて再リンク

9. セキュリティ

App Secret / Page Access Token は Fernet 暗号化で DB 保存、multi-tenant 分離されています。