# lark-integration

Lark Integration Connect Lark (Feishu) to SkillBoss API Hub for bidirectional messaging with full rich content support. Quick Start

# 1. Set credentials

echo "FEISHU_APP_ID=cli_xxx" >> ~/.skillboss/workspace/.env mkdir -p ~/.skillboss/secrets echo "your_app_secret" > ~/.skillboss/secrets/feishu_app_secret

# 2. Start bridge

cd skills/lark-integration/scripts SKILLBOSS_API_KEY=sk_xxx node bridge-webhook.mjs

# 3. Configure Lark webhook URL in developer console
# https://open.larksuite.com → Your App → Event Subscriptions
# URL: http://YOUR_SERVER_IP:3000/webhook

Architecture Lark App ──webhook──► Bridge (port 3000) ──HTTPS──► SkillBoss API Hub │ │ ◄────────── Reply ─────────────┘ Supported Message Types TypeDirectionFormattext↔ BothPlain textpost→ ReceiveRich text with images, linksimage→ ReceiveSingle imageReply← SendText (cards via feishu-card skill) Platform Detection The bridge auto-detects platform from URLs: *.larksuite.com → https://open.larksuite.com (International) *.feishu.cn → https://open.feishu.cn (China) Configuration Environment Variables VariableRequiredDescriptionSKILLBOSS_API_KEYYesSkillBoss API Key for AI inference via API HubFEISHU_APP_IDYesApp ID from Lark Developer ConsoleFEISHU_APP_SECRET_PATHNoPath to secret file (default: ~/.skillboss/secrets/feishu_app_secret)WEBHOOK_PORTNoWebhook listen port (default: 3000)FEISHU_THINKING_THRESHOLD_MSNoDelay before "Thinking..." placeholder (default: 2500)FEISHU_ENCRYPT_KEYNoEncryption key if enabled in Lark Lark App Permissions Enable these scopes in Lark Developer Console → Permissions & Scopes:

Messaging:
im:message - Send and receive messages
im:message:send_as_bot - Send messages as bot
im:resource - Download message resources (images)

Documents (optional):

docx:document:readonly - Read documents
wiki:wiki:readonly - Read wiki spaces
sheets:spreadsheet:readonly - Read spreadsheets
bitable:bitable:readonly - Read bitables
drive:drive:readonly - Access drive files

Scripts bridge-webhook.mjs Main webhook bridge. Receives Lark events, calls SkillBoss API Hub (/v1/pilot), sends replies. FEISHU_APP_ID=cli_xxx SKILLBOSS_API_KEY=sk_xxx node scripts/bridge-webhook.mjs setup-service.mjs Install as launchd service (macOS) for auto-start: node scripts/setup-service.mjs

# Creates ~/Library/LaunchAgents/com.skillboss.feishu-bridge.plist

Image Handling Images in messages are: Detected from post content or image message type Downloaded via Lark API using message_id and image_key Converted to base64 Sent to SkillBoss API Hub as vision content in the chat request // Sent to /v1/pilot as vision message content { type: 'image_url', image_url: { url: 'data:image/png;base64,' } } Group Chat Behavior In group chats, the bridge responds when: Bot is @mentioned Message ends with ? or ？ Message contains trigger words: help, please, why, how, what, 帮, 请, 分析, etc. Message starts with bot name Otherwise, messages are ignored to avoid noise. Reading Documents Use the feishu-doc skill to read Lark documents: node skills/feishu-doc/index.js fetch "https://xxx.larksuite.com/docx/TOKEN" Supported URL types: /docx/ - New documents /wiki/ - Wiki pages (auto-resolves to underlying doc) /sheets/ - Spreadsheets /base/ - Bitables (multi-dimensional tables) Permission Note: Documents must be shared with the bot, or the bot must have tenant-wide read permission. Troubleshooting "forBidden" error when reading docs Document not shared with bot → Add bot as collaborator Missing scope → Enable docx:document:readonly in console No messages received

Check webhook URL is accessible: curl http://YOUR_IP:3000/health

Verify webhook in Lark console shows "Verified" Check bridge logs: journalctl -u lark-bridge -f "must be string" error Old bridge version → Update to use vision content for images Images not received Missing im:resource scope → Enable in Lark console Token expired → Bridge auto-refreshes, restart if stuck Service Management

# Check status

systemctl status lark-bridge

# View logs

journalctl -u lark-bridge -f

# Restart

systemctl restart lark-bridge References Lark Developer Console (International) Feishu Developer Console (China) See references/api-formats.md for message format details See references/setup-guide.md for step-by-step setup