agent-instagram

Agent Instagram

AI エージェント向けの Instagram DM CLI です。ブラウザーの Cookie 抽出（設定不要。Chromium ブラウザーから抽出）と、ユーザー名／パスワード認証（2FA 対応）をサポートしています。Instagram の非公開モバイル API を使用して、ダイレクトメッセージの読み取りと送信を行います。

次のいずれかのエントリーポイントを使用してください。

• グローバルインストール：agent-instagram ...
• 1 回限りの実行：bunx --package agent-messenger agent-instagram ...

主な概念

• スレッド ID = DM の会話を識別する Instagram の ID です。chat list が返す数値文字列です。
• ブラウザーの Cookie 抽出 = 推奨される認証方法です。instagram.com にログインしている Chromium ブラウザー（Chrome、Chrome Canary、Edge、Arc、Brave、Vivaldi、Chromium）から Cookie を抽出します。設定は不要です。
• ユーザー名／パスワード認証 = 代替の認証方法です。Instagram の認証情報を使用して認証します。SMS または認証アプリによる 2 要素認証に対応しています。
• HTTP ベース = CLI コマンドごとに HTTP リクエストを送信し、結果を返します。永続接続やバックグラウンドプロセスはありません。SDK ではさらに、DM のストリーミング用のリアルタイムリスナー（InstagramHybridListener、InstagramRealtimeListener）も利用できます。以下のSDK：リアルタイムイベントを参照してください。
• 複数アカウント = 複数の Instagram アカウントを保存できます。auth list と auth use を使用して切り替えます。
• DM 専用 = この CLI は Instagram ダイレクトメッセージに特化しています。投稿、ストーリー、フォロワーは管理しません。

クイックスタート

# Extract cookies from browser (recommended — zero-config)
agent-instagram auth extract

# Or: Log in with Instagram credentials (fallback)
agent-instagram auth login --username myaccount --password "mypassword"

# List DM conversations
agent-instagram chat list

# Send a message
agent-instagram message send <thread-id> "Hello from agent-instagram"

認証の流れ

Instagram では、2 つの認証方法を利用できます。

1. ブラウザーの Cookie 抽出（推奨）：instagram.com にログインしている Chromium ブラウザーからセッション Cookie を抽出します。設定不要で、パスワードも必要ありません。
2. ユーザー名／パスワードでのログイン：Instagram の認証情報を使用して認証します。必要に応じて 2 要素認証を行います。

セッションはローカルに保存されるため、コマンドを実行するたびに再認証する必要はありません。セッションが存在しない場合、ブラウザーからの抽出が自動的に実行されます。

ブラウザーの Cookie 抽出（推奨）

agent-instagram auth extract は、Chrome、Edge、Arc、Brave、Vivaldi、Chromium から Instagram のセッション Cookie を読み取ります。これらのブラウザーのいずれかで instagram.com にログインしている必要があります。

# Extract cookies from browser — zero-config
agent-instagram auth extract

# With debug output
agent-instagram auth extract --debug

# Scan custom Chromium profile/user-data dirs
agent-instagram auth extract --browser-profile ~/browser-data
agent-instagram auth extract --browser-profile "$HOME/work-profile,$HOME/personal-profile"

--browser-profile には、Chromium のプロファイル／ユーザーデータディレクトリを複数回指定するか、カンマ区切りで指定できます。エージェントブラウザーのプロファイル、カスタム Chrome ユーザーデータディレクトリ、またはポータブルブラウザープロファイルで使用します。

仕組み：CLI はブラウザーの SQLite Cookie データベースから、Instagram の Cookie（sessionid、csrftoken、ds_user_id）を直接読み取ります。ブラウザーの自動操作も、パスワードの入力要求もありません。セッションは ~/.config/agent-messenger/ にローカル保存されます。

再抽出が必要な場合：ブラウザーの Cookie には有効期限があります。セッションの有効期限が切れたら、agent-instagram auth extract を再実行するか、自動抽出に任せてください（有効なセッションが存在しない場合、CLI は自動的に抽出を試みます）。

対応ブラウザー：Chrome、Chrome Canary、Edge、Arc、Brave、Vivaldi、Chromium

エージェントの動作（必須）

アカウントが設定されていないためにコマンドが失敗した場合、エージェントは認証フローを自ら実行する必要があります。ユーザーにコマンドの実行を指示してはいけません。すべてエージェントが実行します。

ステップ 1：既存のアカウントを確認する

agent-instagram auth list

アカウントが存在する場合は、agent-instagram auth use <account-id> を使用してから、元のコマンドを再試行します。

