lark-bot-integration

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

1. Lark Developer Account

   • Go to https://open.larksuite.com/
   • Create new app
   • Enable bot capability

2. Server with Public URL

   • Can use ngrok for testing
   • Production: VPS or cloud server

3. 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

1. Environment Variables

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

2. Webhook Verification

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

3. Rate Limiting

   # Prevent abuse
   from flask_limiter import Limiter
   
   limiter = Limiter(app, default_limits=["100 per hour"])
   

4. 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 Documentation

• SETUP_GUIDE.md - Step-by-step setup
• COMMAND_REFERENCE.md - All commands
• DEPLOYMENT.md - Production deployment
• Lark Open Platform Docs

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)