im (v1)

im (v1)

- Chat: A group chat or P2P conversation, identified by chatid (ocxxx)

Category: design Source: larksuite/cli

im (v1) - Group and P2P Chat Management for Happycapy Skills

The im (v1) skill, identified as lark-im, provides robust capabilities for interacting with Lark's instant messaging (IM) platform. Designed for the Happycapy Skills platform, this skill enables developers and automation workflows to programmatically send and receive messages, manage group chats, handle chat assets, and interact with chat members. Its primary focus is on operations within both group chats and peer-to-peer (P2P) conversations, using chat IDs as unique identifiers.

What Is This?

The lark-im skill is a command-line interface (CLI) extension that integrates with the Lark platform's IM APIs, enabling comprehensive messaging and group management functionalities. At its core, the skill provides:

  • Sending and replying to messages (text, images, files, and more)
  • Searching and retrieving chat history
  • Managing group chat membership
  • Uploading and downloading images and files
  • Managing emoji reactions and message threads

The skill operates through the lark-cli tool, using chat IDs (in the format oc_xxx) to identify conversations and message IDs (om_xxx) to specify individual messages. It supports both user and bot identities, with access and permissions determined by the authentication context.

Why Use It?

Modern teams rely on instant messaging for rapid collaboration, file sharing, and decision-making. Automating IM operations can bring significant value:

  • Efficiency: Automate routine messaging, such as reminders, alerts, or status updates.
  • Integration: Connect chat workflows with other business systems, triggering messages based on external events.
  • Management: Programmatically manage group membership, share files, or moderate content at scale.
  • Consistency: Ensure standardized communication and responses, especially in large-scale or regulated environments.

The lark-im skill simplifies these tasks, providing a versatile interface for both operational automation and custom integration with Lark's rich IM ecosystem.

How to Use It

Prerequisites

Before using lark-im, ensure you have read the shared skill documentation (../lark-shared/SKILL.md) for authentication and permissions guidance. The skill requires the lark-cli binary and a proper authentication setup, either as a user or bot.

Basic Usage

The CLI syntax is as follows:

lark-cli im [command] [options]

Use lark-cli im --help for a list of available commands.

Sending a Text Message

To send a message to a group chat or P2P conversation, use:

lark-cli im send-message \
  --chat-id oc_abcdef1234567890 \
  --text "Hello, team - daily standup at 10:00 AM" \
  --as user

This sends a plain text message to the specified chat as the authorized user.

Uploading and Sending a File

To share a file in a chat:

lark-cli im upload-file \
  --chat-id oc_abcdef1234567890 \
  --file /path/to/document.pdf \
  --as bot

After uploading, you can reference the returned file key in subsequent messages.

Retrieving Chat History

To fetch recent messages from a chat:

lark-cli im list-messages \
  --chat-id oc_abcdef1234567890 \
  --limit 20 \
  --as user

This lists the last 20 messages in the specified chat.

Managing Group Membership

To add a user to a group:

lark-cli im add-member \
  --chat-id oc_abcdef1234567890 \
  --user-id ou_1234567890abcdef \
  --as bot

To remove a user:

lark-cli im remove-member \
  --chat-id oc_abcdef1234567890 \
  --user-id ou_1234567890abcdef \
  --as bot

Reacting to Messages

Add an emoji reaction to a message:

lark-cli im add-reaction \
  --message-id om_1234567890abcdef \
  --emoji ":+1:" \
  --as user

When to Use It

The lark-im skill is best suited for scenarios such as:

  • Automated notifications: Send alerts, reminders, or status updates directly to chat groups or individuals.
  • Integration with business workflows: Trigger IM actions from external systems (e.g., ticketing, monitoring, or CRM).
  • Content moderation and management: Automatically review, delete, or archive messages and files based on business rules.
  • Group administration: Onboard or offboard members, manage chat settings, and maintain group hygiene.
  • Programmatic file sharing: Distribute reports, documents, or multimedia content at scale.

Important Notes

Identity and Permissions

  • Using --as user leverages the end user's identity and their access token. All actions are subject to both the app's scopes and the user's permissions in the target chat.
  • Using --as bot operates under the app bot's identity, using the tenant access token. The bot must be a member of the chat and have appropriate permissions.

Resource Relationships

The skill organizes resources hierarchically:

Chat (oc_xxx)
├── Message (om_xxx)
│   ├── Thread (reply thread)
│   ├── Reaction (emoji)
│   └── Resource (image / file / video / audio)
└── Member (user / bot)

Understanding this structure is crucial when working with threads, reactions, and resource downloads.

Compliance and Rate Limits

Always consider Lark platform compliance requirements and API rate limits. Complex operations or bulk actions may require batching and error handling.

Authentication

Consult the shared skill documentation for details on how to securely handle authentication, especially when switching between user and bot contexts.

The im (v1) skill for Happycapy Skills delivers a powerful interface for automating and managing instant messaging workflows on Lark. By leveraging its features, teams and developers can streamline communication, integrate with existing business processes, and enhance operational efficiency within their organizations.