name	lark-bot-integration
description	Deploy and manage Lark (Feishu) bot for Milady meme generation, command handling, and team collaboration. Use when setting up Lark webhooks, handling bot commands, deploying to production, or integrating with Lark messaging.
allowed-tools	Read, Write, Bash
model	claude-sonnet-4-20250514

Lark Bot Integration

Complete Lark (Feishu/飞书) bot system for interactive Milady meme generation and team collaboration.

Overview

Deploy a fully-featured Lark bot that:

Handles 10+ commands for meme generation
Processes @mentions and direct messages
Uploads images directly to Lark chats
Manages webhooks with automatic token refresh
Integrates all Skills - Milady generator, AI effects, Twitter content

Quick Start

1. Configure Lark App

# Set environment variables
export LARK_APP_ID="cli_xxxxxxxxxxxxx"
export LARK_APP_SECRET="your_app_secret"

# Verify configuration
python scripts/setup_webhook.py --verify

2. Start Webhook Server

# Start on port 8000
python webhook_server.py

# Or use startup script
./start_lark_bot.sh

3. Set Webhook URL

# Get your public URL (use ngrok or public server)
python scripts/setup_webhook.py --url https://your-domain.com/webhook

4. Get Chat ID

# Get group chat ID for posting
python scripts/get_chat_id.py

Supported Commands

Meme Generation Commands

Command	Description	Example
`/milady`	Generate Milady meme	`/milady 5050`
`/milady [layers]`	Add accessories	`/milady 5050 Hat:Beret.png`
`/milady [text]`	Add text overlay	`/milady 5050 top:GM bottom:WAGMI`
`/memegen`	Classic meme templates (207+)	`/memegen drake old way new way`

AI Effects Commands

Command	Description	Cost	Example
`/milady_illusion`	Illusion Diffusion effect	$0.006	`/milady_illusion 5050`
`/milady_replace`	FLUX Fill Pro replace	$0.05	`/milady_replace 5050 hat red cap`
`/milady_replace_sam`	SAM + FLUX replace	$0.05	`/milady_replace_sam 5050 glasses cool shades`

Twitter Content Commands

Command	Description	Cost	Example
`/tweet gm`	Generate GM tweet	~$0.02	`/tweet gm`
`/tweet insight`	Generate insight tweet	~$0.03	`/tweet insight data ownership`
`/tweet casual`	Generate casual tweet	~$0.02	`/tweet casual weekend vibes`
`/tweet reply`	Generate reply tweet	~$0.02	`/tweet reply Great point!`

Social Monitoring Commands

Command	Description	Cost	Example
`/monitor mentions`	Check @mentions	FREE	`/monitor mentions`
`/monitor account`	Monitor user tweets	FREE	`/monitor account vitalikbuterin`
`/monitor opportunities`	Find interaction opportunities	FREE	`/monitor opportunities`
`/monitor stats`	View monitoring stats	FREE	`/monitor stats`

Training Data Commands

Command	Description	Cost	Example
`/training check`	Check content freshness	FREE	`/training check gm builders`
`/training stats`	View training stats	FREE	`/training stats`
`/training add`	Add training sample	FREE	`/training add gm hello world`
`/training freshness`	Detailed freshness analysis	FREE	`/training freshness test content`

Utility Commands

Command	Description	Example
`/help`	Show all commands	`/help`
`/balance`	Check Replicate credit	`/balance`

Command Examples

Basic Meme

/milady 5050

Result: NFT #5050 as image

With Accessories

/milady 5050 Hat:Beret.png Glasses:Sunglasses.png

Result: NFT #5050 + beret + sunglasses

With Text

/milady 5050 top:"Good Morning" bottom:"Let's Go"

Result: NFT #5050 with text overlay

Natural Language

/milady 5050 give her a cowboy hat and heart sunglasses

Result: Bot parses "cowboy hat" → Hat:Cowboy.png, "heart sunglasses" → Glasses:Heart Shaped.png

AI Effects

/milady_illusion 5050 spiral pattern

Result: NFT #5050 with illusion diffusion effect ($0.006)

/milady_replace_sam 5050 hat blue baseball cap

Result: SAM detects hat, FLUX replaces with blue baseball cap ($0.05)

