Messages

Messages Skill

Retrieve chat message history, send messages, manage reactions, and search for chats/groups via the lark CLI.

🤖 Capabilities and Use Cases

• Send markdown-lite messages with links and mentions
• Send images with --image and {{image}} placement
• Message recall/delete for cleanup
• Add/list/remove emoji reactions
• Browse emoji catalog reference
• Read chat history (chat or thread)
• Download message resources (images/files/audio/video)
• Find chats by name or member
• Use clear, flag-based CLI with consistent JSON output

🚀 Quick Reference

Send message:

lark msg send --to user@example.com --text "Hello!"

Read messages:

lark msg history --chat-id oc_12345 --limit 10

Find chats:

lark chat search "project team"

React / list / remove reaction:

lark msg react --message-id om_123456789abcdef --reaction SMILE
lark msg react list --message-id om_123456789abcdef
lark msg react remove --message-id om_123456789abcdef --reaction-id ZCaCIjUBVVWSrm5L-3ZTw...

Download resource:

lark msg resource --message-id om_xxx --file-key img_v3_xxx --type image --output ./image.png

Running Commands

Ensure lark is in your PATH, or use the full path to the binary. Set the config directory if not using the default:

lark msg <command>
lark chat <command>
# Or with explicit config:
LARK_CONFIG_DIR=/path/to/.lark lark msg <command>

Commands Reference

Search for Chats/Groups

lark chat search "project" --limit 10

Available flags:

• --limit: Maximum number of chats to retrieve (0 = no limit)

Output fields include:

• chats[] with chat_id, name, description, owner_id, external, chat_status
• count, query

Send Messages

Send messages to users or group chats as the bot.

lark msg send --to ou_xxxx --text "Hello!"

Available flags:

• --to (required): Recipient identifier (user ID, open_id, email, or chat_id)
• --to-type: Explicitly specify ID type (open_id, user_id, email, chat_id) - auto-detected if omitted
• --text: Message text content (markdown-lite). Use {{image}} to place images.
• --image: Image file path (repeatable)

Output:

{
  "success": true,
  "message_id": "om_dc13264520392913993dd051dba21dcf",
  "chat_id": "oc_xxxxx",
  "create_time": "2026-01-14T10:30:00+08:00"
}

Get Chat History

lark msg history --chat-id oc_xxxxx --limit 50 --sort desc

Available flags:

• --chat-id (required): Chat ID or thread ID
• --type: Container type - chat (default) or thread
• --start: Start time (Unix timestamp or ISO 8601)
• --end: End time (Unix timestamp or ISO 8601)
• --sort: Sort order - asc (default) or desc
• --limit: Maximum number of messages (0 = no limit)

Output fields include:

• messages[] with message_id, msg_type, content, sender, create_time, mentions, is_reply, thread_id, deleted
• count, chat_id

React to Message

Add a reaction to a message as the bot.

lark msg react --message-id om_dc13264520392913993dd051dba21dcf --reaction SMILE

Available flags:

• --message-id (required): Message ID to react to
• --reaction (required): Reaction ID or emoji name
• --type: Reaction type (default: emoji)

Output:

{
  "success": true,
  "message_id": "om_dc13264520392913993dd051dba21dcf",
  "reaction_type": "emoji",
  "reaction_id": "ZCaCIjUBVVWSrm5L-3ZTw...",
  "emoji_type": "SMILE"
}

Notes:

• Reactions are added as the bot/app. The bot must be in the chat to react.
• Emoji types must match the Lark emoji catalog (e.g., SMILE, LAUGH).

Emoji Catalog Reference

lark msg react emojis

Use this command to list the supported emoji types for reactions.

Custom Emojis: Organization-specific custom emojis can be configured in .lark/config.yaml:

custom_emojis:
  "7405453485858095136": "ez-pepe"

Custom emoji IDs will appear in the custom_emojis field of the output.

List Message Reactions

lark msg react list --message-id om_dc13264520392913993dd051dba21dcf --reaction SMILE --limit 50

Available flags:

• --message-id (required): Message ID to list reactions for
• --reaction: Emoji type filter (e.g., SMILE)
• --limit: Maximum number of reactions to retrieve (0 = no limit)

Output fields include:

• message_id, reactions[], count

Remove Message Reaction

lark msg react remove --message-id om_dc13264520392913993dd051dba21dcf --reaction-id ZCaCIjUBVVWSrm5L-3ZTw...

Available flags:

• --message-id (required): Message ID to remove reaction from
• --reaction-id (required): Reaction ID to remove

Output fields include:

• success, message_id, reaction_type, reaction_id, emoji_type

Recall Messages

Recall/delete previously sent messages from chats.

lark msg recall om_dc13264520392913993dd051dba21dcf

Output fields include:

• success, message_id

Downloading Resource Files

Download images, files, audio, and video from messages using msg resource:

lark msg resource --message-id om_xxx --file-key img_v3_xxx --type image --output ./image.png
lark msg resource --message-id om_xxx --file-key file_v2_xxx --type file --output ./document.pdf

Available flags:

• --message-id (required): Message ID containing the resource
• --file-key (required): Resource key from message content (image_key or file_key)
• --type (required): image for images, file for files/audio/video
• --output (required): Output file path

Output fields include:

• success, message_id, file_key, output_path, content_type, bytes_written

Limitations:

• Maximum file size: 100MB
• Emoji resources cannot be downloaded
• Resources from card, merged, or forwarded messages are not supported
• The message_id and file_key must match

Tips

• Use \n for line breaks and \t for indentation in --text
• Use @{ou_xxx} to mention users in group chats
• Use {{image}} in text to place images in order
• Chat IDs start with oc_; thread IDs start with thread_ or omt_
• Use lark msg react list to discover reaction_id for removal
• The CLI auto-detects recipient type; override with --to-type if needed

Message Types

• text - Plain text message
• post - Rich text post
• image - Image
• file - File attachment
• audio - Audio message
• media - Video/media
• sticker - Sticker/emoji
• interactive - Interactive card
• share_chat - Shared chat
• share_user - Shared user contact

Reading Thread Replies

If a message has a thread_id, it is part of a thread (or is the root). To fetch replies:

lark msg history --chat-id oc_xxxxx --limit 10 --sort desc
lark msg history --chat-id omt_1a3b99f9d2cfd982 --type thread

Thread messages will have is_reply: true for replies (root message has is_reply: false).

Output Format

All commands output JSON.

Error Handling

Errors return JSON:

{
  "error": true,
  "code": "ERROR_CODE",
  "message": "Description"
}

Common error codes:

• AUTH_ERROR - Need to run lark auth login
• SCOPE_ERROR - Missing messages permissions
• VALIDATION_ERROR - Missing required fields (e.g., chat-id)
• API_ERROR - Lark API issue (e.g., bot not in group, missing permissions)

Required Permissions

This skill requires the messages scope group. If you see a SCOPE_ERROR, add permissions:

lark auth login --add --scopes messages

To check current permissions:

lark auth status

Additional requirements:

For reading messages:

• The bot must be in the group chat
• Group chat reads require the "Read all messages in associated group chat" permission
• Private chat reads require im:message:readonly

For sending messages:

• Requires im:message or im:message:send_as_bot
• The bot must be added to group chats before it can send messages to them

For reactions:

• List reactions requires im:message.reactions:read
• Add/remove reactions requires im:message.reactions:write_only

Notes

• Messages are sent as the bot/app
• Messages are sorted by creation time ascending by default
• Time filters do not work for thread container type
• Message IDs typically start with om_