Skip to content

Pinvou/pinvou-agent / pinvou3-app/src-tauri/resources/common/bundle/lark-skills/lark-im

lark-im

Verified

【何时用:仅当用户明确指向飞书/Lark(发到飞书、飞书文档等)时使用;泛指做个文档或PPT或表格或方案默认走本地工具,不要误用飞书】飞书即时通讯:收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件、管理表情回复、发送应用内/短信/电话加急、发送和处理交互卡片(Interactive Card)与卡片按钮回调(card.action.trigger)。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索或创建群聊/话题群、管理标记数据、Feed 置顶与标签数据、处理卡片回调时使用。

FileKindSize
SKILL.mdskill md24.6 KB
references/card/card-2.0-schema.mdmarkdown6.0 KB
references/card/components/button.mdmarkdown2.8 KB
references/card/components/chart.mdmarkdown2.2 KB
references/card/components/checker.mdmarkdown1.9 KB
references/card/components/collapsible_panel.mdmarkdown1.8 KB
references/card/components/column_set.mdmarkdown2.5 KB
references/card/components/date_picker.mdmarkdown1.6 KB
references/card/components/div.mdmarkdown1.7 KB
references/card/components/form.mdmarkdown2.2 KB
references/card/components/header.mdmarkdown1.6 KB
references/card/components/hr.mdmarkdown425 B
references/card/components/img.mdmarkdown1.4 KB
references/card/components/img_combination.mdmarkdown1.0 KB
references/card/components/input.mdmarkdown2.0 KB
references/card/components/interactive_container.mdmarkdown2.2 KB
references/card/components/markdown.mdmarkdown3.2 KB
references/card/components/multi_select_person.mdmarkdown1.6 KB
references/card/components/multi_select_static.mdmarkdown1.6 KB
references/card/components/overflow.mdmarkdown1.5 KB
references/card/components/person.mdmarkdown907 B
references/card/components/person_list.mdmarkdown1.2 KB
references/card/components/picker_datetime.mdmarkdown1.5 KB
references/card/components/picker_time.mdmarkdown1.5 KB
references/card/components/recycling_container.mdmarkdown1.5 KB
references/card/components/select_img.mdmarkdown1.9 KB
references/card/components/select_person.mdmarkdown1.5 KB
references/card/components/select_static.mdmarkdown1.8 KB
references/card/components/table.mdmarkdown2.1 KB
references/card/lark-im-card-create.mdmarkdown10.8 KB
references/card/lark-im-card-style.mdmarkdown18.3 KB
references/card/resource/colors.mdmarkdown1.4 KB
references/card/resource/icons.mdmarkdown2.3 KB
references/lark-im-card-action-reply.mdmarkdown9.5 KB
references/lark-im-chat-create.mdmarkdown7.9 KB
references/lark-im-chat-identity.mdmarkdown3.3 KB
references/lark-im-chat-list.mdmarkdown9.3 KB
references/lark-im-chat-members-list.mdmarkdown5.2 KB
references/lark-im-chat-messages-list.mdmarkdown11.1 KB
references/lark-im-chat-search.mdmarkdown8.4 KB
references/lark-im-chat-update.mdmarkdown3.5 KB
references/lark-im-feed-group-list-item.mdmarkdown3.1 KB
references/lark-im-feed-group-list.mdmarkdown2.7 KB
references/lark-im-feed-group-query-item.mdmarkdown2.3 KB
references/lark-im-feed-groups.mdmarkdown18.3 KB
references/lark-im-feed-shortcut-create.mdmarkdown4.2 KB
references/lark-im-feed-shortcut-list.mdmarkdown5.0 KB
references/lark-im-feed-shortcut-remove.mdmarkdown2.1 KB
references/lark-im-flag-cancel.mdmarkdown2.9 KB
references/lark-im-flag-create.mdmarkdown2.7 KB
references/lark-im-flag-list.mdmarkdown4.6 KB
references/lark-im-message-enrichment.mdmarkdown7.0 KB
references/lark-im-message-read-status.mdmarkdown4.3 KB
references/lark-im-messages-edit.mdmarkdown6.4 KB
references/lark-im-messages-mget.mdmarkdown6.8 KB
references/lark-im-messages-reply.mdmarkdown17.1 KB
references/lark-im-messages-resources-download.mdmarkdown4.2 KB
references/lark-im-messages-search.mdmarkdown13.6 KB
references/lark-im-messages-send.mdmarkdown19.3 KB
references/lark-im-reactions.mdmarkdown10.3 KB
references/lark-im-scopes.mdmarkdown2.2 KB
references/lark-im-threads-messages-list.mdmarkdown6.4 KB