Template Meme

/milady_template drake

Result: Random Milady in Drake meme template

Architecture

Webhook Flow

User sends message in Lark
        ↓
Lark sends POST to /webhook
        ↓
webhook_server.py receives event
        ↓
LarkMemeBot processes command
        ↓
Calls MemeGenerator/AI Effects
        ↓
Uploads result to Lark
        ↓
User sees image in chat

File Structure

lark-bot-integration/
├── SKILL.md                    # This file
├── SETUP_GUIDE.md              # Detailed setup
├── COMMAND_REFERENCE.md        # All commands
├── DEPLOYMENT.md               # Production deployment
├── src/
│   ├── lark_meme_bot.py        # Main bot logic
│   ├── webhook_handler.py      # Webhook processing
│   └── lark_api.py             # Lark API wrapper
├── config/
│   └── lark_config.yaml        # Bot configuration
└── scripts/
    ├── setup_webhook.py        # Webhook setup tool
    ├── get_chat_id.py          # Get chat IDs
    └── approve.py              # Approval workflow

Setup Guide

Prerequisites

Lark Developer Account
- Go to https://open.larksuite.com/
- Create new app
- Enable bot capability
Server with Public URL
- Can use ngrok for testing
- Production: VPS or cloud server
Required Permissions
- Send messages
- Receive messages
- Upload files
- Read group info

Detailed Setup Steps

See SETUP_GUIDE.md for step-by-step instructions including:

Creating Lark app
Configuring event subscriptions
Setting up permissions
Webhook URL verification
Testing the bot

Using Ngrok (Development)

# Start ngrok tunnel
./start_tunnel.sh

# Ngrok will output URL like: https://abc123.ngrok.io
# Use this as webhook URL: https://abc123.ngrok.io/webhook

# Set webhook
python scripts/setup_webhook.py --url https://abc123.ngrok.io/webhook

Bot Implementation

Main Bot Class

from src.lark_meme_bot import LarkMemeBot

# Initialize bot
bot = LarkMemeBot(
    app_id=os.getenv("LARK_APP_ID"),
    app_secret=os.getenv("LARK_APP_SECRET")
)

# Process incoming message
bot.handle_message(
    message_id="om_xxxxx",
    chat_id="oc_xxxxx",
    text="/milady 5050",
    user_id="ou_xxxxx"
)

Adding Custom Commands

# In src/lark_meme_bot.py

def handle_custom_command(self, text, chat_id):
    """Add your custom command handler"""

    if text.startswith("/mycommand"):
        # Your logic here
        result = do_something()

        # Send response
        self.send_message(chat_id, "Done!")

        # Upload image if needed
        if image_path:
            self.upload_image(chat_id, image_path)

Webhook Server

from flask import Flask, request
from src.lark_meme_bot import LarkMemeBot

app = Flask(__name__)
bot = LarkMemeBot()

@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.get_json()

    # Handle event
    if data.get('type') == 'message':
        bot.handle_message(
            message_id=data['message']['message_id'],
            chat_id=data['message']['chat_id'],
            text=data['message']['text']
        )

    return {'success': True}

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8000)

Message Formats

Text Messages

bot.send_message(chat_id, "Hello from AI Content Studio! 🎀")

Card Messages (Rich Format)

bot.send_card(
    chat_id=chat_id,
    title="Meme Generated!",
    content="Your Milady meme is ready",
    image_key=image_key
)

Image Upload

# Upload and send image
image_key = bot.upload_image(
    chat_id=chat_id,
    image_path="/path/to/meme.png"
)

Error Handling

Common Issues

1. Webhook verification failed

# Check URL is publicly accessible
curl https://your-domain.com/webhook

# Verify in Lark console:
# Settings > Event Subscriptions > Verify URL

2. Messages not received

# Check event subscriptions are enabled
# Required events:
# - im.message.receive_v1
# - im.message.mention_v1

3. Image upload fails

# Check image size (max 10MB for Lark)
# Check file format (PNG, JPG supported)
# Verify upload permission is granted

4. Token expired

# Token auto-refreshes every 2 hours
# Manual refresh:
bot.refresh_token()

Approval Workflow

