Site icon Efficient Coder

Integrate Feishu into Your Chatbot: The Complete clawd-feishu Plugin Guide

高效码农

How to Integrate Feishu into Your Chatbot: The Complete Guide to the clawd-feishu Plugin

This guide aims to answer one core question: How can you quickly and securely connect your Clawdbot intelligent assistant to the Feishu (or Lark) workplace platform? We will walk through the entire integration process from zero to one using the official @m1heng-clawd/feishu plugin, and delve into best practices for different configuration scenarios.

Why Choose Feishu as a Communication Channel for Your Bot?

Before diving into the technical details, it’s valuable to understand the “why.” Feishu, as a collaboration platform integrating instant messaging, calendar, docs, and video conferencing, has become the operational hub for many organizations. Connecting your bot to Feishu means embedding AI capabilities directly into your team’s daily workflow. Whether it’s auto-responding to FAQs, syncing project updates, handling approval processes, or triggering automated tasks, the bot becomes an “invisible digital colleague” providing seamless service within a familiar chat interface.

The clawd-feishu plugin is the bridge built for this purpose. It encapsulates the complex API interactions with the Feishu Open Platform, allowing you to focus on developing your bot’s business logic without grappling with the underlying communication protocol.

Step 1: Installation and Initial Setup

The core question this section answers: How simple is it to install the clawd-feishu plugin?

The installation process is designed for simplicity. If you use the Clawdbot command-line tool, a single command is all you need:

clawdbot plugins install @m1heng-clawd/feishu

Alternatively, you can use the familiar npm package manager. This is particularly convenient for managing the plugin dependency within a project’s package.json:

npm install @m1heng-clawd/feishu

Once installed, the plugin is in place. However, to bring your bot to life, you need to configure it on the Feishu Open Platform and provide the plugin with the necessary credentials.

Reflection: Offering two installation methods is a thoughtful approach. For developers looking to quickly experiment, the CLI command is straightforward. For long-term, project-based deployment, npm installation integrates seamlessly with existing frontend or Node.js project toolchains, facilitating version locking and dependency management.

Step 2: Feishu App Creation and Core Permission Configuration

The core question this section answers: What is the most critical aspect of configuring an app on the Feishu Open Platform?

All interaction with Feishu starts with a “self-built app.” You need to create one on the Feishu Open Platform and obtain two crucial keys: the App ID and the App Secret. This process is like onboarding your bot; the App ID is its employee badge, and the App Secret is its access password.

The next step is the most critical: permission scoping. Feishu employs granular permissions to ensure data security. The table below lists the core permissions required to run the clawd-feishu plugin:

Permission Scope Permission Name Why is it needed?
User Info contact:user.base:readonly Allows the bot to identify who is sending a message and fetch their basic profile.
Messaging im:message The foundation for sending and receiving messages.
Direct Messages im:message.p2p_msg:readonly Read messages sent to the bot in private chats.
Group @Mentions im:message.group_at_msg:readonly In group chats, the bot only reads messages where it is specifically @mentioned. This is the default polite mode.
Send Messages im:message:send_as_bot Allows the bot to reply to messages as the application.
Resource Upload im:resource Enables the bot to upload images and files as message content.

Scenario-Based Example: Imagine your bot is a “Team Assistant.” When a colleague, Xiao Zhang, privately messages it on Feishu asking, “What’s today’s meeting schedule?”, the bot needs the p2p_msg permission to read the question, the send_as_bot permission to reply with the answer, and might use the user.base permission to identify Xiao Zhang is from the Marketing department, thereby providing more relevant meeting details.

Furthermore, the plugin supports a range of optional permissions for advanced functionality:

  • im:message.group_msg: Read all messages in a group (sensitive permission, use with caution).
  • im:message:readonly: Access message history for context analysis.
  • im:message:update / im:message:recall: Allow the bot to edit or recall sent messages, enabling self-correction.
  • im:message.reactions:read: View emoji reactions (👍, ❤️, etc.) on messages as a form of user feedback.

Personal Insight: Permission configuration is an art of balancing security and functionality. My advice is to follow the “principle of least privilege.” Initially, only apply for the permissions you absolutely need. For example, unless there’s a strong business requirement (like group chat moderation), avoid applying for the group_msg permission that “listens to all group messages.” This not only reduces security risks but also makes it easier to get approval from enterprise administrators when launching the app.

Step 3: In-Depth Configuration Guide and Strategy Selection

The core question this section answers: What specific use case does each option in the YAML configuration file correspond to?