references/lark-im-chat-create.md

View on GitHub
# im +chat-create

> **Prerequisite:** Read [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.

Create a group chat. Supports both user identity (`--as user`) and bot identity (`--as bot`). You can specify the group name, description, members (users/bots), owner, chat type (private/public), and group mode. Set `--chat-mode topic` to create a topic chat.

This skill maps to the shortcut: `lark-cli im +chat-create` (internally calls `POST /open-apis/im/v1/chats`).

- `--as bot` requires the `im:chat:create` scope.
- `--as user` requires the `im:chat:create_by_user` scope.

## Commands

```bash
# Create a private group (default)
lark-cli im +chat-create --name "My Group"

# Create a public group (name is required and must be at least 2 characters)
lark-cli im +chat-create --name "Public Group" --type public

# Create a topic chat
lark-cli im +chat-create --name "Topic Group" --chat-mode topic

# Specify the group owner
lark-cli im +chat-create --name "My Group" --owner ou_xxx

# Invite user members (comma-separated open_ids, up to 50)
lark-cli im +chat-create --name "My Group" --users "ou_aaa,ou_bbb"

# Invite bot members (comma-separated app IDs, up to 5)
lark-cli im +chat-create --name "My Group" --bots "cli_aaa,cli_bbb"

# Invite both users and bots
lark-cli im +chat-create --name "My Group" --users "ou_aaa" --bots "cli_aaa"

# Make the creating bot a group manager (bot identity only)
lark-cli im +chat-create --name "My Group" --set-bot-manager --as bot

# JSON output
lark-cli im +chat-create --name "My Group" --format json

# Create a group with bot identity
lark-cli im +chat-create --name "My Group" --users "ou_aaa" --as bot

# Create a group with user identity
lark-cli im +chat-create --name "My Group" --users "ou_aaa,ou_bbb" --as user

# Preview the request without creating anything
lark-cli im +chat-create --name "My Group" --dry-run
```

## Parameters

| Parameter | Required | Limits | Description |
|------|------|------|------|
| `--name <name>` | Required for public groups | Max 60 characters; at least 2 characters for public groups | Group name (`"(no subject)"` for private groups if omitted) |
| `--description <text>` | No | Max 100 characters | Group description |
| `--users <ids>` | No | Up to 50, format `ou_xxx` | Comma-separated user open_ids |
| `--bots <ids>` | No | Up to 5, format `cli_xxx` | Comma-separated bot app IDs |
| `--owner <open_id>` | No | Format `ou_xxx` | Owner open_id (defaults to the bot when using `--as bot`, or the authorized user when using `--as user`) |
| `--type <type>` | No | `private` (default) or `public` | Group type. Default to `private`; pass `public` only when the user explicitly asks for a discoverable/public group. |
| `--chat-mode <mode>` | No | `group` (default) or `topic` | Group mode; `topic` creates a topic chat (not the same as `group_message_type=thread`). When the user asks for a topic chat, pass `topic` explicitly — do not rely on the default. |
| `--set-bot-manager` | No | - | Set the creating bot as a group manager (only effective with `--as bot`) |
| `--format json` | No | - | Output as JSON |
| `--as <identity>` | No | `bot` or `user` | Identity type |
| `--dry-run` | No | - | Preview the request without executing it |

> **`--chat-mode topic` vs "normal group with topic-message mode"**: `--chat-mode topic` here creates a 话题群 — the entire group is a topic chat. This is different from "normal group (`chat_mode=group`) + topic-message mode (`group_message_type=thread`)". This CLI exposes only `chat_mode`; `group_message_type` is intentionally not surfaced.

## AI Usage Guidance

### When using `--as bot`

Bot may fail to invite users who are mutually invisible to it during group creation (error 232043). To avoid this, use the **two-step flow** below instead of passing other users' open_ids in `--users`.

1. **Get the current user's open_id:** Run `lark-cli contact +search-user --query "<name or email>"` to retrieve it.
2. **Create the group — by default include the current user:**

   ```bash
   lark-cli im +chat-create --name "<group name>" \
     --users "<current user open_id>" --as bot
   ```

   **Default behavior:** Always add the current user to the group, unless the user explicitly says "do not add me" or "bot-only group" — only then omit `--users`.

3. **Add other members via user identity** (requires the current user to be in the group):

   ```bash
   lark-cli im chat.members create \
     --params '{"chat_id":"<chat_id from step 2>","member_id_type":"open_id","succeed_type":1}' \
     --data '{"id_list":["ou_aaa","ou_bbb"]}' \
     --as user
   ```

   `succeed_type=1` ensures reachable users are added successfully; unreachable ones are returned in `invalid_id_list` instead of failing the whole request.

4. **Check `invalid_id_list`** in the response. If non-empty, report to the user which members could not be added.

### When using `--as user`

User identity does not have the bot visibility limitation, so you can create the group and invite members in one step:

```bash
lark-cli im +chat-create --name "<group name>" --users "ou_aaa,ou_bbb" --as user
```

The authorized user is automatically the group creator and member.

## Output Fields

| Field | Description |
|------|------|
| `chat_id` | The new group's ID (`oc_xxx` format) |
| `name` | Group name |
| `chat_type` | Group type (`private` / `public`) |
| `owner_id` | Owner ID (may be empty when a bot creates the group and `--owner` is not specified) |
| `external` | Whether the group is external |
| `share_link` | Group share link (omitted if retrieval fails) |

## Usage Scenarios

### Scenario 1: Create a group and specify the owner

```bash
lark-cli im +chat-create --name "Project Discussion Group" --owner ou_xxx
```

### Scenario 2: Create a group and invite users and a bot

```bash
lark-cli im +chat-create --name "Project Discussion Group" \
  --owner ou_xxx \
  --users "ou_aaa,ou_bbb" \
  --bots "cli_aaa"
```

### Scenario 3: Create a group and send a welcome message

```bash
# --jq is built into the CLI (no local jq needed); read chat_id from the projected output
lark-cli im +chat-create --name "New Group" --jq '.data.chat_id'
lark-cli im +messages-send --chat-id "<chat_id>" --text "Welcome, everyone!"
```

## Common Errors and Troubleshooting

| Symptom | Root Cause | Solution |
|---------|---------|---------|
| Permission denied (99991672) | The app does not have `im:chat:create` (bot) or `im:chat:create_by_user` (user) permission enabled | Enable the required permission for the app in the Open Platform console |
| `--name is required for public groups and must be at least 2 characters` | A public group was created without a name or with a name shorter than 2 characters | Provide a name with at least 2 characters |
| `--name exceeds the maximum of 60 characters` | The group name is too long | Shorten the name to 60 characters or fewer |
| `--description exceeds the maximum of 100 characters` | The group description is too long | Shorten the description to 100 characters or fewer |
| `--users exceeds the maximum of 50` | Too many user members were provided | Split the operation into batches and add more members later |
| `--bots exceeds the maximum of 5` | Too many bot members were provided | Invite at most 5 bots at once |
| `invalid user id: expected open_id (ou_xxx)` | Invalid user ID format | Use the `ou_xxx` format for users |
| `invalid bot id: expected app ID (cli_xxx)` | Invalid bot ID format | Use the `cli_xxx` format for bots |
| `invalid --owner: expected open_id (ou_xxx)` | Invalid owner ID format | Use the `ou_xxx` format for the owner |
| `bot is invisible to user` (232043) | The bot and target users are mutually invisible | Follow the two-step flow in AI Usage Guidance above — do not pass other users in `--users` during creation |

## References

- [lark-im](../SKILL.md) - all IM commands
- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall