Lark Event

event (v1)

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、权限处理和安全规则。

Shortcuts（推荐优先使用）

Shortcut 是对常用操作的高级封装（lark-cli event +<verb> [flags]）。有 Shortcut 的操作优先使用。

event +subscribe

Prerequisite: Read `../lark-shared/SKILL.md` first to understand authentication, global parameters, and safety rules.

Subscribe to Lark events via WebSocket long connection, outputting NDJSON to stdout. Supports compact (agent-friendly) format, regex-based routing, and file output.

Identity / Risk:

• Identity: bot-only — uses App ID + App Secret to establish the WebSocket connection. No user login needed (lark-cli config init is sufficient).
• Risk: read — this is a read-only subscription command. It receives events but does not modify any resources.

Platform-side configuration (must be done in the Lark Open Platform console): 1. Events & Callbacks → Subscription method → Select "Use long connection to receive events" 2. Add the events you need (e.g. im.message.receive_v1) 3. Enable the corresponding permissions (e.g. im:message:receive_as_bot)

Commands

# Subscribe to all registered events (catch-all mode, 24 common event types)
lark-cli event +subscribe

# Subscribe to specific event types only
lark-cli event +subscribe --event-types im.message.receive_v1

# Subscribe to multiple event types
lark-cli event +subscribe --event-types im.message.receive_v1,calendar.calendar.event.changed_v4

# Client-side regex filter (applied after SDK receives events)
lark-cli event +subscribe --filter "^im\."

# Agent-friendly format (parse content, strip noise fields)
lark-cli event +subscribe --event-types im.message.receive_v1 --compact --quiet

# Pretty-print JSON output
lark-cli event +subscribe --json

# Write each event to a file
lark-cli event +subscribe --output-dir ./events

# Route events to different directories by regex
lark-cli event +subscribe \
  --route '^im\.message=dir:./im/' \
  --route '^contact\.=dir:./contacts/'

# Route IM events to files, other events to stdout
lark-cli event +subscribe --route '^im\.=dir:./im-events/'

# Preview configuration without connecting
lark-cli event +subscribe --dry-run

Parameters

Output Formats

Default (raw NDJSON)

One event per line, all fields included:

{"schema":"2.0","header":{"event_id":"xxx","event_type":"im.message.receive_v1","create_time":"1773491924409","app_id":"cli_xxx"},"event":{"message":{"chat_id":"oc_xxx","content":"{\"text\":\"Hello\"}","message_id":"om_xxx","message_type":"text"},"sender":{"sender_id":{"open_id":"ou_xxx"},"sender_type":"user"}}}

--compact (agent-friendly)

Flattened key-value output with semantic fields. The exact fields depend on the event type and its processor.

IM message events (im.message.receive_v1) have deep compact processing:

{"type":"im.message.receive_v1","id":"om_xxx","message_id":"om_xxx","chat_id":"oc_xxx","chat_type":"p2p","message_type":"text","content":"Hello","sender_id":"ou_xxx","create_time":"1773491924409","timestamp":"1773491924409"}

• event.message.content (double-encoded JSON like "{\"text\":\"Hello\"}") is parsed and converted to human-readable text via convertlib → output as content
• event.sender.sender_id.open_id → flattened to sender_id
• schema, token, tenant_key, app_id stripped
• Supports all message types: text, post, image, file, card, etc.

Other IM events (reactions, chat member changes, chat updates) also have specialized compact processors with relevant semantic fields.

Non-IM events (contact, calendar, approval, task, drive, application) use the generic compact processor:

• Parses the event payload as a flat map
• Injects type (event_type), event_id, and timestamp from the event header
• All original event fields are preserved as-is

Agent pipelines should always use `--compact --quiet`.

Catch-all Event Types

The following 24 event types are registered in catch-all mode (when --event-types is omitted):

IM

Contact

Calendar

Approval

Application

Task

Drive

See the full list at Lark Event List.

Agent Pipeline Examples

Listen for messages and reply with Claude

lark-cli event +subscribe \
  --event-types im.message.receive_v1 --compact --quiet \
  | while IFS= read -r line; do
      content=$(echo "$line" | jq -r '.content // empty')
      message_id=$(echo "$line" | jq -r '.message_id // empty')
      [[ -z "$content" ]] && continue

      # Generate reply with Claude
      answer=$(claude -p "Reply concisely: $content" < /dev/null 2>/dev/null)

      # Reply as bot
      reply_data=$(jq -n --arg t "$answer" '{msg_type:"text",content:({text:$t}|tojson)}')
      lark-cli api POST "/open-apis/im/v1/messages/$message_id/reply" \
        --data "$reply_data" --as bot --format data
    done

Listen for messages and log to a Lark document

lark-cli event +subscribe \
  --event-types im.message.receive_v1 --compact --quiet \
  | while IFS= read -r line; do
      content=$(echo "$line" | jq -r '.content // empty')
      [[ -z "$content" ]] && continue

      lark-cli docs +update --doc "DOC_URL" --mode append --markdown "- $content"
    done

Notes

• Events must be configured in the Open Platform console — the CLI cannot dynamically subscribe to event types
• --event-types controls which types the SDK dispatcher registers for. Unregistered types are silently dropped even if the server sends them. Omitting this flag registers 24 common types (catch-all)
• --filter is a pure client-side regex filter applied after the SDK delivers events. It does not affect which events are registered
• --force bypasses the single-instance lock per app. Without it, only one +subscribe process is allowed per app to prevent the server from splitting events across connections
• WebSocket auto-reconnects on disconnection (SDK built-in)
• Ctrl+C gracefully shuts down and prints the total event count
• Reply to messages with lark-cli api ... --as bot — no user login needed

References

• lark-im — Messaging commands
• lark-doc-update — Update Lark documents
• lark-shared — Authentication and global parameters