After obtaining credentials, you need to activate the plugin via Clawdbot’s configuration commands or by editing the config file directly. The core setup looks like this:

clawdbot config set channels.feishu.appId “cli_xxxxx”
clawdbot config set channels.feishu.appSecret “your_app_secret”
clawdbot config set channels.feishu.enabled true

However, the real flexibility lies in the more detailed YAML configuration. Let’s break down each option:

channels:
  feishu:
    enabled: true
    appId: “cli_xxxxx”
    appSecret: “secret”
    # Key Config 1: Domain
    domain: “feishu”
    # Key Config 2: Connection Mode
    connectionMode: “websocket”
    # Key Config 3: Direct Message Policy
    dmPolicy: “pairing”
    # Key Config 4: Group Chat Policy
    groupPolicy: “allowlist”
    # Key Config 5: Group Response Condition
    requireMention: true

1. Domain: domain: “feishu” or “lark”
This setting directly distinguishes between the domestic version (Feishu) and the international version (Lark). It determines the server endpoint the plugin connects to. If your team uses the larksuite.com domain, this must be set to “lark”.

2. Connection Mode: connectionMode: “websocket” or “webhook”
This is a core architectural choice for the plugin.

  • WebSocket (Recommended): The bot actively establishes a persistent connection with Feishu’s servers. Messages are pushed in real-time with minimal latency. This is like staying online waiting for a call; you can process messages immediately. It doesn’t require a public IP address or complex reverse proxy setup and is the preferred choice for most scenarios.
  • Webhook: You need to provide a publicly accessible URL. Feishu servers actively call this URL when events occur. This is suitable if your server is behind a strict firewall or if you have an existing HTTP service architecture. You’ll need to handle signature verification, retries, etc.

Scenario Comparison: Choosing a connection mode for a “fun Q&A bot” used internally by a startup team with no dedicated ops personnel, deployed on a simple cloud server. In this case, the WebSocket mode requires almost no additional network configuration, making it the most hassle-free and quickest option to launch.

3. Direct Message Policy: dmPolicy
This policy controls who can send direct messages to your bot.

  • “pairing”: Users need to go through a “pairing” flow (e.g., sending a specific command) before they can start a DM. This effectively prevents the bot from being spammed by unrelated users.
  • “open”: Any Feishu user can directly message the bot. Suitable for publicly available service bots.
  • “allowlist”: Only user IDs pre-configured in an allowlist can send DMs. Offers the highest security, ideal for bots handling sensitive information.

4. Group Chat Policy & Mention Requirement: groupPolicy and requireMention
These two settings together manage the bot’s behavior in group chats.

  • groupPolicy: “allowlist” and requireMention: true: This is the most common and courteous configuration. The bot only operates in specific, allowed groups, and only responds when a group member @mentions it. This prevents the bot from spamming the chat and ensures its responses are always contextually relevant.
  • groupPolicy: “open”: The bot can join any group it’s added to. Suitable for an assistant used by all internal employees, but should be paired with a strict requireMention setting.
  • groupPolicy: “disabled”: Completely disables group chat functionality; the bot only offers direct messaging services.

Reflection: Policies like pairing and allowlist reflect excellent design philosophy. They internalize social etiquette and access control mechanisms directly into the communication configuration. This allows developers to easily build bots that are both friendly and secure, rather than creating “digital noise” that chatters incessantly in groups or can be disturbed by anyone.

Step 4: Core Features Demonstrated Through Real Scenarios

The core question this section answers: How are the features provided by this plugin used in real workplace scenarios?

Once properly configured, your bot gains the following capabilities. Let’s experience them through specific scenarios:

Scenario 1: Technical Support Bot (Leveraging Message Replies & Context)
An employee @mentions the bot in a group: “What was the issue with the API returning 500 errors yesterday?” The bot can not only reply with the latest incident report but, using the plugin’s support for “quoted message context,” can precisely associate the answer with the question, creating a clear conversation thread. It can even show a “typing” indicator (simulated by the plugin via emoji reactions) to let the asker know it’s processing, enhancing the user experience.

Scenario 2: Daily Report Collection Bot (Leveraging File Upload & DMs)
The bot privately messages each team member at 5 PM daily, reminding them to submit their reports. Members can simply drag and drop their completed Word or Excel documents into the chat window. Using the im:resource permission, the bot uploads and parses the file, automatically aggregating the content into a backend database. For members who haven’t submitted, the bot uses the “pairing flow” enabled DM channel to send a gentle follow-up reminder.

