# Send Telebiz Mcp to your agent Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually. ## Fast path - 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. ## Suggested prompts ### New install ```text 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. ``` ### Upgrade existing ```text 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. ``` ## Machine-readable fields ```json { "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": { "downloadUrl": "/downloads/telebiz-mcp-skill", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=telebiz-mcp-skill", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "SKILL.md", "dist/daemon.d.ts", "dist/daemon.js", "dist/health.d.ts", "dist/health.js", "dist/http-server.d.ts" ], "downloadMode": "redirect", "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." ] } }, "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" } } ``` ## Documentation ### telebiz-mcp MCP integration for Telegram via telebiz-tt browser client. ### Quick Rules (read this first) Rate limits are strict: max 20 calls/request, 30 calls/min, 500ms between calls, heavy ops 1s. For adding many chats to folders: do NOT use batchAddToFolder with multiple chatIds (known bug). Loop addChatToFolder sequentially. For 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. Prefer reversible operations and clean up test artifacts (folders, groups) immediately. ### Architecture ┌──────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Clawdbot │────▶│ MCP Server │────▶│ WebSocket Relay │ │ (mcporter) │ │ (stdio) │ │ (port 9716) │ └──────────────┘ └──────────────────┘ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Browser │ │ (telebiz-tt) │ │ [executor] │ └─────────────────┘ ### Prerequisites Node.js 18+ Telegram account ### 1. Install telebiz-mcp npm install -g @telebiz/telebiz-mcp ### 2. Open Telebiz in browser Go to https://telebiz.io and login with your Telegram account. ### 3. Start the HTTP server cd ~/clawd/skills/telebiz-mcp ./start-http.sh This starts a persistent server that: Runs telebiz-mcp internally Keeps browser connection alive Exposes HTTP API on port 9718 ### 4. Enable MCP in Telebiz In telebiz.io: Settings → Agent → Local MCP The status should show "Connected" once the server is running. ### 4. Verify connection # Quick health check cd ~/clawd/skills/telebiz-mcp npm run health # Should show: # 📱 Telebiz MCP Status # ──────────────────── # Relay: ✅ Running # Executor: ✅ Connected # Tools: 31 available ### 5. Test via mcporter cd ~/clawd mcporter call telebiz.listChats limit:5 ### Manual Check # Check status npm run health # JSON output for automation node dist/health.js --json ### Monitor Script The monitor tracks state changes and can be used with cron: # Check and alert on changes npm run monitor # Quiet mode - only output on state change node dist/monitor.js --quiet # JSON output node dist/monitor.js --json Exit codes: 0 = Healthy (relay up, executor connected) 1 = Degraded (relay up, executor disconnected) 2 = Down (relay not running) 3 = State changed (for alerting) ### Cron Integration Add to crontab for periodic monitoring: # Check every 5 minutes, alert on changes */5 * * * * cd ~/clawd/skills/telebiz-mcp && node dist/monitor.js --quiet >> /var/log/telebiz-monitor.log 2>&1 ### Heartbeat Integration Add to HEARTBEAT.md for Clawdbot monitoring: ### Telebiz MCP (every 2h) - [ ] Run: \`cd ~/clawd/skills/telebiz-mcp && npm run health\` - [ ] If degraded/down: Alert Albert via Telegram ### Chat Tools 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 ⚠️ ### Message Tools ToolDescriptionsendMessageSend text message (markdown supported)forwardMessagesForward messages between chatsdeleteMessagesDelete messages ⚠️searchMessagesSearch globally or in a chatgetRecentMessagesGet message historymarkChatAsReadMark all messages as read ### Folder Tools ToolDescriptionlistFoldersList all chat folderscreateFolderCreate a new folderaddChatToFolderAdd chat to foldersremoveChatFromFolderRemove chat from foldersdeleteFolderDelete a folder ⚠️ ### Member Tools ToolDescriptiongetChatMembersList group/channel membersaddChatMembersAdd users to groupremoveChatMemberRemove user from groupcreateGroupCreate a new group ### User Tools ToolDescriptionsearchUsersSearch by name/usernamegetUserInfoGet user details ### Batch Tools ToolDescriptionbatchSendMessageSend to multiple chatsbatchAddToFolderAdd multiple chats to folderbatchArchiveArchive multiple chats ### Find chats waiting for my reply mcporter call telebiz.listChats iAmLastSender=false hasUnread=true limit:20 ### Find stale conversations I started mcporter call telebiz.listChats iAmLastSender=true lastMessageOlderThanDays:7 limit:20 ### Search all messages mcporter call telebiz.searchMessages query="invoice" limit:20 ### Search in specific chat mcporter call telebiz.searchMessages query="meeting" chatId=-1001234567890 limit:10 ### Send message mcporter call telebiz.sendMessage chatId=-1001234567890 text="Hello from Clawdbot!" ### Get recent messages mcporter call telebiz.getRecentMessages chatId=-1001234567890 limit:50 ### Paginate through history # Page 1 (newest 50) mcporter call telebiz.getRecentMessages chatId=-1001234567890 limit:50 offset:0 # Page 2 (messages 51-100) mcporter call telebiz.getRecentMessages chatId=-1001234567890 limit:50 offset:50 ### Organize chats # List folders mcporter call telebiz.listFolders # Add chats to folder mcporter call telebiz.batchAddToFolder chatIds='["-1001234","-1001235"]' folderId:5 ### Rate Limiting The browser enforces rate limits to prevent Telegram flood protection: Max calls per request: 20 Max calls per minute: 30 Min delay between calls: 500ms Delay for heavy operations (send/forward/delete): 1s (These values come from the Telebiz UI and are the effective limits we observed in practice.) ### batchAddToFolder fails for multiple chatIds Observed behavior: batchAddToFolder(folderId, chatIds=[one]) works (or reports alreadyIncluded) batchAddToFolder(folderId, chatIds=[two or more]) fails with: "Error: Failed to update folder" Repro confirmed for both: Auto + another group Auto + a private chat Workaround: loop sequentially: addChatToFolder(chatId=A, folderIds=[folderId]) addChatToFolder(chatId=B, folderIds=[folderId]) ### linkEntityToChat is unstable / schema mismatch Observed behavior (Feb 2026): linkEntityToChat returns "Validation error" for entityType=deal, contact, and company. In one run, using entityType="organization" successfully linked a HubSpot company to a chat — but later organization also returned "Validation error". Implication: 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. Workaround: Prefer linking via createContact/createDeal/createCompany (these link to the chat at creation time). Use associateEntities to connect deal↔company/contact. Don’t depend on linkEntityToChat until upstream provides a stable contract + better error messages. ### Relay not starting # Check if port is in use ss -tlnp | grep 9716 # Kill existing process pkill -f "relay.js" # Start fresh ./start-relay.sh ### Browser not connecting Verify relay is running: npm run health Check browser console (F12) for WebSocket errors Ensure MCP is enabled in Settings → Agent → Enable MCP Try refreshing the telebiz-tt page ### "Executor not connected" error The browser tab with telebiz-tt must be: Open and visible (not suspended) Logged into Telegram MCP enabled in settings ### Rate limit errors Reduce batch sizes Add delays between operations Be more specific in filters to reduce API calls ### Session expired If Telegram session expires: Refresh the telebiz-tt browser page Re-login if prompted Re-enable MCP in settings ### Environment Variables VariableDefaultDescriptionTELEBIZ_PORT9716Relay WebSocket portTELEBIZ_RELAY_URLws://localhost:9716Relay URL for MCP serverTELEBIZ_STATE_FILE~/.telebiz-mcp-state.jsonMonitor state file ### mcporter Config Located at ~/clawd/config/mcporter.json: { "mcpServers": { "telebiz": { "url": "http://localhost:9718/mcp" } } } Note: Use the HTTP URL (not stdio) to avoid spawning conflicts. ### Security Notes The browser holds your Telegram session - keep it secure Don't expose the relay port (9716) to the internet Review tool calls before executing destructive operations Rate limits help prevent accidental spam ## Trust - Source: tencent - Verification: Indexed source record - Publisher: acastellana - Version: 0.1.0 ## Source health - Status: healthy - Source download looks usable. - Yavira can redirect you to the upstream package for this source. - Health scope: source - Reason: direct_download_ok - Checked at: 2026-05-07T17:22:31.273Z - Expires at: 2026-05-14T17:22:31.273Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/telebiz-mcp-skill) - [Send to Agent page](https://openagent3.xyz/skills/telebiz-mcp-skill/agent) - [JSON manifest](https://openagent3.xyz/skills/telebiz-mcp-skill/agent.json) - [Markdown brief](https://openagent3.xyz/skills/telebiz-mcp-skill/agent.md) - [Download page](https://openagent3.xyz/downloads/telebiz-mcp-skill)