ステップ 2：まずブラウザーからの抽出を試す

agent-instagram auth extract
# -> {"authenticated":true,"account_id":"12345678","username":"myaccount"}

抽出に成功した場合は、元のコマンドを実行します。

ステップ 3：抽出に失敗した場合は、認証情報を尋ねる

Instagram のユーザー名とパスワードをユーザーに尋ねます。ユーザーが提供する必要があるのは、この 2 つだけです。

ステップ 4：ログインを開始する

agent-instagram auth login --username myaccount --password "mypassword"
# -> {"authenticated":true,"account_id":"myaccount","username":"myaccount"}

ステップ 4：必要に応じて 2FA に対応する

ログインの結果が two_factor_required の場合は、確認コードをユーザーに尋ねます。

# -> {"two_factor_required":true,"two_factor_identifier":"abc123","message":"..."}

続いて、確認を完了します。

agent-instagram auth verify --username myaccount --code 123456 --identifier abc123
# -> {"authenticated":true,"account_id":"myaccount","username":"myaccount"}

ステップ 5：元のコマンドを再試行する

認証に成功したら、ユーザーが最初に依頼した操作をすぐに実行します。

よく使う認証コマンド

agent-instagram auth extract                 # Extract cookies from browser (recommended)
agent-instagram auth extract --debug         # Extract with debug output
agent-instagram auth status                  # Check current auth state
agent-instagram auth status --account <id>   # Check specific account
agent-instagram auth list                    # List all stored accounts
agent-instagram auth use <id>                # Switch active account
agent-instagram auth logout                  # Remove current account
agent-instagram auth logout --account <id>   # Remove specific account

メモリ

エージェントは、セッションをまたいで保持されるメモリとして ~/.config/agent-messenger/MEMORY.md ファイルを管理します。これはエージェントが管理します。CLI はこのファイルを読み書きしません。メモリファイルを管理するには、Read ツールと Write ツールを使用してください。

メモリの読み込み

すべてのタスクの開始時に、Read ツールを使って ~/.config/agent-messenger/MEMORY.md を読み込み、以前に見つかったスレッド ID、連絡先名、設定を確認してください。

• ファイルがまだ存在しない場合は問題ありません。メモリを使わずに続行し、保存する有用な情報が初めて見つかった時点でファイルを作成してください。
• ファイルを読み込めない場合（権限がない、ディレクトリがないなど）は、メモリを使わずに続行してください。

メモリの書き込み

有用な情報を見つけたら、Write ツールを使って ~/.config/agent-messenger/MEMORY.md を更新してください。書き込みが必要となるタイミングの例：

• スレッド ID と連絡先名を見つけた後（chat list から）
• グループ会話の名前と参加者を見つけた後
• ユーザーから別名や設定の指定があったとき（「このグループを家族グループと呼んで」「仕事のチャットは X」など）

書き込む際は、ファイルの内容全体を含めてください。Write ツールはファイル全体を上書きします。

保存する情報

• 連絡先名またはグループ名とスレッド ID
• 自分のユーザー名とユーザー ID
• ユーザーが指定した別名（「家族グループ」「仕事のチャット」など）
• よく参照するスレッド ID
• やり取りの中で示されたユーザーの設定

保存しない情報

認証情報、パスワード、セッショントークンなど、機密データは絶対に保存しないでください。メッセージの全文も保存しないでください（ID とチャットのコンテキストのみを保存してください）。

形式／例

# Agent Messenger Memory

## Instagram Account

- Username: myaccount
- User ID: 12345678

## Conversations

- `340282366841710300949128138443434234567` - Alice (private)
- `340282366841710300949128138443434234568` - Bob (private)
- `340282366841710300949128138443434234569` - Project Team (group, 5 members)

## Aliases

- "alice" -> `340282366841710300949128138443434234567`
- "project" -> `340282366841710300949128138443434234569` (Project Team)

## Notes

- User prefers --pretty output

メモリを利用すると、chat list を繰り返し呼び出す手間を省けます。以前のセッションでスレッド ID が分かっている場合は、その ID を直接使用してください。

コマンド

認証コマンド

# Extract cookies from browser (recommended — zero-config)
agent-instagram auth extract
agent-instagram auth extract --debug

# Log in (interactive: prompts for username/password)
agent-instagram auth login

# Log in (non-interactive: pass credentials as flags)
agent-instagram auth login --username <username> --password <password>

# Log in with debug output (shows raw API responses)
agent-instagram auth login --username <username> --password <password> --debug

