Lark Event スキル

Lark Events

Prerequisite: Read `../lark-shared/SKILL.md` first for authentication, --as user/bot switching, Permission denied handling, and safety rules.

Core commands

Common flags

Examples

# Default: stream every event for the key (no filter, no projection)
lark-cli event consume im.message.receive_v1 --as bot

# List every EventKey of one domain (the authoritative, always-current catalog)
lark-cli event list --domain vc --json

# Grab one sample event to inspect payload shape
lark-cli event consume im.message.receive_v1 --max-events 1 --timeout 30s --as bot

# Run for 10 minutes then auto-exit
lark-cli event consume im.message.receive_v1 --timeout 10m --as bot

# Consume multiple EventKeys concurrently (one shape per process, no dispatcher)
lark-cli event consume im.message.receive_v1          --as bot > receive.ndjson &
lark-cli event consume im.message.reaction.created_v1 --as bot > reaction.ndjson &
wait

Call flow

1. lark-cli event list --json → pick a legal key. --domain <d> narrows to one domain; the domains are application, approval, board, card, im, minutes, task, vc. An unknown domain fails with the valid set listed in the hint.
2. lark-cli event schema <key> --json → read resolved_output_schema + jq_root_path to determine field paths
3. lark-cli event consume <key> [--jq '<expr>'] → consume

Subprocess contract

Ready marker

event consume's stderr emits a fixed line [event] ready event_key=<key>. Parent processes should block on stderr until this line appears, then start reading stdout. Do not fall back to sleep.

stdin EOF = graceful exit

event consume treats stdin close as a shutdown signal (wired for AI subprocess callers). Bounded runs are exempt: when --max-events or --timeout is set (> 0), stdin EOF is ignored and the run exits only via its own bound, timeout, or SIGTERM. For unbounded runs, < /dev/null / nohup / systemd's default StandardInput=null will cause an immediate graceful exit (stderr reason: signal). To keep an unbounded run alive:

• Feed stdin a source that never EOFs: < <(tail -f /dev/null)
• Or run bounded: --max-events N / --timeout D

Exit codes & reason

On exit, the last stderr line is [event] exited — received N event(s) in Xs (reason: ...).

Startup and runtime failures emit a structured JSON envelope on stderr: {"ok":false,"error":{"type","subtype","param","message","hint",...}} (the envelope may also carry top-level identity / _notice siblings). Parse error.type / error.subtype to branch (e.g. missing_scope carries a missing_scopes list), error.param to find the offending flag, and error.hint for the recovery action — do not regex-match message text.

Orchestrators should treat reason: limit/timeout/signal (all exit 0) as "business completion" and non-zero as "failure".

Never kill -9

Avoid kill -9 on consume processes for EventKeys whose PreConsume registers a server-side subscription and unsubscribes on exit (minutes, vc, board keys): kill -9 skips the OAPI unsubscribe and leaks the server-side subscription (symptoms: "subscription already exists" on restart, duplicate event delivery). Keys whose subscription is a durable relation with no cleanup (task, approval keys) do not leak this way, but SIGTERM or closing stdin remains the right shutdown for every key.

One consume, one EventKey (multi-key = multi-shell)

The command takes exactly one positional argument; k1,k2 and wildcards are unsupported. Listening to N keys means N subprocesses — this is intentional:

• One shape per process stdout; no dispatcher logic required in the AI
• Fault isolation (one key failing doesn't affect others)
• Independent --as / --jq / --max-events / --timeout per key

All N consumers share a single bus daemon (UDS local IPC), so the overhead is small

Writing jq via schema

event schema <key> --json is the source of truth for writing --jq. Four things to look at:

(1) Where fields start — see jq_root_path

• Value "." → fields are at the top level, write .chat_id
• Value ".event" → fields are inside a V2 envelope, write .event.chat_id

(2) Field list and types — see resolved_output_schema.properties.<name>

Each field carries type / description, and some also have format. Snippet (from event schema im.message.receive_v1 --json):

{
  "chat_id":     {"type":"string", "format":"chat_id",      "description":"Chat ID, prefixed with oc_"},
  "sender_id":   {"type":"string", "format":"open_id",      "description":"Sender open_id, prefixed with ou_"},
  "create_time": {"type":"string", "format":"timestamp_ms", "description":"Send time as ms-epoch string"}
}

(3) Field semantics — see the format tag

Lark-defined semantic tags (not JSON Schema's standard format). Common values: open_id / chat_id / message_id / timestamp_ms / email. Purpose: distinguish "same string type, different meanings" fields so you can reverse-lookup via API or convert formats.

(4) Decoded state — read the field's description

event consume runs Process hooks that may pre-decode some payload fields (flattening V2 envelopes, rendering .content to plain text, etc.) — behavior differs from raw OAPI. Always read the field's description before writing jq, especially for generic field names like content / data / body / payload.

Why it matters: blindly applying fromjson to an already-decoded text field makes jq error on every event and silently drop it — the consumer looks alive but emits nothing, with only a single WARN line buried on stderr. (This is the general behavior: any jq runtime error skips the event with a one-line WARN; the loop does not abort.)

Don't shortcut the schema: when projecting event schema --json with jq, do not strip .description from properties — that's the field that tells you whether a field is already decoded. Dump the full property objects, not just keys.

Aside: --param's valid parameters also live in the schema — the params section lists name / type / required / enum / default / description; section missing = this key accepts no --param.

Topic index

Lark Application Events

This page covers Application-domain EventKeys supported by lark-cli event.

application.bot.menu_v6

Triggered when a user clicks a custom bot menu item whose response action is configured as a push event.

Listen as the bot identity:

lark-cli event consume application.bot.menu_v6 --as bot

Filter a specific menu event key:

lark-cli event consume application.bot.menu_v6 --as bot --jq 'select(.event_key == "start_eval")'

Output is flattened at the top level:

This EventKey has no --param; use --jq to filter by event_key or operator fields.

Approval Events

Prerequisite: Read `../SKILL.md` first for the event consume essentials (commands, subprocess contract, jq usage).

Key catalog (2)

Both keys use a Custom schema. The raw Lark schema 2.0 envelope is flattened: event metadata is exposed as type, event_id, and timestamp, while approval business fields are exposed at the top level.

Both keys carry a PreConsume hook that subscribes the current authorized user through the Approval subscription APIs before listening. The consumer intentionally does not unsubscribe on exit; the server-side Approval subscription relation remains until it is canceled outside event consume. These keys require --as user.

Listener and subscription selection

At the raw CLI level, each event consume process accepts exactly one EventKey. approval.instance.status_changed_v4 and approval.task.status_changed_v4 have different output shapes, so listening to both still means two processes.

For Approval only, subscription_type is an optional setup param used by PreConsume to register server-side Approval subscription relations before the local listener starts. It is not an output field, a local event filter, or a local subscription identity. The pushed event does not say which subscription relation caused delivery, and one business event can match both relations; deduplicate with event_id when needed.

subscription_type may be omitted, a single value, a comma-separated list, or a JSON string array:

# Omitted: register both INVOLVED_APPROVAL and MANAGED_APPROVAL for this EventKey
lark-cli event consume approval.instance.status_changed_v4 --as user

# Single relation
lark-cli event consume approval.instance.status_changed_v4 \
  -p subscription_type=INVOLVED_APPROVAL \
  --as user

# Explicit multi-relation registration for one local consumer
lark-cli event consume approval.task.status_changed_v4 \
  -p subscription_type=INVOLVED_APPROVAL,MANAGED_APPROVAL \
  --as user

# JSON array form; quote it for the shell
lark-cli event consume approval.task.status_changed_v4 \
  -p 'subscription_type=["INVOLVED_APPROVAL","MANAGED_APPROVAL"]' \
  --as user

User-intent inference:

If the user's wording omits the relation and broad listening is acceptable, omit subscription_type. Ask only when registering both relations would be materially harmful.

Scopes & auth

Subscription behavior

Startup calls the endpoint for the selected EventKey:

POST /open-apis/approval/v4/instances/subscription
POST /open-apis/approval/v4/tasks/subscription

For each resolved subscription_type, PreConsume sends one request body:

{"subscription_type":"INVOLVED_APPROVAL"}

If subscription_type is omitted, PreConsume sends two registration requests for that EventKey: one with INVOLVED_APPROVAL, then one with MANAGED_APPROVAL. If listening to both instance and task events, run two consumers; each consumer may omit subscription_type to register both relations for its own EventKey.

Do not start two consumers for the same Approval EventKey merely to split INVOLVED_APPROVAL and MANAGED_APPROVAL. The server push and flattened output are keyed by EventKey and cannot be distinguished by subscription relation.

Shutdown behavior:

event consume does not call the Approval unsubscribe APIs when it exits. This applies to graceful exit, Ctrl+C / SIGTERM, stdin EOF, --timeout, and --max-events.

To stop future delivery for a user, cancel the Approval subscription relation outside this consumer. The unsubscribe APIs are separate operations and are not called by event consume.

Output fields

Common fields:

Instance event fields:

Task event fields:

Examples

# Stream approval instance updates broadly; registers both involved and managed relations
lark-cli event consume approval.instance.status_changed_v4 \
  --as user

# Stream approval instance updates only for approvals involving the current user
lark-cli event consume approval.instance.status_changed_v4 \
  -p subscription_type=INVOLVED_APPROVAL \
  --as user

# Stream approval task updates for definitions managed by the current user
lark-cli event consume approval.task.status_changed_v4 \
  -p subscription_type=MANAGED_APPROVAL \
  --as user

# Broad approval status listening:
# run both EventKeys as separate processes; omit subscription_type so each registers both relations.
lark-cli event consume approval.instance.status_changed_v4 \
  --as user > approval-instance.ndjson &
lark-cli event consume approval.task.status_changed_v4 \
  --as user > approval-task.ndjson &
wait

# Listen to both involved and managed task subscriptions with one local consumer.
lark-cli event consume approval.task.status_changed_v4 \
  -p subscription_type=INVOLVED_APPROVAL,MANAGED_APPROVAL \
  --as user > approval-task.ndjson

# Project a compact approval-task record
lark-cli event consume approval.task.status_changed_v4 \
  -p subscription_type=INVOLVED_APPROVAL \
  --as user \
  --jq '{event_id, task_id, status, at: .operate_time}'

IM Events

Prerequisite: Read `../SKILL.md` first for the event consume essentials (commands, subprocess contract, jq usage).

Heads-up for AI agents: this key's .content is NOT the raw OAPI payload shape your training data may suggest. lark-cli runs a Process hook (convertlib) that flattens the V2 envelope and pre-renders .content to human-readable text for text / post / image / file / audio / etc. Only interactive (cards) keeps the raw JSON string. Don't blindly fromjson.

Key catalog (12)

Shape: All 12 events have a V2-enveloped raw payload. lark-cli flattens two of them — im.message.receive_v1 and card.action.trigger — so their consumed output is flat (fields at .xxx). The other 10 are passed through as-is; use .event.xxx to access their fields.

Gotchas (im.message.receive_v1)

sender_id is open_id only: the event payload carries no display name. Call the contact API separately if you need the sender's name.

.content shape depends on message_type (this key uses a flat Custom schema; see `events/im/message_receive.go`):

Do not blindly fromjson — for non-interactive messages it fails with jq: fromjson cannot be applied to "hello" because .content isn't JSON-encoded.

# text: .content is plain text — no fromjson needed
lark-cli event consume im.message.receive_v1 --as bot \
  --jq 'select(.message_type=="text") | .content'

# interactive: .content is a JSON string — fromjson to parse
lark-cli event consume im.message.receive_v1 --as bot \
  --jq 'select(.message_type=="interactive") | .content | fromjson'

On-demand filter recipes

Default = no --jq. Run lark-cli event consume im.message.receive_v1 --as bot to see every message. The recipes below are only for cases where the user has asked to narrow the stream.

1. Filter by chat type (p2p vs group)

chat_type is an enum with values p2p / group.

# p2p only (direct messages)
lark-cli event consume im.message.receive_v1 --as bot \
  --jq 'select(.chat_type=="p2p") | {from: .sender_id, msg: .content}'

# group only
lark-cli event consume im.message.receive_v1 --as bot \
  --jq 'select(.chat_type=="group") | {chat: .chat_id, from: .sender_id, msg: .content}'

2. Filter by message type

# text only — content is plain human-readable text
lark-cli event consume im.message.receive_v1 --as bot \
  --jq 'select(.message_type=="text") | .content'

# interactive (card) only — parse the card body
lark-cli event consume im.message.receive_v1 --as bot \
  --jq 'select(.message_type=="interactive") | .content | fromjson'

3. Filter by sender (only one user's messages)

# example: only messages from the given open_id
lark-cli event consume im.message.receive_v1 --as bot\
  --jq 'select(.sender_id=="ou_xxxxxxxxxxxxxxxxxxxxxxxxxx") | {msg_id: .message_id, text: .content}'

Get your own open_id via lark-cli contact +get-user --as user; other users' via lark-cli contact +search-user.

Minutes Events

Prerequisite: Read `../SKILL.md` first for the event consume essentials (commands, subprocess contract, jq usage).

Key catalog (1)

This key uses a Custom schema (flat output at .xxx) and carries a PreConsume hook that auto-subscribes / unsubscribes via OAPI on first / last consumer.

Scopes & auth

Requires --as user.

minutes.minute.generated_v1

Output fields

Enrichment & degradation

The Process hook calls GET /open-apis/minutes/v1/minutes/{minute_token} to enrich title. If the detail API fails, this field is left empty — the base fields (type, event_id, timestamp, minute_token, minute_source) are always present.

minute_source is populated from the event payload directly (not the detail API), so it survives enrichment failures. Note: minute_source is only present when the minute originates from a meeting; for other sources (e.g. recording, local upload) this field is absent.

Example

lark-cli event consume minutes.minute.generated_v1 --as user

# Project title and token only (skip events where enrichment failed)
lark-cli event consume minutes.minute.generated_v1 --as user \
  --jq 'select(.title != "") | {minute_token, title}'

# Filter by source type
lark-cli event consume minutes.minute.generated_v1 --as user \
  --jq 'select(.minute_source.source_type == "meeting") | {minute_token, title}'

Task Events

Prerequisite: Read `../SKILL.md` first for the event consume essentials (commands, subprocess contract, jq usage).

Key catalog (1)

This key uses a Native schema (V2 envelope; output rooted at .event) and carries a PreConsume hook that calls the Task event subscription API before listening.

Scopes & auth

Supports --as user or --as bot.

• --as user: receive task updates visible to the current user through authorship, assignment, following, or other access.
• --as bot: receive task updates for tasks the application is responsible for.

task.task.update_user_access_v2

Subscription behavior

On startup, event consume calls:

POST /open-apis/task/v2/task_v2/task_subscription?user_id_type=open_id

The Task subscription API has no matching unsubscribe endpoint in the current CLI metadata, so graceful exit has no cleanup call for this EventKey. Re-running the consumer repeats the subscribe call for the selected identity.

This EventKey is single-consumer per local bus subscription: start one event consume task.task.update_user_access_v2 process for a given app/profile/identity at a time.

Output fields (V2 envelope; root path .event)

Commit types:

task_assignees_update
task_completed_update
task_create
task_deleted
task_desc_update
task_followers_update
task_reminders_update
task_start_due_update
task_summary_update

Example

# Stream task update events for the current user
lark-cli event consume task.task.update_user_access_v2 --as user

# Sample one event for payload inspection
lark-cli event consume task.task.update_user_access_v2 \
  --as user --max-events 1 --timeout 2m

# Project to a compact task-update record
lark-cli event consume task.task.update_user_access_v2 \
  --as user \
  --jq '{event_id: .header.event_id, task_guid: .event.task_guid, event_types: .event.event_types, timestamp: .header.create_time}'

# Consume as the app identity
lark-cli event consume task.task.update_user_access_v2 --as bot

VC Events

Prerequisite: Read `../SKILL.md` first for the event consume essentials (commands, subprocess contract, jq usage).

Key catalog (7)

All seven keys use a Custom schema (flat output) and carry a PreConsume hook that auto-subscribes / unsubscribes via OAPI on first / last consumer. All require --as user.

Scopes & auth

Meeting participant events

Covered keys:

• vc.meeting.participant_meeting_started_v1
• vc.meeting.participant_meeting_joined_v1
• vc.meeting.participant_meeting_ended_v1

Output fields

Gotchas

• start_time / end_time are not the raw unix-seconds from OAPI — the Process hook converts them to local-timezone RFC3339. If the raw value is empty or non-numeric, the field is left empty. end_time is emitted only for vc.meeting.participant_meeting_ended_v1.
• No detail API call is made; all fields come from the event payload itself.

Example

lark-cli event consume vc.meeting.participant_meeting_started_v1 --as user
lark-cli event consume vc.meeting.participant_meeting_joined_v1 --as user
lark-cli event consume vc.meeting.participant_meeting_ended_v1 --as user

# Project meeting topic and end time only
lark-cli event consume vc.meeting.participant_meeting_ended_v1 --as user \
  --jq '{meeting: .meeting_id, topic: .topic, ended: .end_time}'

vc.note.generated_v1

Fires when a note is generated — not just from meetings, but also from realtime recordings and local file uploads.

Output fields

Source type semantics

note_source (and its sub-fields) are only populated when source_type is meeting. For other sources the field is absent.

Example

lark-cli event consume vc.note.generated_v1 --as user

# Only notes with enriched tokens, skip incomplete ones
lark-cli event consume vc.note.generated_v1 --as user \
  --jq 'select(.note_token != "") | {note_id, note_token, verbatim_token}'

# Filter to meeting-sourced notes only
lark-cli event consume vc.note.generated_v1 --as user \
  --jq 'select(.note_source.source_type == "meeting") | {note_id, meeting_id: .note_source.source_entity_id}'

Whiteboard Events

Prerequisite: Read `../SKILL.md` first for the event consume essentials (commands, subprocess contract, jq usage).

Key catalog (1)

This key uses a Native schema (V2 envelope; output rooted at .event) and carries a PreConsume hook that auto-subscribes / unsubscribes via OAPI on first / last consumer.

Scopes & auth

Supports --as user or --as bot. The caller must have manage access to the target whiteboard, otherwise the subscribe OAPI returns 403 and event consume exits with an auth error before listening.

board.whiteboard.updated_v1

Per-whiteboard subscription

Unlike global event keys (e.g. minutes / im), this key subscribes per whiteboard: event consume calls POST /open-apis/board/v1/whiteboards/{whiteboard_id}/subscribe on startup with the whiteboard_id you pass via -p. Required parameter: -p whiteboard_id=<whiteboard_token>. Missing this param fails param validation up-front with required param "whiteboard_id" missing for EventKey board.whiteboard.updated_v1 before any subscription happens.

Whiteboard token can be obtained via the docs OAPI list document blocks: the block whose block_type=43 is a whiteboard, and block.token is the whiteboard token.

Output fields (V2 envelope; root path .event)

operator_ids is an array — multi-user collaborative editing within one tick collapses into a single event with multiple entries.

Subscription lifecycle

Example

# Stream every edit on whiteboard <token> until Ctrl+C
lark-cli event consume board.whiteboard.updated_v1 \
    -p whiteboard_id=<whiteboard_token> \
    --as user

# Sample one event for payload inspection
lark-cli event consume board.whiteboard.updated_v1 \
    -p whiteboard_id=<whiteboard_token> \
    --as user --max-events 1 --timeout 2m

# Project to "edit summary": who edited which whiteboard
lark-cli event consume board.whiteboard.updated_v1 \
    -p whiteboard_id=<whiteboard_token> \
    --as user \
    --jq '{whiteboard: .event.whiteboard_id, editors: (.event.operator_ids | map(.open_id))}'