10 KiB
๐ Deployment Guide
Complete guide for deploying Smart Follow-ups to production
Target: Bot with Telegram integration
User: Robby (@robbyczgw-cla)
Status: Ready for testing
๐ Pre-Deployment Checklist
โ Completed
- CLI tool implemented and tested
- Handler integration completed
- All documentation written
- Package structure verified
- Dependencies installed
- License file included
- .gitignore configured
- Test scripts created
๐ฒ Before Production
- Set ANTHROPIC_API_KEY in production environment
- Test CLI with real API calls
- Test Telegram integration with live bot
- Set up error monitoring
- Configure rate limiting (if needed)
- Create GitHub repository
- Publish to npm (optional)
- Submit to Skills
๐ ๏ธ Installation Steps
1. Environment Setup
# Set API key (REQUIRED)
export ANTHROPIC_API_KEY="sk-ant-your-actual-key-here"
# Add to shell profile for persistence
echo 'export ANTHROPIC_API_KEY="sk-ant-your-actual-key-here"' >> ~/.bashrc
source ~/.bashrc
2. Verify Installation
cd /root/bot/skills/smart-followups
./verify.sh
Expected output:
โ
All checks passed!
The skill package is ready for testing.
3. Test CLI Standalone
./test.sh
This will:
- Test help command
- Generate follow-ups in all output modes
- Verify API connectivity
- Show sample outputs
4. Integrate with Bot
Option A: Symbolic Link (Recommended for development)
ln -s /root/bot/skills/smart-followups /path/to/bot/skills/
Option B: Copy (For production)
cp -r /root/bot/skills/smart-followups /path/to/bot/skills/
5. Configure Bot
Edit bot.config.json:
{
"skills": {
"smart-followups": {
"enabled": true,
"autoTrigger": false,
"model": "claude-haiku-4"
}
}
}
Settings:
enabled: Set totrueto activateautoTrigger: Start withfalse, enable after testingmodel: Useclaude-haiku-4for speed/cost
6. Restart Bot
bot daemon restart
Or if using systemd:
sudo systemctl restart bot
๐งช Testing Protocol
Phase 1: CLI Testing (5 minutes)
# Test 1: Basic functionality
echo '[{"user":"What is Docker?","assistant":"Docker is..."}]' | \
node cli/followups-cli.js --mode json
# Test 2: Text mode
cat test-example.json | node cli/followups-cli.js --mode text
# Test 3: Telegram mode
cat test-example.json | node cli/followups-cli.js --mode telegram
Success Criteria:
- โ Returns valid JSON
- โ All 3 categories present (quick, deep, related)
- โ 2 questions per category
- โ No errors or warnings
Phase 2: Bot Integration (10 minutes)
Test in Telegram:
-
Manual trigger test:
User: What is Rust? Bot: [Response about Rust] User: /followupsExpected: 3 inline buttons appear (โก๐ง ๐)
-
Button click test:
- Click any button
- Expected: Question is sent automatically
- Expected: Bot responds to that question
-
Error handling test:
User: /followups(Without prior conversation)
Expected: "Not enough conversation context" message
Phase 3: Auto-Trigger Testing (Optional, 15 minutes)
Enable auto-trigger:
{
"skills": {
"smart-followups": {
"autoTrigger": true
}
}
}
Restart Bot, then test:
-
Auto-generation test:
User: What is Python? Bot: [Response about Python]Expected: Follow-up buttons appear automatically
-
Multiple exchanges test:
- Have 3-4 back-and-forth exchanges
- Expected: Suggestions evolve with conversation
-
Disable and verify:
- Set
autoTrigger: false - Restart Bot
- Expected: No auto-suggestions, manual
/followupsstill works
- Set
๐ Monitoring & Metrics
What to Monitor
-
API Usage:
- Requests per day
- Cost per day (~$0.0001 per request with Haiku)
- Latency (target: <2s)
-
User Engagement:
/followupscommand usage- Button click-through rate
- Most common suggestion types clicked
-
Error Rate:
- API failures
- Parse errors
- Context extraction failures
Logging Setup
Add to Bot config:
{
"logging": {
"skills": {
"smart-followups": {
"level": "info",
"destination": "/var/log/bot/smart-followups.log"
}
}
}
}
Log what:
- Command invocations
- API errors
- Button clicks
- Generation latency
Don't log:
- Full conversation context (privacy)
- API keys
- User IDs (or hash them)
๐ Security Hardening
1. API Key Protection
Never:
- โ Hardcode in source files
- โ Commit to git
- โ Expose in error messages
- โ Log in plain text
Always:
- โ Use environment variables
- โ Rotate keys periodically
- โ Use read-only access if possible
2. Rate Limiting
Add to handler.js (if high traffic expected):
const rateLimit = new Map(); // userId -> lastRequest
function checkRateLimit(userId) {
const now = Date.now();
const lastRequest = rateLimit.get(userId);
if (lastRequest && (now - lastRequest) < 10000) { // 10s cooldown
throw new Error('Please wait before requesting more suggestions');
}
rateLimit.set(userId, now);
}
3. Input Validation
Already implemented in parseContext():
- โ Validates exchange format
- โ Limits context to last 3 exchanges
- โ Handles malformed JSON gracefully
4. Error Handling
Already implemented:
- โ API errors caught and logged
- โ Parse errors handled
- โ User-friendly error messages
๐ Scaling Considerations
Current Capacity
- Users: ~100 concurrent users
- Requests: ~1000/day comfortable
- Cost: ~$0.10/day @ 1000 requests
If Scaling to 10,000+ Users
1. Implement Caching:
const NodeCache = require('node-cache');
const cache = new NodeCache({ stdTTL: 600 }); // 10 min TTL
async function generateFollowups(exchanges) {
const key = hashExchanges(exchanges);
if (cache.has(key)) {
return cache.get(key);
}
const result = await apiCall(exchanges);
cache.set(key, result);
return result;
}
2. Queue System (for auto-trigger mode):
const queue = new Queue('followups');
queue.process(async (job) => {
return await generateFollowups(job.data.exchanges);
});
3. Load Balancing:
- Multiple Bot instances
- Shared Redis cache
- API request distribution
๐ Troubleshooting
Issue: "Module not found: @anthropic-ai/sdk"
Solution:
cd /root/bot/skills/smart-followups
npm install
Issue: Slow response times (>5s)
Possible causes:
- Using Sonnet instead of Haiku
- Check config:
"model": "claude-haiku-4"
- Check config:
- Network latency
- Test:
ping api.anthropic.com
- Test:
- Large context
- Verify: Context limited to 3 exchanges
Solution: Review SKILL.md โ Advanced Configuration
Issue: Buttons not showing on Telegram
Check:
- Channel detection:
console.log(channel) - Bot Telegram config
- Bot permissions (inline keyboard permission)
Debug:
// Add to handler.js
console.log('Channel:', context.channel);
console.log('Supports buttons:', supportsInlineButtons(context.channel));
Issue: Repetitive suggestions
Solution: Increase temperature in cli/followups-cli.js:
temperature: 0.8 // Up from 0.7
๐ Rollback Plan
If issues arise in production:
1. Immediate Disable
Edit Bot config:
{
"skills": {
"smart-followups": {
"enabled": false
}
}
}
Restart: bot daemon restart
2. Revert to Previous Version
cd /root/bot/skills/smart-followups
git checkout v0.9.0 # or previous tag
bot daemon restart
3. Complete Removal
rm -rf /path/to/bot/skills/smart-followups
bot daemon restart
๐ฆ Publishing to Skills
Prerequisites
- Tested thoroughly (all phases above)
- GitHub repository created (public)
- npm package published (optional)
- Screenshots/demo ready
- Skills account created
Submission Checklist
name: smart-followups
version: 1.0.0
description: Generate contextual follow-up suggestions with inline buttons
author: Robby (@robbyczgw-cla)
repository: https://github.com/robbyczgw-cla/bot-smart-followups
license: MIT
tags: [conversation, suggestions, ai, telegram, buttons]
channels: [telegram, discord, slack, signal, imessage]
tested_on:
- bot: 1.0.0
- telegram: true
- signal: true
screenshots:
- telegram_buttons.png
- signal_text.png
demo_video: https://youtube.com/...
๐ฏ Success Metrics
After 1 week in production:
Usage:
/followupsused in >50% of conversations- Button click-through rate >30%
- No critical errors
Performance:
- Average latency <2s
- API error rate <1%
- Cost within budget ($0.20/day)
Feedback:
- User satisfaction score >4/5
- No security incidents
- Feature requests collected
๐ Support & Maintenance
Regular Maintenance (Weekly)
- Review logs for errors
- Check API usage and costs
- Monitor user feedback
- Update dependencies if needed
Emergency Contacts
- Bot issues: Bot team
- API issues: Anthropic support
- Skill issues: @robbyczgw-cla
Documentation Updates
- Keep CHANGELOG.md current
- Update examples with new use cases
- Add FAQs based on user questions
โ Final Pre-Launch Checklist
- API key set and verified
- All tests passing
- Telegram integration tested
- Auto-trigger tested and disabled (start manual)
- Error handling verified
- Logging configured
- Monitoring set up
- Rollback plan documented
- Team briefed
- User documentation ready
- Launch date scheduled
Deployment Status: ๐ก Ready for Testing
Next Step: Test with real Telegram bot
Target Launch: After successful testing phase
Maintainer: @robbyczgw-cla