# Complete 2FA verification (non-interactive)
agent-instagram auth verify --username <username> --code <code> --identifier <identifier>

# Resolve a security challenge — send verification code
agent-instagram auth challenge --username <username> --method email
agent-instagram auth challenge --username <username> --method sms

# Resolve a security challenge — submit verification code
agent-instagram auth challenge --username <username> --code <code>

# Check auth status
agent-instagram auth status
agent-instagram auth status --account <id>

# List stored accounts
agent-instagram auth list

# Switch active account
agent-instagram auth use <id>

# Remove account
agent-instagram auth logout
agent-instagram auth logout --account <id>

Whoami コマンド

# Show current authenticated user
agent-instagram whoami
agent-instagram whoami --pretty
agent-instagram whoami --account <account-id>

出力には、認証されたユーザーの本人確認情報が含まれます。

チャットコマンド

# List DM conversations (sorted by most recent activity)
agent-instagram chat list
agent-instagram chat list --limit 50
agent-instagram chat list --account <id>

# Search conversations by name
agent-instagram chat search "alice"
agent-instagram chat search "alice" --limit 10
agent-instagram chat search "alice" --account <id>

出力には次の情報が含まれます：

• id - スレッド ID
• name - 連絡先名またはグループ名
• type - private または group
• is_group - 真偽値
• participant_count - 参加者数
• unread_count - 未読メッセージ数
• last_message - 最新メッセージのプレビュー

メッセージコマンド

# List messages in a conversation
agent-instagram message list <thread-id>
agent-instagram message list <thread-id> --limit 50
agent-instagram message list <thread-id> --limit 10 --account <id>

# Send a text message to a thread
agent-instagram message send <thread-id> <text>
agent-instagram message send <thread-id> "Hello!" --account <id>

# Send a text message to a user by @username
agent-instagram message send-to <username> <text>
agent-instagram message send-to @alice "Hello!"

# Search messages by text content
agent-instagram message search <query>
agent-instagram message search "meeting" --thread <thread-id>
agent-instagram message search "hello" --limit 10

# Search Instagram users by username
agent-instagram message search-users <query>
agent-instagram message search-users "alice"

出力形式

JSON（デフォルト）

すべてのコマンドは、AI が利用できるよう、デフォルトで JSON を出力します：

{
  "id": "340282366841710300949128138443434234567",
  "name": "Alice",
  "type": "private",
  "is_group": false,
  "participant_count": 2,
  "unread_count": 3,
  "last_message": {
    "id": "29876543210987654",
    "thread_id": "340282366841710300949128138443434234567",
    "from": "12345678",
    "timestamp": "2026-03-29T10:30:00.000Z",
    "is_outgoing": false,
    "type": "text",
    "text": "See you tomorrow!"
  }
}

Pretty（人が読みやすい形式）

--pretty フラグを使うと、整形された出力になります：

agent-instagram chat list --pretty

グローバルオプション

オプション	説明
--pretty	JSON の代わりに、人が読みやすい形式で出力します
--account <id>	このコマンドで特定のアカウントを使用します

よくあるパターン

未読メッセージを確認する

# List conversations to see unread counts
agent-instagram chat list --limit 20

# Read messages from a specific conversation
agent-instagram message list <thread-id> --limit 10

連絡先にメッセージを送信する

# Find the contact first
agent-instagram chat search "Alice"

# Send to the thread ID
agent-instagram message send <thread-id> "Hey, are we still on for tomorrow?"

グループ会話に返信する

# Find the group
agent-instagram chat search "Project Team"

# Send to the group thread
agent-instagram message send <thread-id> "Status update: deployment complete."

エラー処理

すべてのコマンドは、一貫した形式でエラーを返します：

{
  "error": "Not authenticated. Run \"agent-instagram auth login --username <username>\" first."
}

よくあるエラー：

• Not authenticated - アカウントが設定されていません。auth extract または auth login を実行してください。
• Session expired or missing - セッションが無効です。ブラウザーから再抽出するには auth extract を実行するか、再度ログインするには auth login を実行してください。
• Login failed - ユーザー名またはパスワードが間違っています。認証情報を確認してください。
• Two-factor authentication failed - 2FA コードが間違っています。新しいコードを取得し、auth verify をもう一度実行してください。
• Rate limited - リクエストが多すぎます。しばらく待ってから再試行してください。

注意事項

• セッションの永続化：ログインセッションは ~/.config/agent-messenger/instagram/ に保存されます。Instagram が異常なアクティビティを検知すると、セッションの有効期限が切れることがあります。
• アカウント停止のリスク：Instagram は自動化された動作を監視しています。大量のメッセージ送信、短時間での連続送信、一括操作は避けてください。複数のメッセージを送信する場合は、コマンドの実行間隔を空けてください。
• 複数アカウント：複数の Instagram アカウントを同時に保存できます。auth list でアカウント一覧を確認し、auth use <id> で切り替えてください。
• テキストのみ：現在はテキストメッセージのみをサポートしています。メディア、音声メッセージ、リアクションは読み取り専用です（メッセージ一覧ではタイプのインジケーターとして表示されます）。
• agent-instagram はデフォルトで JSON を返し、--pretty を指定するとインデント付きの出力を返します。

トラブルシューティング

agent-instagram: command not found

agent-instagram は npm パッケージ名ではありません。 npm パッケージ名は agent-messenger です。

パッケージがグローバルにインストールされている場合は、agent-instagram を直接使用してください。

agent-instagram chat list --pretty

パッケージがインストールされていない場合は、--package を使用してインストールして実行してください。

npx -y --package agent-messenger agent-instagram chat list --pretty
bunx --package agent-messenger agent-instagram chat list --pretty
pnpm dlx --package agent-messenger agent-instagram chat list --pretty

--package agent-messenger を指定せずに npx agent-instagram、bunx agent-instagram、または pnpm dlx agent-instagram を実行しないでください。 agent-instagram は npm パッケージ名ではないため、失敗するか、誤ったパッケージがインストールされます。

ログイン時に「challenge_required」エラーが発生する

Instagram で追加の認証が必要な場合があります（例：Instagram アプリで本人確認を行う）。スマートフォンで Instagram アプリを開き、セキュリティ確認を完了してから、もう一度ログインしてください。

セッションが頻繁に期限切れになる

Instagram は、デバイスのフィンガープリントとアクティビティのパターンに基づいてセッションを無効化します。セッションが頻繁に期限切れになる場合は、次の点に注意してください。

1. 頻繁な再認証を避ける
2. API 呼び出しの間隔を空ける
3. 複数の IP アドレス間を短時間で切り替えない

SDK：リアルタイムイベント

InstagramHybridListener は Instagram の MQTToT トランスポート（edge-mqtt.facebook.com への永続的な TLS 接続）で接続し、接続に失敗すると自動的にポーリングに切り替えます。上限付きの指数バックオフでリアルタイム接続を再試行します。ほとんどのユースケースでは、このリスナーを推奨します。

InstagramRealtimeListener はポーリングへのフォールバックがない、純粋なリアルタイム接続方式です。MQTToT に直接接続し、再接続を自身で処理したい場合に使用してください。

どちらも非公式のプライベート API を使用しているため、既存のポーリングリスナーと同じリスクがあります。

セットアップ

import { InstagramClient, InstagramHybridListener } from 'agent-messenger/instagram'

const client = await new InstagramClient().login()
const listener = new InstagramHybridListener(client, {
  pollInterval: 5000,         // fallback poll interval in ms
  realtimeRetryBaseMs: 2000,  // backoff base for realtime reconnect
  realtimeRetryMaxMs: 60000,  // backoff cap
})

または、純粋なリアルタイム接続の場合：

import { InstagramClient, InstagramRealtimeListener } from 'agent-messenger/instagram'

const client = await new InstagramClient().login()
const listener = new InstagramRealtimeListener(client)

イベントのリスニング

listener.on('connected', ({ userId, transport }) => {
  // transport is 'realtime' or 'polling' (hybrid only)
  console.log(`Listening as ${userId} via ${transport}`)
})

listener.on('message', (msg) => {
  // msg.id, msg.thread_id, msg.from, msg.timestamp
  // msg.is_outgoing, msg.type, msg.text, msg.media_url
  if (msg.is_outgoing) return
  console.log(`[${msg.thread_id}] ${msg.from}: ${msg.text}`)
})

listener.on('error', (err) => {
  console.error(err.message)
})

listener.on('disconnected', () => {
  // hybrid listener retries realtime automatically
})

ライフサイクル

await listener.start()  // connects via MQTToT (or starts polling fallback)
listener.stop()         // clean shutdown

イベントの種類

イベント	ペイロード（Hybrid）	ペイロード（Realtime / Polling）	説明
message	InstagramMessageSummary	InstagramMessageSummary	新しい DM を受信
connected	{ userId: string; transport: 'realtime' | 'polling' }	{ userId: string }	リスナーがアクティブ
disconnected	—	—	接続が閉じられた
error	Error	Error	接続または API のエラー