For production use with Twitter posting:

# Start approval workflow
python scripts/approve.py

# Bot generates content → sends to Lark
# Team reviews in Lark chat
# Approved tweets get posted to Twitter

Approval Flow

1. Bot generates tweet/meme
2. Posts to Lark approval channel
3. Team reacts with ✅ (approve) or ❌ (reject)
4. If approved → Posts to Twitter
5. If rejected → Logs feedback for learning

Production Deployment

Using systemd (Linux)

# Create service file
sudo nano /etc/systemd/system/lark-bot.service

# Add:
[Unit]
Description=Lark Meme Bot
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/ai-content-studio
Environment="LARK_APP_ID=cli_xxxxx"
Environment="LARK_APP_SECRET=xxxxx"
ExecStart=/usr/bin/python3 webhook_server.py
Restart=always

[Install]
WantedBy=multi-user.target

# Enable and start
sudo systemctl enable lark-bot
sudo systemctl start lark-bot

Using Docker

FROM python:3.9-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["python", "webhook_server.py"]

# Build and run
docker build -t lark-bot .
docker run -d -p 8000:8000 \
  -e LARK_APP_ID=cli_xxxxx \
  -e LARK_APP_SECRET=xxxxx \
  lark-bot

Using nohup (Simple)

# Start in background
nohup python3 webhook_server.py > webhook.log 2>&1 &

# Check status
ps aux | grep webhook_server

# View logs
tail -f webhook.log

Monitoring

Check Bot Status

# View logs
tail -f webhook.log

# Check if running
ps aux | grep webhook_server

# Test webhook
curl -X POST https://your-domain.com/webhook \
  -H "Content-Type: application/json" \
  -d '{"type":"test"}'

Metrics to Track

Messages received per hour
Commands processed
Images generated
API errors
Response time

Security

Best Practices

Environment Variables

# Never commit credentials
# Use .env file (add to .gitignore)
LARK_APP_ID=cli_xxxxx
LARK_APP_SECRET=xxxxx

Webhook Verification

# Verify requests come from Lark
def verify_webhook(request):
    # Check signature
    # Validate timestamp
    # Reject invalid requests

Rate Limiting

# Prevent abuse
from flask_limiter import Limiter

limiter = Limiter(app, default_limits=["100 per hour"])

Access Control

# Restrict to specific chats/users
ALLOWED_CHATS = ["oc_xxxxx", "oc_yyyyy"]

if chat_id not in ALLOWED_CHATS:
    return "Unauthorized"

Advanced Features

Multi-Language Support

# Detect language and respond accordingly
if user_language == "zh-CN":
    response = "梗图生成中..."
else:
    response = "Generating meme..."

Command Shortcuts

# Define aliases
COMMAND_ALIASES = {
    "/m": "/milady",
    "/mr": "/milady_random",
    "/mi": "/milady_illusion"
}

Scheduled Posts

# Use APScheduler for timed posts
from apscheduler.schedulers.background import BackgroundScheduler

scheduler = BackgroundScheduler()
scheduler.add_job(
    func=bot.post_daily_gm,
    trigger="cron",
    hour=9,
    minute=0
)
scheduler.start()

Integration with Other Skills

With Milady Generator

from skills.milady_meme_generator.src.meme_generator_v2 import MemeGeneratorV2

generator = MemeGeneratorV2()
image = generator.generate_meme(nft_id=5050)
bot.upload_image(chat_id, image)

With AI Effects

from skills.ai_image_effects.src.flux_fill_pro import FluxFillPro

flux = FluxFillPro()
result = flux.replace_accessory(image, "hat", "cool beanie")
bot.upload_image(chat_id, result)

With Twitter Content

from skills.twitter_content_ai.src.content_generator import ContentGenerator

content = ContentGenerator()
tweet = content.generate_gm_post()
bot.send_message(chat_id, f"Suggested tweet:\n\n{tweet}")

Troubleshooting

See DEPLOYMENT.md for comprehensive troubleshooting guide.

Related Skills

milady-meme-generator - Core meme generation
ai-image-effects - AI effects integration
twitter-content-ai - Content generation

Cost: Free (Lark API is free, only AI effects have costs)

Install Skill

SKILL.md