Agent MessengerAgent Messenger
Platform Guides

KakaoTalk

Complete reference for the agent-kakaotalk CLI.

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:

TermDescription
LOCO protocolKakaoTalk's binary messaging protocol. The CLI handles this internally — you never touch it.
Chat roomA conversation (1:1, group, or open chat). Referenced by a numeric chat ID.
Device slotsKakaoTalk allows one phone + one PC + one tablet session simultaneously.
Sub-deviceA secondary device (PC or tablet). The CLI logs in as a sub-device so your phone session is never affected.
Passcode verificationWhen registering a new device, KakaoTalk displays a code that you confirm on your phone.
Log IDA unique numeric identifier for each message, used for pagination.

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>

auth status checks stored credential state only. Kakao validates the access token when a command opens a LOCO session. If the token has expired or been revoked, commands print an error with a specific message and code:

{
  "error": "KakaoTalk LOGINLIST invalid access token (status -950)",
  "code": "invalid_access_token"
}

Run agent-kakaotalk auth login before retrying. Other explicit server rejections use code: "login_rejected" and identify the returned status in the error message. Connection closes and timeouts remain transport failures and keep their existing messages.

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)

Chat Leave

# Leave a chat room (works on 1:1, group, open, and PlusChat rooms)
agent-kakaotalk chat leave <chat-id>
agent-kakaotalk chat leave <chat-id> --pretty
agent-kakaotalk chat leave <chat-id> --account <account-id>

Output (JSON by default; --pretty pretty-prints the same JSON):

{ "success": true, "status_code": 0, "chat_id": "9876543210" }

Member Commands

# List all members of a chat room using a fail-closed, read-only snapshot
agent-kakaotalk member list <chat-id>
agent-kakaotalk member list <chat-id> --pretty
agent-kakaotalk member list <chat-id> --account <account-id>

# Return an explicitly partial snapshot instead of failing
agent-kakaotalk member list <chat-id> --allow-partial

# Opt in to room entry (CHATONROOM) when the read-only snapshot is incomplete
agent-kakaotalk member list <chat-id> --allow-room-entry
agent-kakaotalk member list <chat-id> --allow-room-entry --allow-partial

By default, member listing uses two read-only CHATINFO observations and two GETMEM observations. The command returns only when the active count, display-member subset, and full member-ID set remain stable across the observations and the member records match the active count. It does not enter the room with CHATONROOM; incomplete or changing snapshots fail (member_snapshot_changed_or_incomplete) instead of returning a guessed member list. In some large open chats GETMEM returns fewer records than the active member count, so the default command fails there.

--allow-partial prints the whole snapshot object instead of a bare member array and returns it even when it is incomplete:

{
  "chat_id": "9876543210",
  "active_members": 1414,
  "members": [{ "user_id": "1234567890", "nickname": "Alice" }],
  "complete": false,
  "consistency_basis": "stable_double_read_chatinfo_getmem",
  "incomplete_reason": "member_count_mismatch"
}

incomplete_reason is member_count_mismatch when the observations were stable but the collected records do not match the active count, or membership_changed when the observations disagreed (members joined or left during the read). A mismatch alone does not say why records are missing. incomplete_reason is absent when complete is true.

--allow-room-entry lets an incomplete read-only snapshot be filled from the room's member ID list: it sends CHATONROOM, resolves the IDs GETMEM did not return with MEMBER (100 IDs per request), and compares the result with CHATINFO taken before and after collection. The result is complete only when both CHATINFO observations agree and every member ID was resolved into exactly the active count; consistency_basis is then chatonroom_ids_member_batch. Without --allow-partial the output is still a bare member array and an incomplete result still fails.

Side effect: CHATONROOM is the room-entry command. Sending it can advance this account's unread state for the chat, so the chat may show as read. It is only sent with --allow-room-entry, and only when the read-only snapshot is incomplete.

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 not exposed as its own CLI command; member list --allow-room-entry uses it internally. Use agent-kakaotalk member list for the common case.

Open Chat Moderation

Open chats only; the account must be the room's host or a co-host. The open chat link ID is resolved from the chat ID (login snapshot first, then read-only CHATINFO). Regular chats fail with Chat <chat-id> is not an open chat before any moderation packet is sent.

# Preview only: without --force, prints a warning and exits 1 without connecting
agent-kakaotalk member kick <chat-id> <user-id>

