{ "schemaVersion": "1.0", "item": { "slug": "telebiz-mcp-skill", "name": "Telebiz Mcp", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/acastellana/telebiz-mcp-skill", "canonicalUrl": "https://clawhub.ai/acastellana/telebiz-mcp-skill", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/telebiz-mcp-skill", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=telebiz-mcp-skill", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md", "dist/daemon.d.ts", "dist/daemon.js", "dist/health.d.ts", "dist/health.js", "dist/http-server.d.ts" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-05-07T17:22:31.273Z", "expiresAt": "2026-05-14T17:22:31.273Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report", "contentDisposition": "attachment; filename=\"afrexai-annual-report-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/telebiz-mcp-skill" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/telebiz-mcp-skill", "agentPageUrl": "https://openagent3.xyz/skills/telebiz-mcp-skill/agent", "manifestUrl": "https://openagent3.xyz/skills/telebiz-mcp-skill/agent.json", "briefUrl": "https://openagent3.xyz/skills/telebiz-mcp-skill/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "telebiz-mcp", "body": "MCP integration for Telegram via telebiz-tt browser client." }, { "title": "Quick Rules (read this first)", "body": "Rate limits are strict: max 20 calls/request, 30 calls/min, 500ms between calls, heavy ops 1s.\nFor adding many chats to folders: do NOT use batchAddToFolder with multiple chatIds (known bug). Loop addChatToFolder sequentially.\nFor CRM linking: linkEntityToChat is unstable in our tests. We observed company failing with Validation error, and at one point organization succeeding — but later organization also failed. Treat linkEntityToChat as unreliable until upstream clarifies schema/feature flags.\nPrefer reversible operations and clean up test artifacts (folders, groups) immediately." }, { "title": "Architecture", "body": "┌──────────────┐ ┌──────────────────┐ ┌─────────────────┐\n│ Clawdbot │────▶│ MCP Server │────▶│ WebSocket Relay │\n│ (mcporter) │ │ (stdio) │ │ (port 9716) │\n└──────────────┘ └──────────────────┘ └────────┬────────┘\n │\n ▼\n ┌─────────────────┐\n │ Browser │\n │ (telebiz-tt) │\n │ [executor] │\n └─────────────────┘" }, { "title": "Prerequisites", "body": "Node.js 18+\nTelegram account" }, { "title": "1. Install telebiz-mcp", "body": "npm install -g @telebiz/telebiz-mcp" }, { "title": "2. Open Telebiz in browser", "body": "Go to https://telebiz.io and login with your Telegram account." }, { "title": "3. Start the HTTP server", "body": "cd ~/clawd/skills/telebiz-mcp\n./start-http.sh\n\nThis starts a persistent server that:\n\nRuns telebiz-mcp internally\nKeeps browser connection alive\nExposes HTTP API on port 9718" }, { "title": "4. Enable MCP in Telebiz", "body": "In telebiz.io: Settings → Agent → Local MCP\n\nThe status should show \"Connected\" once the server is running." }, { "title": "4. Verify connection", "body": "# Quick health check\ncd ~/clawd/skills/telebiz-mcp\nnpm run health\n\n# Should show:\n# 📱 Telebiz MCP Status\n# ────────────────────\n# Relay: ✅ Running\n# Executor: ✅ Connected\n# Tools: 31 available" }, { "title": "5. Test via mcporter", "body": "cd ~/clawd\nmcporter call telebiz.listChats limit:5" }, { "title": "Manual Check", "body": "# Check status\nnpm run health\n\n# JSON output for automation\nnode dist/health.js --json" }, { "title": "Monitor Script", "body": "The monitor tracks state changes and can be used with cron:\n\n# Check and alert on changes\nnpm run monitor\n\n# Quiet mode - only output on state change\nnode dist/monitor.js --quiet\n\n# JSON output\nnode dist/monitor.js --json\n\nExit codes:\n\n0 = Healthy (relay up, executor connected)\n1 = Degraded (relay up, executor disconnected)\n2 = Down (relay not running)\n3 = State changed (for alerting)" }, { "title": "Cron Integration", "body": "Add to crontab for periodic monitoring:\n\n# Check every 5 minutes, alert on changes\n*/5 * * * * cd ~/clawd/skills/telebiz-mcp && node dist/monitor.js --quiet >> /var/log/telebiz-monitor.log 2>&1" }, { "title": "Heartbeat Integration", "body": "Add to HEARTBEAT.md for Clawdbot monitoring:\n\n### Telebiz MCP (every 2h)\n- [ ] Run: `cd ~/clawd/skills/telebiz-mcp && npm run health`\n- [ ] If degraded/down: Alert Albert via Telegram" }, { "title": "Chat Tools", "body": "ToolDescriptionlistChatsList chats with filters (type, unread, archived, etc.)getChatInfoGet detailed chat informationgetCurrentChatGet currently open chatopenChatNavigate to a chatarchiveChatArchive a chatunarchiveChatUnarchive a chatpinChatPin a chatunpinChatUnpin a chatmuteChatMute notificationsunmuteChatUnmute notificationsdeleteChatDelete/leave chat ⚠️" }, { "title": "Message Tools", "body": "ToolDescriptionsendMessageSend text message (markdown supported)forwardMessagesForward messages between chatsdeleteMessagesDelete messages ⚠️searchMessagesSearch globally or in a chatgetRecentMessagesGet message historymarkChatAsReadMark all messages as read" }, { "title": "Folder Tools", "body": "ToolDescriptionlistFoldersList all chat folderscreateFolderCreate a new folderaddChatToFolderAdd chat to foldersremoveChatFromFolderRemove chat from foldersdeleteFolderDelete a folder ⚠️" }, { "title": "Member Tools", "body": "ToolDescriptiongetChatMembersList group/channel membersaddChatMembersAdd users to groupremoveChatMemberRemove user from groupcreateGroupCreate a new group" }, { "title": "User Tools", "body": "ToolDescriptionsearchUsersSearch by name/usernamegetUserInfoGet user details" }, { "title": "Batch Tools", "body": "ToolDescriptionbatchSendMessageSend to multiple chatsbatchAddToFolderAdd multiple chats to folderbatchArchiveArchive multiple chats" }, { "title": "Find chats waiting for my reply", "body": "mcporter call telebiz.listChats iAmLastSender=false hasUnread=true limit:20" }, { "title": "Find stale conversations I started", "body": "mcporter call telebiz.listChats iAmLastSender=true lastMessageOlderThanDays:7 limit:20" }, { "title": "Search all messages", "body": "mcporter call telebiz.searchMessages query=\"invoice\" limit:20" }, { "title": "Search in specific chat", "body": "mcporter call telebiz.searchMessages query=\"meeting\" chatId=-1001234567890 limit:10" }, { "title": "Send message", "body": "mcporter call telebiz.sendMessage chatId=-1001234567890 text=\"Hello from Clawdbot!\"" }, { "title": "Get recent messages", "body": "mcporter call telebiz.getRecentMessages chatId=-1001234567890 limit:50" }, { "title": "Paginate through history", "body": "# Page 1 (newest 50)\nmcporter call telebiz.getRecentMessages chatId=-1001234567890 limit:50 offset:0\n\n# Page 2 (messages 51-100)\nmcporter call telebiz.getRecentMessages chatId=-1001234567890 limit:50 offset:50" }, { "title": "Organize chats", "body": "# List folders\nmcporter call telebiz.listFolders\n\n# Add chats to folder\nmcporter call telebiz.batchAddToFolder chatIds='[\"-1001234\",\"-1001235\"]' folderId:5" }, { "title": "Rate Limiting", "body": "The browser enforces rate limits to prevent Telegram flood protection:\n\nMax calls per request: 20\nMax calls per minute: 30\nMin delay between calls: 500ms\nDelay for heavy operations (send/forward/delete): 1s\n\n(These values come from the Telebiz UI and are the effective limits we observed in practice.)" }, { "title": "batchAddToFolder fails for multiple chatIds", "body": "Observed behavior:\n\nbatchAddToFolder(folderId, chatIds=[one]) works (or reports alreadyIncluded)\nbatchAddToFolder(folderId, chatIds=[two or more]) fails with: \"Error: Failed to update folder\"\nRepro confirmed for both:\n\nAuto + another group\nAuto + a private chat\n\nWorkaround: loop sequentially:\n\naddChatToFolder(chatId=A, folderIds=[folderId])\naddChatToFolder(chatId=B, folderIds=[folderId])" }, { "title": "linkEntityToChat is unstable / schema mismatch", "body": "Observed behavior (Feb 2026):\n\nlinkEntityToChat returns \"Validation error\" for entityType=deal, contact, and company.\nIn one run, using entityType=\"organization\" successfully linked a HubSpot company to a chat — but later organization also returned \"Validation error\".\n\nImplication: this tool is either behind a feature flag, has changing server-side validation, or the published schema/enums don’t match what the backend expects.\n\nWorkaround:\n\nPrefer linking via createContact/createDeal/createCompany (these link to the chat at creation time).\nUse associateEntities to connect deal↔company/contact.\nDon’t depend on linkEntityToChat until upstream provides a stable contract + better error messages." }, { "title": "Relay not starting", "body": "# Check if port is in use\nss -tlnp | grep 9716\n\n# Kill existing process\npkill -f \"relay.js\"\n\n# Start fresh\n./start-relay.sh" }, { "title": "Browser not connecting", "body": "Verify relay is running: npm run health\nCheck browser console (F12) for WebSocket errors\nEnsure MCP is enabled in Settings → Agent → Enable MCP\nTry refreshing the telebiz-tt page" }, { "title": "\"Executor not connected\" error", "body": "The browser tab with telebiz-tt must be:\n\nOpen and visible (not suspended)\nLogged into Telegram\nMCP enabled in settings" }, { "title": "Rate limit errors", "body": "Reduce batch sizes\nAdd delays between operations\nBe more specific in filters to reduce API calls" }, { "title": "Session expired", "body": "If Telegram session expires:\n\nRefresh the telebiz-tt browser page\nRe-login if prompted\nRe-enable MCP in settings" }, { "title": "Environment Variables", "body": "VariableDefaultDescriptionTELEBIZ_PORT9716Relay WebSocket portTELEBIZ_RELAY_URLws://localhost:9716Relay URL for MCP serverTELEBIZ_STATE_FILE~/.telebiz-mcp-state.jsonMonitor state file" }, { "title": "mcporter Config", "body": "Located at ~/clawd/config/mcporter.json:\n\n{\n \"mcpServers\": {\n \"telebiz\": {\n \"url\": \"http://localhost:9718/mcp\"\n }\n }\n}\n\nNote: Use the HTTP URL (not stdio) to avoid spawning conflicts." }, { "title": "Security Notes", "body": "The browser holds your Telegram session - keep it secure\nDon't expose the relay port (9716) to the internet\nReview tool calls before executing destructive operations\nRate limits help prevent accidental spam" } ], "body": "telebiz-mcp\n\nMCP integration for Telegram via telebiz-tt browser client.\n\nQuick Rules (read this first)\nRate limits are strict: max 20 calls/request, 30 calls/min, 500ms between calls, heavy ops 1s.\nFor adding many chats to folders: do NOT use batchAddToFolder with multiple chatIds (known bug). Loop addChatToFolder sequentially.\nFor CRM linking: linkEntityToChat is unstable in our tests. We observed company failing with Validation error, and at one point organization succeeding — but later organization also failed. Treat linkEntityToChat as unreliable until upstream clarifies schema/feature flags.\nPrefer reversible operations and clean up test artifacts (folders, groups) immediately.\nArchitecture\n┌──────────────┐ ┌──────────────────┐ ┌─────────────────┐\n│ Clawdbot │────▶│ MCP Server │────▶│ WebSocket Relay │\n│ (mcporter) │ │ (stdio) │ │ (port 9716) │\n└──────────────┘ └──────────────────┘ └────────┬────────┘\n │\n ▼\n ┌─────────────────┐\n │ Browser │\n │ (telebiz-tt) │\n │ [executor] │\n └─────────────────┘\n\nQuick Setup\nPrerequisites\nNode.js 18+\nTelegram account\n1. Install telebiz-mcp\nnpm install -g @telebiz/telebiz-mcp\n\n2. Open Telebiz in browser\n\nGo to https://telebiz.io and login with your Telegram account.\n\n3. Start the HTTP server\ncd ~/clawd/skills/telebiz-mcp\n./start-http.sh\n\n\nThis starts a persistent server that:\n\nRuns telebiz-mcp internally\nKeeps browser connection alive\nExposes HTTP API on port 9718\n4. Enable MCP in Telebiz\n\nIn telebiz.io: Settings → Agent → Local MCP\n\nThe status should show \"Connected\" once the server is running.\n\n4. Verify connection\n# Quick health check\ncd ~/clawd/skills/telebiz-mcp\nnpm run health\n\n# Should show:\n# 📱 Telebiz MCP Status\n# ────────────────────\n# Relay: ✅ Running\n# Executor: ✅ Connected\n# Tools: 31 available\n\n5. Test via mcporter\ncd ~/clawd\nmcporter call telebiz.listChats limit:5\n\nHealth Monitoring\nManual Check\n# Check status\nnpm run health\n\n# JSON output for automation\nnode dist/health.js --json\n\nMonitor Script\n\nThe monitor tracks state changes and can be used with cron:\n\n# Check and alert on changes\nnpm run monitor\n\n# Quiet mode - only output on state change\nnode dist/monitor.js --quiet\n\n# JSON output\nnode dist/monitor.js --json\n\n\nExit codes:\n\n0 = Healthy (relay up, executor connected)\n1 = Degraded (relay up, executor disconnected)\n2 = Down (relay not running)\n3 = State changed (for alerting)\nCron Integration\n\nAdd to crontab for periodic monitoring:\n\n# Check every 5 minutes, alert on changes\n*/5 * * * * cd ~/clawd/skills/telebiz-mcp && node dist/monitor.js --quiet >> /var/log/telebiz-monitor.log 2>&1\n\nHeartbeat Integration\n\nAdd to HEARTBEAT.md for Clawdbot monitoring:\n\n### Telebiz MCP (every 2h)\n- [ ] Run: `cd ~/clawd/skills/telebiz-mcp && npm run health`\n- [ ] If degraded/down: Alert Albert via Telegram\n\nAvailable Tools\nChat Tools\nTool\tDescription\nlistChats\tList chats with filters (type, unread, archived, etc.)\ngetChatInfo\tGet detailed chat information\ngetCurrentChat\tGet currently open chat\nopenChat\tNavigate to a chat\narchiveChat\tArchive a chat\nunarchiveChat\tUnarchive a chat\npinChat\tPin a chat\nunpinChat\tUnpin a chat\nmuteChat\tMute notifications\nunmuteChat\tUnmute notifications\ndeleteChat\tDelete/leave chat ⚠️\nMessage Tools\nTool\tDescription\nsendMessage\tSend text message (markdown supported)\nforwardMessages\tForward messages between chats\ndeleteMessages\tDelete messages ⚠️\nsearchMessages\tSearch globally or in a chat\ngetRecentMessages\tGet message history\nmarkChatAsRead\tMark all messages as read\nFolder Tools\nTool\tDescription\nlistFolders\tList all chat folders\ncreateFolder\tCreate a new folder\naddChatToFolder\tAdd chat to folders\nremoveChatFromFolder\tRemove chat from folders\ndeleteFolder\tDelete a folder ⚠️\nMember Tools\nTool\tDescription\ngetChatMembers\tList group/channel members\naddChatMembers\tAdd users to group\nremoveChatMember\tRemove user from group\ncreateGroup\tCreate a new group\nUser Tools\nTool\tDescription\nsearchUsers\tSearch by name/username\ngetUserInfo\tGet user details\nBatch Tools\nTool\tDescription\nbatchSendMessage\tSend to multiple chats\nbatchAddToFolder\tAdd multiple chats to folder\nbatchArchive\tArchive multiple chats\nUsage Examples\nFind chats waiting for my reply\nmcporter call telebiz.listChats iAmLastSender=false hasUnread=true limit:20\n\nFind stale conversations I started\nmcporter call telebiz.listChats iAmLastSender=true lastMessageOlderThanDays:7 limit:20\n\nSearch all messages\nmcporter call telebiz.searchMessages query=\"invoice\" limit:20\n\nSearch in specific chat\nmcporter call telebiz.searchMessages query=\"meeting\" chatId=-1001234567890 limit:10\n\nSend message\nmcporter call telebiz.sendMessage chatId=-1001234567890 text=\"Hello from Clawdbot!\"\n\nGet recent messages\nmcporter call telebiz.getRecentMessages chatId=-1001234567890 limit:50\n\nPaginate through history\n# Page 1 (newest 50)\nmcporter call telebiz.getRecentMessages chatId=-1001234567890 limit:50 offset:0\n\n# Page 2 (messages 51-100)\nmcporter call telebiz.getRecentMessages chatId=-1001234567890 limit:50 offset:50\n\nOrganize chats\n# List folders\nmcporter call telebiz.listFolders\n\n# Add chats to folder\nmcporter call telebiz.batchAddToFolder chatIds='[\"-1001234\",\"-1001235\"]' folderId:5\n\nRate Limiting\n\nThe browser enforces rate limits to prevent Telegram flood protection:\n\nMax calls per request: 20\nMax calls per minute: 30\nMin delay between calls: 500ms\nDelay for heavy operations (send/forward/delete): 1s\n\n(These values come from the Telebiz UI and are the effective limits we observed in practice.)\n\nKnown Issues / Workarounds (Feb 2026)\nbatchAddToFolder fails for multiple chatIds\n\nObserved behavior:\n\nbatchAddToFolder(folderId, chatIds=[one]) works (or reports alreadyIncluded)\nbatchAddToFolder(folderId, chatIds=[two or more]) fails with: \"Error: Failed to update folder\"\nRepro confirmed for both:\nAuto + another group\nAuto + a private chat\n\nWorkaround: loop sequentially:\n\naddChatToFolder(chatId=A, folderIds=[folderId])\naddChatToFolder(chatId=B, folderIds=[folderId])\nlinkEntityToChat is unstable / schema mismatch\n\nObserved behavior (Feb 2026):\n\nlinkEntityToChat returns \"Validation error\" for entityType=deal, contact, and company.\nIn one run, using entityType=\"organization\" successfully linked a HubSpot company to a chat — but later organization also returned \"Validation error\".\n\nImplication: this tool is either behind a feature flag, has changing server-side validation, or the published schema/enums don’t match what the backend expects.\n\nWorkaround:\n\nPrefer linking via createContact/createDeal/createCompany (these link to the chat at creation time).\nUse associateEntities to connect deal↔company/contact.\nDon’t depend on linkEntityToChat until upstream provides a stable contract + better error messages.\nTroubleshooting\nRelay not starting\n# Check if port is in use\nss -tlnp | grep 9716\n\n# Kill existing process\npkill -f \"relay.js\"\n\n# Start fresh\n./start-relay.sh\n\nBrowser not connecting\nVerify relay is running: npm run health\nCheck browser console (F12) for WebSocket errors\nEnsure MCP is enabled in Settings → Agent → Enable MCP\nTry refreshing the telebiz-tt page\n\"Executor not connected\" error\n\nThe browser tab with telebiz-tt must be:\n\nOpen and visible (not suspended)\nLogged into Telegram\nMCP enabled in settings\nRate limit errors\nReduce batch sizes\nAdd delays between operations\nBe more specific in filters to reduce API calls\nSession expired\n\nIf Telegram session expires:\n\nRefresh the telebiz-tt browser page\nRe-login if prompted\nRe-enable MCP in settings\nConfiguration\nEnvironment Variables\nVariable\tDefault\tDescription\nTELEBIZ_PORT\t9716\tRelay WebSocket port\nTELEBIZ_RELAY_URL\tws://localhost:9716\tRelay URL for MCP server\nTELEBIZ_STATE_FILE\t~/.telebiz-mcp-state.json\tMonitor state file\nmcporter Config\n\nLocated at ~/clawd/config/mcporter.json:\n\n{\n \"mcpServers\": {\n \"telebiz\": {\n \"url\": \"http://localhost:9718/mcp\"\n }\n }\n}\n\n\nNote: Use the HTTP URL (not stdio) to avoid spawning conflicts.\n\nSecurity Notes\nThe browser holds your Telegram session - keep it secure\nDon't expose the relay port (9716) to the internet\nReview tool calls before executing destructive operations\nRate limits help prevent accidental spam" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/acastellana/telebiz-mcp-skill", "publisherUrl": "https://clawhub.ai/acastellana/telebiz-mcp-skill", "owner": "acastellana", "version": "0.1.0", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/telebiz-mcp-skill", "downloadUrl": "https://openagent3.xyz/downloads/telebiz-mcp-skill", "agentUrl": "https://openagent3.xyz/skills/telebiz-mcp-skill/agent", "manifestUrl": "https://openagent3.xyz/skills/telebiz-mcp-skill/agent.json", "briefUrl": "https://openagent3.xyz/skills/telebiz-mcp-skill/agent.md" } }