Skip to main content

​
Feishu Digital Twin Integration

Zeus supports deep integration with Feishu (Lark), creating your digital twin with auto-reply, message synchronization, and intelligent assistant capabilities.

​
Overview

The Feishu digital twin is an AI agent running on Feishu that can:
  • Auto-reply to messages - Reply on your behalf in private chats and group chats
  • Smart activation strategies - Support @ trigger or all-message reply
  • SSE streaming updates - Real-time message card updates showing the thinking process
  • Tool call visualization - Display tool execution status in message cards
  • Reuse Zeus capabilities - Inherit full Agent capabilities and personality settings

​
Architecture Design

​
Quick Start

​
1. Create Feishu Application

  1. Visit Feishu Open Platform to create an application
  2. Add Bot capability
  3. Configure permissions:
    • im:message - Get and send messages
    • im:message.group_at_msg - Receive group @ messages
    • im:chat - Get chat information
  4. Obtain App ID and App Secret

​
2. Configure Event Subscription

Configure event subscription on the Feishu Open Platform:
  • Request URL: https://your-domain.com/api/channels/feishu/webhook
  • Subscribe to events: im.message.receive_v1 (receive messages)

​
3. Environment Variables

Configure the following environment variables in your .env file:
  • FEISHU_APP_ID - Feishu App ID
  • FEISHU_APP_SECRET - Feishu App Secret
  • FEISHU_VERIFICATION_TOKEN - Verification Token
  • FEISHU_ENCRYPT_KEY - Message encryption key (optional)
  • FEISHU_DM_ACTIVATION - Direct message activation strategy (always or mention)
  • FEISHU_GROUP_ACTIVATION - Group chat activation strategy (always or mention)
  • FEISHU_ALLOWED_USERS - User allowlist (optional, comma-separated)
  • FEISHU_ALLOWED_CHATS - Chat allowlist (optional, comma-separated)

​
4. Publish Application

After configuration, publish the application on the Feishu Open Platform to start using it.

​
Activation Strategies

Inspired by OpenClaw design, supporting flexible activation strategies:
StrategyDescriptionUse Case
alwaysReply to all messagesPersonal assistant, dedicated groups
mentionReply only when @ mentionedPublic groups, multi-person collaboration
Independent configuration per scenario:
  • Direct message strategy - Default always (always reply in DMs)
  • Group chat strategy - Default mention (reply only when @ mentioned in groups)
  • Allowlist - Configurable user and chat allowlists; when empty, all are allowed

​
SSE Streaming Message Sync

Zeus supports synchronizing the complete SSE message stream to Feishu, delivering a real-time experience similar to the Web interface.

​
Message Type Mapping

SSE Message TypeFeishu Display
TextMessageReal-time content update
ToolCallMessageShow tool call status
ToolCallResultMessageUpdate tool execution result
CompleteMessageFinal completion state
ErrorMessageError notification

​
Implementation

​
Preview

Message cards update in real-time, showing the complete thinking and execution process: 
┌─────────────────────────────────────┐
│ Zeus AI                        🔵    │
├─────────────────────────────────────┤
│ Based on search results, today's     │
│ key news includes:                   │
│ 1. AI technology breakthrough...     │
│ 2. Tech company earnings...          │
│─────────────────────────────────────│
│ 🔧 Tool calls:                       │
│ ✅ web_search                        │
└─────────────────────────────────────┘

​
API Endpoints

​
Webhook Receiver

POST /api/channels/feishu/webhook Handled event types:
  • url_verification - URL verification (initial setup)
  • im.message.receive_v1 - Receive messages

​
Message Card Templates

Recommended to use Feishu message cards for displaying AI replies, supporting:
  • Status indicators (thinking/replying/completed)
  • Markdown content rendering
  • Collapsible tool call display
  • Error message alerts

​
Advanced Features

​
Planned Features

FeaturePriorityDescription
Message MemoryP0Use MemoryService, isolated by chat_id
Group Chat ContextP0Remember conversation context in group chats
@ ReplyP0Automatically @ the questioner when replying in group chats
Message CardsP1Use Feishu message cards for complex content display
Delayed ReplyP1Simulate thinking time for more natural responses
Calendar IntegrationP2Integrate Feishu Calendar, auto-reply “I’m in a meeting”
File ProcessingP2Process images, documents, and other attachments
Offline ModeP2Auto-reply during “do not disturb” periods
Cron Proactive MessagesP3Send daily reports, reminders on schedule

​
Integration with Other Channels

The Feishu channel design follows a generic Channel abstraction, extensible to support:
  • Slack
  • Discord
  • WeCom
  • Telegram
  • DingTalk

​
Security Considerations

​
Signature Verification

It is recommended to enable Feishu event signature verification using SHA-256 HMAC to verify request signatures, ensuring trusted message sources. Verification requires checking the X-Lark-Request-Timestamp and X-Lark-Request-Nonce request headers.

​
Allowlist Mechanism

  • Supports user allowlist (allowed_users)
  • Supports chat allowlist (allowed_chats)
  • When not configured, all are allowed by default

​
Sensitive Operation Protection

For major decisions, financial, legal, and other sensitive issues, the digital twin will explicitly state that the actual person’s confirmation is needed.

​
References