larksuite / larksuite/cli

[Feature Request] Query my own unread IM messages (count + list)

Open
#2,316 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

domain/mail enhancement
Dominant language
Go
Stars
17.3k
Forks
1.4k
Avg merge
2d 4h
Merged PRs (30d)
105

Description

Summary

lark-cli currently has no way to query the current user's unread IM messages — neither a global unread count nor a list of unread messages across chats. This is a common need for human users and AI agents that want to pick up "what's waiting for me" without opening the desktop/mobile client.

What I tried (CLI v1.0.85)

  • lark-cli im +chat-list — lists chats I'm a member of, but returns no unread_count and offers no unread filter.
  • lark-cli im +messages-search --is-at-me — only finds messages that @ me; cannot tell read/unread status.
  • lark-cli im +chat-messages-list — lists messages per chat (via /open-apis/im/v1/messages), but has no unread filter.

None of these expose read/unread state.

Proposed capability

  1. Unread count per chat: include unread_count in +chat-list output, and/or add an --only-unread filter to +chat-list.
  2. List my unread messages: e.g. lark-cli im +unread-list — returns messages across chats where is_read=false, with time range, per-chat grouping, and pagination.
  3. Underlying OpenAPI: the IM (im.v1) domain does not appear to expose a "list my unread messages" or "unread count" endpoint. This likely needs an OpenAPI addition (similar to the mail domain's is_unread filter) so the CLI can surface it.

Use cases

  • AI agent daily routine: "summarize what's unread in my Lark chats".
  • Triage: list unread messages across chats sorted by recency, without opening the client.
  • Programmatic detection of new/unread messages (e.g. for custom notification/bot flows).

Consistency reference

The mail domain already supports an unread filter (lark-cli mail +triage --is-unread / --filter is_unread=true). An analogous IM capability would be consistent with the existing CLI design.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the existing im +chat-list, im +messages-search, and im +chat-messages-list commands, then compare them with mail +triage --is-unread and the available im.v1 OpenAPI operations. Done means the required unread count/list capability, API availability, command shape, filtering, grouping, and pagination have been decided and can be implemented without unresolved design questions.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
api, cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.