Scenario 3: Team Task Assistant (Leveraging User & Group Directory)
A project manager says in the project group: “@Xiao Wang, please send the final design proposal.” The bot can listen for this message (requires the group_msg permission) and, using the contact:user.base permission, identify the user corresponding to “Xiao Wang.” It then automatically creates a private task reminder sent to Xiao Wang: “You were mentioned in the ‘Project Group’ regarding the task ‘Send the final design proposal’.” This achieves lightweight cross-platform task synchronization.

Practical Summary & Action Checklist

To help you implement quickly, here is a step-by-step checklist:

  1. Environment Prep: Ensure you have a Clawdbot runtime environment.
  2. Install Plugin: Run clawdbot plugins install @m1heng-clawd/feishu.
  3. Create Feishu App: Visit the Feishu Open Platform, create a self-built app, and obtain the App ID and App Secret.
  4. Apply for Core Permissions: On the app’s permission management page, precisely add the 6 required permissions like contact:user.base:readonly and im:message.
  5. Determine Advanced Policies: Based on the bot’s purpose, decide on the connection mode (prefer WebSocket), DM policy (recommend pairing), and group chat policy (recommend allowlist + requireMention).
  6. Configure Plugin: Use the clawdbot config set commands or edit the config file to input credentials and set the above policies.
  7. Publish & Test: Publish a version of the app on the Open Platform and invite team members to test. Start by pairing in DMs or adding the bot to an allowed group, @mention your bot, and begin interacting!

One-Page Overview

  • Plugin Name: @m1heng-clawd/feishu
  • Core Value: Provides a secure, feature-complete enterprise-grade integration channel between Clawdbot and the Feishu/Lark platform.
  • Installation: One CLI command or npm install.
  • Core Permissions: 6 required, covering identity, message exchange, and basic file capabilities.
  • Key Configuration:
    • domain: Distinguishes Feishu (feishu) from Lark (lark).
    • connectionMode: WebSocket (real-time, no public IP needed, recommended) vs. Webhook (requires callback URL).
    • dmPolicy: Controls DM access (pairing requires authorization).
    • groupPolicy + requireMention: Controls group chat behavior and response conditions.
  • Recommended Strategy: WebSocket connection + DM pairing + group allowlist requiring @mention. This balances functionality, etiquette, and security.

Frequently Asked Questions

FAQ 1: My team uses the international version, Lark. Does this plugin support it?
Yes, fully supported. Simply set the domain parameter in the configuration to "lark". The plugin will automatically connect to the Lark international service endpoints.

FAQ 2: Should I choose WebSocket or Webhook mode?
For the vast majority of cases, especially when starting out, choose WebSocket mode. It doesn’t require you to have a public-facing server or configure complex networking, is simpler to implement, and has lower latency. Only consider Webhook mode if your bot’s deployment environment imposes restrictions (e.g., can only receive incoming requests).

FAQ 3: Why isn’t my bot responding in the group chat, even when I @mention it?
Check in order: 1) Is groupPolicy in the config set to "open" or is the group in the "allowlist"? 2) Is requireMention set to true (if yes, it must be @mentioned to respond)? 3) Does the Feishu app have the im:message.group_at_msg:readonly permission, and is the latest version published?

FAQ 4: Under the “pairing” policy, how does a user start a direct message with the bot?
Typically, a trigger command is needed. For example, you can inform users in a group chat or the bot’s description: “To chat privately with the assistant, send it the keyword ‘start’ or ‘pair’.” Upon receiving this DM command, the bot can add the user to its conversation list and open the DM channel.

FAQ 5: Does the plugin support sending images or files?
Yes. Through the im:resource permission, the plugin supports file uploads. In your bot’s business logic, you can handle local image or file paths and call the interfaces provided by the plugin to send them as message content to Feishu conversations.

FAQ 6: How can I allow the bot to access more group messages for analysis?
This requires applying for the sensitive im:message.group_msg permission. Please note, this permission usually requires additional approval from enterprise administrators. Ensure your bot’s privacy policy clearly states how messages are processed and use this permission only for legitimate and necessary business scenarios.

By working through this guide, you should now have a comprehensive understanding of how to use the clawd-feishu plugin to inject your bot’s capabilities into Feishu’s collaboration stream. From straightforward installation to granular policy configuration, each step aims to balance developer convenience, powerful functionality, and system security. Now, it’s time to build your first Feishu intelligent assistant and let it become a force multiplier for your team’s productivity.

Exit mobile version