KakaoTalk

Tip: After npm install -g agent-messenger, agent-kakaotalk is available directly. For one-off execution without a global install you can use npm exec --package agent-messenger agent-kakaotalk ..., pnpm dlx --package agent-messenger agent-kakaotalk ..., yarn dlx agent-messenger agent-kakaotalk ..., or bunx --package agent-messenger agent-kakaotalk ....

Key Concepts

Before diving in, a few things about KakaoTalk's architecture:

Quick Start

# 1. Login (registers as sub-device — desktop app stays running)
agent-kakaotalk auth login

# 2. List chat rooms
agent-kakaotalk chat list

# 3. Send a message
agent-kakaotalk message send <chat-id> "Hello from agent-kakaotalk!"

# 4. List messages in a chat
agent-kakaotalk message list <chat-id>

Authentication

The CLI authenticates by registering as a sub-device (tablet slot by default). Your desktop app keeps running.

Login

Registers the CLI as a sub-device using the tablet slot by default. Your desktop app keeps running.

# Interactive — prompts for email and password
agent-kakaotalk auth login

# Non-interactive (for AI agents)
agent-kakaotalk auth login --email user@example.com --password mypass

On first login, KakaoTalk requires device verification:

1. The CLI requests a passcode from KakaoTalk's server
2. A numeric code is displayed in the terminal
3. Enter the code on your phone when prompted
4. The CLI polls until you confirm — login completes automatically

Device Slots

KakaoTalk allows these simultaneous sessions:

• Phone — always active, never affected by the CLI
• PC — will kick KakaoTalk desktop if the CLI uses this slot
• Tablet (default) — safe if you don't use a tablet for KakaoTalk

# Default: tablet slot (safe for most users)
agent-kakaotalk auth login

# Use PC slot instead (kicks desktop app)
agent-kakaotalk auth login --device-type pc

# Force login even if slot is occupied
agent-kakaotalk auth login --device-type tablet --force

Auth Management

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

# List all stored accounts
agent-kakaotalk auth list

# Switch the current account
agent-kakaotalk auth use <account-id>

# Remove stored credentials
agent-kakaotalk auth logout
agent-kakaotalk auth logout --account <account-id>

Multi-Account

KakaoTalk supports multiple accounts. Each login stores credentials separately, keyed by user ID.

# List all stored accounts
agent-kakaotalk auth list

# Switch the current account
agent-kakaotalk auth use <account-id>

# Use a specific account for any command
agent-kakaotalk chat list --account <account-id>
agent-kakaotalk message send <chat-id> "Hello" --account <account-id>

Without --account, commands use the current (default) account.

Commands

Chat Commands

# List all chat rooms (sorted by most recent activity)
agent-kakaotalk chat list
agent-kakaotalk chat list --pretty
agent-kakaotalk chat list --account <account-id>

# Fetch all chats (paginate beyond login snapshot)
agent-kakaotalk chat list --all

# Search for a chat by display name
agent-kakaotalk chat list --search "Alice"
agent-kakaotalk chat list --all --search "project"

# Resolve user-set room titles (one extra LOCO call per chat — slower but matches the in-app room name)
agent-kakaotalk chat list --resolve-titles

Output includes:

• chat_id — numeric chat room ID
• type — chat type (1:1, group, open chat)
• display_name — comma-separated member names
• title — user-set room title (only populated with --resolve-titles; otherwise null). For open chats (OM / OD) without a user-set title, falls back to the OpenLink room name (one extra INFOLINK LOCO call per such chat).
• active_members — number of active members
• unread_count — unread message count
• last_message — most recent message preview, including author_name when the sender's nickname is known from the chat list (otherwise null)

Member Commands

# List all members of a chat room (uses LOCO GETMEM — one call per invocation)
agent-kakaotalk member list <chat-id>
agent-kakaotalk member list <chat-id> --pretty
agent-kakaotalk member list <chat-id> --account <account-id>

Each member includes:

• user_id — numeric user ID (string for safety)
• nickname — display name in this chat (open chats may differ from the user's main Kakao nickname)
• profile_image_url, full_profile_image_url, original_profile_image_url
• status_message, country_iso
• user_type — KakaoTalk's user type (100 = friend, 1000 = open profile, etc.); null when the server omits the field
• open_token, open_profile_link_id, open_permission — open-chat-only fields (null for normal chats; open_permission is 1=OWNER, 2=NONE, 4=MANAGER, 8=BOT)

SDK-only: KakaoTalkClient.getMembersByIds(chatId, userIds) is available for the >100-member case where you already have specific user IDs to resolve (typically from a CHATONROOM mi array). It is intentionally not exposed via the CLI because acquiring those IDs requires a CHATONROOM call that is also SDK-only. Use agent-kakaotalk member list for the common case.

Message Commands

# List messages in a chat room
agent-kakaotalk message list <chat-id>
agent-kakaotalk message list <chat-id> -n 50
agent-kakaotalk message list <chat-id> --from <log-id>
agent-kakaotalk message list <chat-id> --pretty

# Send a text message
agent-kakaotalk message send <chat-id> "Hello world"
agent-kakaotalk message send <chat-id> "Hello world" --pretty

# Use a specific account
agent-kakaotalk message list <chat-id> --account <account-id>
agent-kakaotalk message send <chat-id> "Hello" --account <account-id>

Each message includes:

• log_id — unique message identifier
• type — message type (1 = text, 2 = photo, 12 = sticker, 20 = animated sticker, etc.)
• author_id — sender's user ID
• author_name — sender's nickname when known from the chat list (otherwise null; only the room's "display members" are cached)
• message — message text content (empty string for non-text messages like stickers)
• attachment — parsed JSON metadata for non-text messages (e.g. photo URL/dimensions, sticker path), or null for plain text. Shape varies by type; treat as an opaque object and narrow per message type.
• sent_at — Unix timestamp (milliseconds)

Fetching More Messages

The CLI handles internal pagination automatically. Just increase -n to get more messages. Pagination is capped at ~4,000 raw messages (50 pages × 80 per page). If the cap is hit, a warning is printed to stderr and results may be incomplete.

# Get latest 20 messages (default)
agent-kakaotalk message list 9876543210

# Get 50 messages
agent-kakaotalk message list 9876543210 -n 50

# Get 200 messages
agent-kakaotalk message list 9876543210 -n 200

# Get messages newer than a known log ID (forward only)
agent-kakaotalk message list 9876543210 --from 123456789

Whoami Command

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

Output includes:

• user_id — your KakaoTalk user ID
• nickname — your display name
• profile_image_url — profile image thumbnail URL
• original_profile_image_url — original profile image URL
• status_message — your status message
• account_display_id — your KakaoTalk ID (may be null if not set)
• background_image_url — background image URL
• original_background_image_url — original background image URL
• fullname — real name (may be null)
• account_email — account email (may be null)
• pstn_number — phone number (may be null)
• email_verified — whether email is verified (may be null)

Global Options

Storage

• Credentials stored in ~/.config/agent-messenger/kakaotalk-credentials.json (0600 permissions)

Limitations

• No file upload or download

• No channel/chat room creation or management

• No friend list management

• No reactions or emoji

• No message editing or deletion

• No open chat browsing or joining

• No search across chats

• Read-only for rich content: photos, stickers, files, and other non-text messages are exposed via the attachment field on each message, but sending them is not supported

• Chat IDs are numeric and not human-readable — use chat list to discover them

Troubleshooting

agent-kakaotalk: command not found

agent-kakaotalk is NOT the npm package name. The npm package is agent-messenger.

# If installed globally
agent-kakaotalk chat list --pretty

# If not installed, use --package
npx -y --package agent-messenger agent-kakaotalk chat list --pretty

NEVER run npx agent-kakaotalk without --package agent-messenger. It will fail or install a wrong package.

Device slot occupied

If login fails because the tablet slot is occupied:

# Option 1: Use the PC slot instead
agent-kakaotalk auth login --device-type pc --force

# Option 2: Force the tablet slot (kicks existing tablet session)
agent-kakaotalk auth login --device-type tablet --force

Passcode verification timeout

If the passcode expires before you confirm on your phone:

1. Run agent-kakaotalk auth login again — a new passcode will be generated
2. Confirm the code on your phone within the time limit
3. The CLI automatically completes login after confirmation

AI Agent Integration

See skills/agent-kakaotalk/ for:

• Complete skill documentation
• Common patterns for AI agent workflows