# Kick a member (irreversible; also blocks them from rejoining via the link)
agent-kakaotalk member kick <chat-id> <user-id> --force
agent-kakaotalk member kick <chat-id> <user-id> --force --pretty
agent-kakaotalk member kick <chat-id> <user-id> --force --account <account-id>

# List members on the room's kick list
agent-kakaotalk member kick-list <chat-id>
agent-kakaotalk member kick-list <chat-id> --pretty
agent-kakaotalk member kick-list <chat-id> --account <account-id>

# Remove a member from the kick list so they can rejoin (does not re-add them)
agent-kakaotalk member unkick <chat-id> <user-id>
agent-kakaotalk member unkick <chat-id> <user-id> --pretty
agent-kakaotalk member unkick <chat-id> <user-id> --account <account-id>

member kick without --force:

{
  "warning": "Kicking is irreversible and blocks the member from rejoining. Use --force to confirm.",
  "action": "kick",
  "chat_id": "9876543210",
  "user_id": "1234567890"
}

member kick --force and member unkick:

{ "success": true, "status_code": 0, "chat_id": "9876543210", "user_id": "1234567890" }

member kick-list:

{
  "success": true,
  "status_code": 0,
  "chat_id": "9876543210",
  "members": [{ "user_id": "1234567890", "nickname": "Alice", "chat_id": "9876543210", "kicked_at": null }]
}

nickname, chat_id, and kicked_at are null when the server omits them. A server rejection (for example, missing host or co-host permission) is reported as success: false with the server's non-zero status_code, and the process exits non-zero. Only member kick has been used against a live server; the KLSYNC and KLDELITEM request shapes and the kick-list response fields are unverified, so a successful kick-list response without a kickMembers array fails with get_kick_list_failed instead of returning an empty list.

CommandLOCO opcode
member kickKICKMEM
member kick-listKLSYNC
member unkickKLDELITEM

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

# Read history losslessly, oldest first, one page at a time
agent-kakaotalk message page <chat-id> --from <log-id>
agent-kakaotalk message page <chat-id> --from <log-id> -n 50
agent-kakaotalk message page <chat-id> --pretty

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

# Send a quoted reply (looks the target up in the latest 100 messages)
agent-kakaotalk message send <chat-id> "Replying to this" --reply-to <log-id>

# Send a quoted reply to a target you already have (no history lookup)
agent-kakaotalk message send <chat-id> "Replying to this" \
  --reply-to-json '{"log_id":"<log-id>","author_id":<author-id>,"message":"<target text>","type":1}'

# Mention (tag) members; the text must contain @<name> for each one
agent-kakaotalk message send <chat-id> "@Alice hello" --mention <user-id>
agent-kakaotalk message send <chat-id> "@Alice @Bob hello" --mention <user-id>:Alice --mention <user-id>:Bob
agent-kakaotalk message send <chat-id> "@Alice agreed" --reply-to <log-id> --mention <user-id>:Alice

# Send a file (auto-routes by MIME: photo / video / audio / generic file)
agent-kakaotalk message upload <chat-id> ./photo.jpg
agent-kakaotalk message upload <chat-id> ./clip.mp4
agent-kakaotalk message upload <chat-id> ./voice.m4a
agent-kakaotalk message upload <chat-id> ./report.pdf

# Send a multi-photo gallery (2+ images in one message)
agent-kakaotalk message upload <chat-id> ./img1.jpg ./img2.jpg ./img3.jpg

# Force a specific kind (override auto-routing)
agent-kakaotalk message upload <chat-id> ./clip.mp4 --as file
agent-kakaotalk message upload <chat-id> ./data.bin --mime application/octet-stream

# Mark messages as read up to a given log ID
agent-kakaotalk message mark-read <chat-id> <log-id>
agent-kakaotalk message mark-read <chat-id> <log-id> --link-id <li>   # open chats only

# Show the typing indicator ("..." dots) for ~5s
agent-kakaotalk message typing <chat-id>
agent-kakaotalk message typing <chat-id> --link-id <li>   # open chats only

# Use a specific account
agent-kakaotalk message list <chat-id> --account <account-id>
agent-kakaotalk message page <chat-id> --from <log-id> --account <account-id>
agent-kakaotalk message send <chat-id> "Hello" --account <account-id>
agent-kakaotalk message upload <chat-id> ./photo.jpg --account <account-id>
agent-kakaotalk message typing <chat-id> --account <account-id>

--reply-to <log-id> builds the quote from the chat's latest 100 messages and errors out with code: "reply_target_not_found" if the target is not there. --reply-to-json takes the target as a JSON object (log_id, author_id, message, type, optional link_id for open chats) and sends without reading history, so it also works for older messages. Ids may be decimal strings or bare integers; large ids are parsed exactly. The two flags cannot be combined.

message send prints the send result (success, status_code, chat_id, log_id, sent_at) and exits non-zero when success is false, the same as upload, mark-read, and typing. A send is success: false when the server returns a non-zero status or no log_id.

No CLI command: Read status is available only through the SDK: use getReadWatermarks and computeReadStatus to answer "who has read this message?". getReadWatermarks returns a one-time snapshot; the SDK does not keep it up to date. Because it sends CHATONROOM, which enters the room and may clear your own unread count (#315), call it once per chat per LOCO session. Your code owns the snapshot from then on: apply listener read events to your stored watermarks, only ever moving a watermark forward, instead of polling. On disconnected, discard the stored watermarks and seed each chat again after the reconnect.

Mentioning Users

--mention <user-id> tags a member so KakaoTalk renders the @name as a mention and notifies them. The text must already contain @<name> for every mentioned user. Repeat the flag to tag several users. The CLI also accepts --mention together with --reply-to, but mentions inside a quoted reply have not yet been verified against a live server.

# Name is looked up from the chat's member list (the member's nickname in this chat)
agent-kakaotalk message send <chat-id> "@Alice the build is green" --mention 1234567890

# Pass the name explicitly as <user-id>:<name> (no member lookup)
agent-kakaotalk message send <chat-id> "@Alice @Bob standup in 5" --mention 1234567890:Alice --mention 2345678901:Bob

# Mention inside a quoted reply
agent-kakaotalk message send <chat-id> "@Alice agreed" --reply-to <log-id> --mention 1234567890:Alice
  • A bare <user-id> is resolved to that member's nickname in the chat. If the nickname cannot be resolved, the command errors out without sending; pass <user-id>:<name> instead.
  • Every mentioned @<name> must appear in the text as a whole tag. If one is missing, the command errors out without sending and names the missing @<name>. A Latin name followed directly by another Latin letter or digit does not count (@Kimberly does not tag Kim).
  • Two different users with the same name cannot be told apart, so the command errors out without sending.
  • The same user can be tagged more than once in one message; each @<name> occurrence is tagged.
  • Output is the same send result as a plain message send.

Sending Attachments

message upload sends photos, videos, audio, and arbitrary files to a chat. The CLI sniffs the MIME type from the filename and dispatches to the matching KakaoTalk message type, so the common case is a single command and a file path:

agent-kakaotalk message upload <chat-id> ./report.pdf

Routing rules:

Filename / MIMESent asKakaoTalk renders it as
image/* (.jpg, .png, .gif, .webp)photoInline image with tap-to-zoom
video/* (.mp4, .mov, .webm)videoInline player with play button
audio/* (.m4a, .mp3, .wav, .ogg)audioVoice-message bubble with waveform
anything elsefileGeneric file attachment with download icon

Pass 2+ files (or --as multi) to send a multi-photo gallery in one message. Override the auto-routing with --as <photo|video|audio|file|multi> when you need explicit control — for example, to send an .mp4 as a generic downloadable file instead of an inline video. Use --mime <type> to override MIME detection (handy for extension-less files).

Output (JSON by default; --pretty pretty-prints the same JSON):

{ "success": true, "status_code": 0, "chat_id": "9876543210", "log_id": "3846830417126748160", "sent_at": 1779509936 }

All attachment kinds use the same SHIP / POST / COMPLETE LOCO pipeline (and MSHIP / MPOST / FORWARD for multi-photo). Each upload opens one fresh TCP+LOCO connection per attachment; multi-photo opens N connections in parallel.

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)
  • mentions — present only when the message tags users: [{ "user_id": "1234567890", "at": [1], "len": 5 }]. user_id is the tagged user as an exact decimal string, at lists which @ characters in message (1-based, counting every @) start that user's tag, and len is the tagged name's length without the @.
  • scope — (optional) raw chat-log scope number, included only when the server sends it. Observed values: 1 for ordinary messages, 3 for open-chat thread replies. This mapping is observed behavior, not a documented contract.
  • thread_id — (optional) raw chat-log thread id as an exact decimal string, omitted when absent or zero. For open-chat thread replies it has been observed to equal the parent message's log_id.
  • prev_id — (optional) raw chat-log previous log id as an exact decimal string, omitted when absent or zero.

Typing Indicator

message typing sends a single LOCO ACTION (typing) pulse. Recipients see the animated "..." for about 5 seconds; no message is created.

{ "success": true, "status_code": 0, "chat_id": "9876543210" }

Re-run it every few seconds to keep the indicator up while a long reply is being prepared. Each CLI call logs in on its own connection, so for frequent pulses use the SDK's sendTyping on a long-lived client instead. Open chats need --link-id <li>, the same value mark-read takes. A non-zero server status is printed as {"error": "ACTION failed: statusCode=<n>"} with a non-zero exit code.

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

message list --from keeps only the latest N messages after the cursor, so when more than N have arrived the ones in between are not returned. Use message page when you need every message after a known point.

Paging History Without Gaps

message page wraps the SDK's getMessagePage. It returns one page of messages strictly after --from <log-id>, oldest first. When more than -n messages are available it returns the oldest -n and sets complete: false; continue with --from <next_cursor> until complete is true.

FlagDefaultDescription
--from <log-id>start of available historyExclusive cursor. Only messages with a larger log_id are returned. An empty or non-numeric value fails before login.
-n, --count <number>100Page size, an integer from 1 to 100. Other values fail before login.
--account <id>current accountUse a specific KakaoTalk account.
--prettyoffPretty print JSON output.
{
  "messages": [
    {
      "log_id": "123456790",
      "type": 1,
      "author_id": 1234567890,
      "author_name": "Alice",
      "message": "Hello",
      "attachment": null,
      "sent_at": 1700000000000
    }
  ],
  "next_cursor": "123456790",
  "complete": false
}

messages uses the same fields as message list. next_cursor is the log_id of the last message in the page, or null when the page is empty. Reads go through MCHATLOGS with a read-only CHATINFO + SYNCMSG fallback and never call CHATONROOM, so paging does not change read state. Each CLI call logs in once; for long catch-ups use the default page size or the SDK on a long-lived client.

CURSOR=123456789
while :; do
  PAGE=$(agent-kakaotalk message page 9876543210 --from "$CURSOR") || exit 1
  echo "$PAGE" | jq -c '.messages[]'
  [ "$(echo "$PAGE" | jq -r '.complete')" = "true" ] && break
  NEXT=$(echo "$PAGE" | jq -r '.next_cursor // empty')
  [ -z "$NEXT" ] && { echo "message page: complete=false but no next_cursor; history may be incomplete" >&2; exit 1; }
  CURSOR=$NEXT
done

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

OptionDescription
--accountUse a specific KakaoTalk account (default: current account)
--prettyHuman-readable output instead of JSON

Storage

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

Limitations

  • No file download

  • No chat room creation

  • No friend list management

  • No reactions or emoji

  • No message editing or deletion

  • No open chat browsing or joining. Moderation is limited to kicking members and managing the kick list (member kick, member kick-list, member unkick)

  • No search across chats

  • Read-only for stickers: sticker / animated-sticker messages are exposed via the attachment field on each message, but sending stickers is not supported

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

Error Output

Errors raised while a command runs go through the shared error handler: they are printed to stderr as JSON and the process exits non-zero. A few failures bypass it, so check the exit code first and read both streams: a missing or unknown account prints {"error": "..."} to stdout; missing credentials (checked before any non-auth command) are printed to stderr as plain text; both of these exit 1. auth subcommands report failures (and non-interactive auth login next-action steps) as result JSON on stdout; member kick without --force, and success: false results from message upload, message mark-read, message typing, member kick, member kick-list, and member unkick print their JSON to stdout and exit 1. message send also prints its result JSON to stdout but currently exits 0 even when it reports success: false, so check the success field of its output. When the error carries a machine-readable code, it is included as code; otherwise only error is present. Branch on code instead of matching the message text.

{
  "error": "Reply target log-id 1234567890 not found in the latest 100 messages of chat 9876543210",
  "code": "reply_target_not_found"
}

Common codes: delivery_unknown (a send may or may not have been delivered; check history before resending), invalid_access_token and login_rejected (run auth login), invalid_mention, reply_target_not_found, invalid_chat_id, invalid_link_id.

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

On this page