# Telegram MCP Serverless API - Documentation **Complete Developer Guide for Telegram Bot API with Model Context Protocol Integration** --- ## Table of Contents 1. [Quick Start Guide](#quick-start-guide) 2. [Authentication & Session Management](#authentication--session-management) 3. [API Endpoints](#api-endpoints) 4. [MCP Protocol Interface](#mcp-protocol-interface) 5. [Complete Tool Reference](#complete-tool-reference) 6. [Integration Patterns](#integration-patterns) 7. [Error Handling](#error-handling) 8. [Best Practices](#best-practices) --- ## Quick Start Guide ### Prerequisites **Required Credentials:** - **RapidAPI Key**: Get from your [RapidAPI Dashboard](https://rapidapi.com/developer/dashboard) - **Telegram Bot Token**: Create a bot via [@BotFather](https://t.me/botfather) ### Basic Integration (2 Steps) #### Step 1: Initialize MCP Session ```javascript const response = await fetch('https://telegram-mcp.p.rapidapi.com/config', { method: 'POST', headers: { 'X-RapidAPI-Key': 'your-rapidapi-key', 'X-Telegram-Bot-Token': 'your-telegram-bot-token', 'Content-Type': 'application/json' } }); const config = await response.json(); console.log('Session ID:', config.sessionId); console.log('Available tools:', config.tools.length); ``` **Response Format:** ```json { "sessionId": "sess_abc123def456", "tools": [ { "name": "telegram_send_message", "description": "Send a text message to a chat", "inputSchema": { ... } } ], "serverInfo": { "name": "telegram-mcp-serverless", "version": "1.0.0" } } ``` #### Step 2: Execute Telegram Operations Use your session ID to call any Telegram operation: ```javascript const result = await fetch('https://telegram-mcp.p.rapidapi.com/mcp', { method: 'POST', headers: { 'X-RapidAPI-Key': 'your-rapidapi-key', 'Mcp-Session-Id': config.sessionId, 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: "2.0", method: "tools/call", params: { name: "telegram_send_message", arguments: { chatId: "123456789", text: "Hello from Telegram MCP API! 🚀" } }, id: 1 }) }); const response = await result.json(); console.log('Message sent:', response.result); ``` ### Language Examples

Python

```python import requests import json # Step 1: Initialize session config_response = requests.post( 'https://telegram-mcp.p.rapidapi.com/config', headers={ 'X-RapidAPI-Key': 'your-rapidapi-key', 'X-Telegram-Bot-Token': 'your-telegram-bot-token', 'Content-Type': 'application/json' } ) config = config_response.json() session_id = config['sessionId'] # Step 2: Send message mcp_response = requests.post( 'https://telegram-mcp.p.rapidapi.com/mcp', headers={ 'X-RapidAPI-Key': 'your-rapidapi-key', 'Mcp-Session-Id': session_id, 'Content-Type': 'application/json' }, json={ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "telegram_send_message", "arguments": { "chatId": "123456789", "text": "Hello from Python! 🐍" } }, "id": 1 } ) result = mcp_response.json() print(f"Message sent: {result['result']}") ```

cURL

```bash # Step 1: Initialize session SESSION_RESPONSE=$(curl -s -X POST "https://telegram-mcp.p.rapidapi.com/config" \ -H "X-RapidAPI-Key: your-rapidapi-key" \ -H "X-Telegram-Bot-Token: your-telegram-bot-token" \ -H "Content-Type: application/json") SESSION_ID=$(echo $SESSION_RESPONSE | jq -r '.sessionId') # Step 2: Send message curl -X POST "https://telegram-mcp.p.rapidapi.com/mcp" \ -H "X-RapidAPI-Key: your-rapidapi-key" \ -H "Mcp-Session-Id: $SESSION_ID" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "telegram_send_message", "arguments": { "chatId": "123456789", "text": "Hello from cURL! 💻" } }, "id": 1 }' ```

Node.js

```javascript const axios = require('axios'); async function sendTelegramMessage() { try { // Step 1: Initialize session const configResponse = await axios.post( 'https://telegram-mcp.p.rapidapi.com/config', {}, { headers: { 'X-RapidAPI-Key': 'your-rapidapi-key', 'X-Telegram-Bot-Token': 'your-telegram-bot-token', 'Content-Type': 'application/json' } } ); const sessionId = configResponse.data.sessionId; // Step 2: Send message const mcpResponse = await axios.post( 'https://telegram-mcp.p.rapidapi.com/mcp', { jsonrpc: "2.0", method: "tools/call", params: { name: "telegram_send_message", arguments: { chatId: "123456789", text: "Hello from Node.js! 🟢" } }, id: 1 }, { headers: { 'X-RapidAPI-Key': 'your-rapidapi-key', 'Mcp-Session-Id': sessionId, 'Content-Type': 'application/json' } } ); console.log('Message sent:', mcpResponse.data.result); } catch (error) { console.error('Error:', error.response?.data || error.message); } } sendTelegramMessage(); ```

--- ## Authentication & Session Management ### Headers Required | Header | Required | Description | Example | |--------|----------|-------------|---------| | `X-RapidAPI-Key` | ✅ Always | Your RapidAPI subscription key | `abc123def456...` | | `X-Telegram-Bot-Token` | ✅ For `/config` | Bot token from @BotFather | `123456:ABC-DEF...` | | `Mcp-Session-Id` | ✅ For `/mcp` | Session ID from `/config` response | `sess_abc123...` | ### Session Lifecycle ```mermaid graph LR A[Call /config] --> B[Get Session ID] B --> C[Use Session ID for /mcp calls] C --> D[Session expires after 1 hour] D --> A ``` **Session Properties:** - **Duration**: 1 hour of inactivity - **Scope**: Single bot token per session - **Reuse**: Multiple operations with same session ID - **Security**: Cryptographically secure session generation --- ## API Endpoints ### Base URL ``` https://telegram-mcp.p.rapidapi.com ``` ### Available Endpoints | Endpoint | Method | Purpose | Authentication | |----------|--------|---------|----------------| | `/config` | POST | Initialize MCP session | RapidAPI Key + Bot Token | | `/mcp` | POST | Execute MCP protocol calls | RapidAPI Key + Session ID | | `/telegram` | POST | Direct REST API calls | RapidAPI Key + Bot Token | | `/health` | GET | Service health check | RapidAPI Key only | ### Endpoint Details #### 1. `/config` - Session Initialization **Purpose**: Create an MCP session and get available tools **Headers**: ``` X-RapidAPI-Key: your-rapidapi-key X-Telegram-Bot-Token: your-bot-token Content-Type: application/json ``` **Response**: ```json { "sessionId": "sess_abc123def456", "tools": [ { "name": "telegram_send_message", "description": "Send a text message to a chat", "inputSchema": { "type": "object", "properties": { "chatId": { "type": "string", "description": "Chat ID" }, "text": { "type": "string", "description": "Message text" } }, "required": ["chatId", "text"] } } ], "serverInfo": { "name": "telegram-mcp-serverless", "version": "1.0.0" } } ``` #### 2. `/mcp` - MCP Protocol Operations **Purpose**: Execute MCP protocol calls (tools/list, tools/call) **Headers**: ``` X-RapidAPI-Key: your-rapidapi-key Mcp-Session-Id: your-session-id Content-Type: application/json ``` **Request Body** (List Tools): ```json { "jsonrpc": "2.0", "method": "tools/list", "id": "list-1" } ``` **Request Body** (Call Tool): ```json { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "telegram_send_message", "arguments": { "chatId": "123456789", "text": "Hello, World!" } }, "id": "call-1" } ``` #### 3. `/telegram` - Direct REST API **Purpose**: Direct REST calls without MCP protocol wrapper **Headers**: ``` X-RapidAPI-Key: your-rapidapi-key X-Telegram-Bot-Token: your-bot-token Content-Type: application/json ``` **Request Body**: ```json { "type": "telegram_send_message", "chatId": "123456789", "text": "Hello from REST API!" } ``` #### 4. `/health` - Health Check **Purpose**: Check API service status **Headers**: ``` X-RapidAPI-Key: your-rapidapi-key ``` **Response**: ```json { "status": "healthy", "timestamp": "2024-01-15T10:30:00.000Z", "version": "1.0.0" } ``` --- ## MCP Protocol Interface ### Supported MCP Methods | Method | Purpose | Request Format | |--------|---------|----------------| | `tools/list` | Get available tools | `{"jsonrpc":"2.0","method":"tools/list","id":"1"}` | | `tools/call` | Execute a tool | `{"jsonrpc":"2.0","method":"tools/call","params":{...},"id":"1"}` | ### MCP Response Format **Success Response**: ```json { "jsonrpc": "2.0", "result": { "content": [ { "type": "text", "text": "Message sent successfully" } ], "isError": false }, "id": "call-1" } ``` **Error Response**: ```json { "jsonrpc": "2.0", "error": { "code": -1, "message": "Invalid chat ID", "data": { "details": "Chat ID must be a valid number or @username" } }, "id": "call-1" } ``` --- ## Complete Tool Reference ### 📬 Core Messaging Operations (6 tools) #### 1. Get Bot Information **Tool**: `telegram_get_bot_info` **Purpose**: Retrieve information about your bot ```json { "name": "telegram_get_bot_info", "arguments": {} } ``` **Response**: ```json { "id": 123456789, "is_bot": true, "first_name": "My Bot", "username": "my_awesome_bot", "can_join_groups": true, "can_read_all_group_messages": false, "supports_inline_queries": false } ``` #### 2. Send Message **Tool**: `telegram_send_message` **Purpose**: Send text messages with formatting options ```json { "name": "telegram_send_message", "arguments": { "chatId": "123456789", "text": "Hello! *Bold text* and _italic text_", "parseMode": "Markdown", "disableWebPagePreview": false, "disableNotification": false, "replyToMessageId": 42 } } ``` **Parameters**: - `chatId` (required): Chat ID or @username - `text` (required): Message text (1-4096 characters) - `parseMode`: "Markdown", "MarkdownV2", or "HTML" - `disableWebPagePreview`: Disable link previews - `disableNotification`: Send silently - `replyToMessageId`: Reply to specific message #### 3. Get Updates **Tool**: `telegram_get_updates` **Purpose**: Receive incoming messages and updates ```json { "name": "telegram_get_updates", "arguments": { "offset": 0, "limit": 100, "timeout": 0, "allowedUpdates": ["message", "edited_message", "callback_query"] } } ``` **Parameters**: - `offset`: Identifier of first update to be returned - `limit`: Limits number of updates (1-100, default 100) - `timeout`: Long polling timeout in seconds (0-50) - `allowedUpdates`: Array of update types to receive #### 4. Forward Message **Tool**: `telegram_forward_message` **Purpose**: Forward messages between chats ```json { "name": "telegram_forward_message", "arguments": { "chatId": "123456789", "fromChatId": "987654321", "messageId": 42, "disableNotification": false } } ``` #### 5. Edit Message Text **Tool**: `telegram_edit_message_text` **Purpose**: Edit existing text messages ```json { "name": "telegram_edit_message_text", "arguments": { "chatId": "123456789", "messageId": 42, "text": "Updated message content", "parseMode": "HTML" } } ``` #### 6. Delete Message **Tool**: `telegram_delete_message` **Purpose**: Delete messages from chats ```json { "name": "telegram_delete_message", "arguments": { "chatId": "123456789", "messageId": 42 } } ``` ### 🎨 Rich Media Operations (8 tools) #### 7. Send Photo **Tool**: `telegram_send_photo` **Purpose**: Send photos with optional captions ```json { "name": "telegram_send_photo", "arguments": { "chatId": "123456789", "photo": "https://example.com/photo.jpg", "caption": "Beautiful sunset! 🌅", "parseMode": "HTML", "disableNotification": false } } ``` **Photo Sources**: - HTTP URL to photo (must be publicly accessible) - Telegram file_id of existing photo - File upload (using multipart/form-data in direct API) #### 8. Send Document **Tool**: `telegram_send_document` **Purpose**: Send files and documents ```json { "name": "telegram_send_document", "arguments": { "chatId": "123456789", "document": "https://example.com/document.pdf", "caption": "Important document 📄", "disableContentTypeDetection": false } } ``` #### 9. Send Audio **Tool**: `telegram_send_audio` **Purpose**: Send audio files with metadata ```json { "name": "telegram_send_audio", "arguments": { "chatId": "123456789", "audio": "https://example.com/song.mp3", "caption": "Great song! 🎵", "duration": 180, "performer": "Artist Name", "title": "Song Title", "thumbnail": "https://example.com/thumbnail.jpg" } } ``` #### 10. Send Video **Tool**: `telegram_send_video` **Purpose**: Send video files ```json { "name": "telegram_send_video", "arguments": { "chatId": "123456789", "video": "https://example.com/video.mp4", "duration": 60, "width": 1920, "height": 1080, "caption": "Amazing video! 🎬", "supportsStreaming": true } } ``` #### 11. Send Animation **Tool**: `telegram_send_animation` **Purpose**: Send GIF animations ```json { "name": "telegram_send_animation", "arguments": { "chatId": "123456789", "animation": "https://example.com/funny.gif", "duration": 5, "width": 480, "height": 360, "caption": "Funny GIF! 😂" } } ``` #### 12. Send Video Note **Tool**: `telegram_send_video_note` **Purpose**: Send circular video messages ```json { "name": "telegram_send_video_note", "arguments": { "chatId": "123456789", "videoNote": "https://example.com/note.mp4", "duration": 30, "length": 240, "thumbnail": "https://example.com/thumb.jpg" } } ``` #### 13. Send Voice **Tool**: `telegram_send_voice` **Purpose**: Send voice messages ```json { "name": "telegram_send_voice", "arguments": { "chatId": "123456789", "voice": "https://example.com/voice.ogg", "caption": "Voice message 🎙️", "duration": 15 } } ``` #### 14. Send Sticker **Tool**: `telegram_send_sticker` **Purpose**: Send stickers ```json { "name": "telegram_send_sticker", "arguments": { "chatId": "123456789", "sticker": "CAACAgIAAxkBAAEBaaBhZ1234567890", "emoji": "😀" } } ``` ### 🎮 Interactive Elements (4 tools) #### 15. Send Poll **Tool**: `telegram_send_poll` **Purpose**: Create polls for user feedback ```json { "name": "telegram_send_poll", "arguments": { "chatId": "123456789", "question": "What's your favorite programming language?", "options": ["JavaScript", "Python", "Java", "Go", "Rust"], "isAnonymous": true, "type": "regular", "allowsMultipleAnswers": false, "openPeriod": 600 } } ``` **Poll Types**: - `regular`: Regular poll with multiple choice - `quiz`: Quiz with correct answer #### 16. Send Dice **Tool**: `telegram_send_dice` **Purpose**: Send animated dice and games ```json { "name": "telegram_send_dice", "arguments": { "chatId": "123456789", "emoji": "🎲" } } ``` **Available Dice Types**: - 🎲 (1-6 dice) - 🎯 (1-6 darts) - 🏀 (1-5 basketball) - ⚽ (1-5 football) - 🎳 (1-6 bowling) - 🎰 (1-64 slot machine) #### 17. Stop Poll **Tool**: `telegram_stop_poll` **Purpose**: Stop active polls ```json { "name": "telegram_stop_poll", "arguments": { "chatId": "123456789", "messageId": 42 } } ``` #### 18. Answer Callback Query **Tool**: `telegram_answer_callback_query` **Purpose**: Respond to inline keyboard button presses ```json { "name": "telegram_answer_callback_query", "arguments": { "callbackQueryId": "callback_query_id_123", "text": "Button clicked! ✅", "showAlert": false, "url": "https://example.com/page", "cacheTime": 0 } } ``` ### 📍 Location & Contact Services (3 tools) #### 19. Send Location **Tool**: `telegram_send_location` **Purpose**: Share geographic locations ```json { "name": "telegram_send_location", "arguments": { "chatId": "123456789", "latitude": 40.7128, "longitude": -74.0060, "horizontalAccuracy": 50.0, "livePeriod": 900, "heading": 45, "proximityAlertRadius": 100 } } ``` **Parameters**: - `latitude`, `longitude`: GPS coordinates - `horizontalAccuracy`: Location accuracy in meters - `livePeriod`: Live location update period (60-86400 seconds) - `heading`: Direction in degrees (1-360) - `proximityAlertRadius`: Alert when users get close (1-100000 meters) #### 20. Send Contact **Tool**: `telegram_send_contact` **Purpose**: Share contact information ```json { "name": "telegram_send_contact", "arguments": { "chatId": "123456789", "phoneNumber": "+1234567890", "firstName": "John", "lastName": "Doe", "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:John Doe\nORG:Example Corp\nEND:VCARD" } } ``` #### 21. Send Venue **Tool**: `telegram_send_venue` **Purpose**: Share venue information with location ```json { "name": "telegram_send_venue", "arguments": { "chatId": "123456789", "latitude": 40.7128, "longitude": -74.0060, "title": "Central Park", "address": "New York, NY 10022, USA", "foursquareId": "49da74aef964a5208b5e1fe3", "foursquareType": "parks_outdoors/park" } } ``` ### 👥 Chat & File Management (4 tools) #### 22. Get Chat **Tool**: `telegram_get_chat` **Purpose**: Get chat information and settings ```json { "name": "telegram_get_chat", "arguments": { "chatId": "123456789" } } ``` **Response** (Private Chat): ```json { "id": 123456789, "type": "private", "username": "john_doe", "first_name": "John", "last_name": "Doe" } ``` **Response** (Group Chat): ```json { "id": -123456789, "type": "group", "title": "My Awesome Group", "description": "A group for discussing awesome things", "all_members_are_administrators": false, "permissions": { ... } } ``` #### 23. Get Chat Member **Tool**: `telegram_get_chat_member` **Purpose**: Get information about a chat member ```json { "name": "telegram_get_chat_member", "arguments": { "chatId": "123456789", "userId": 987654321 } } ``` **Response**: ```json { "status": "member", "user": { "id": 987654321, "is_bot": false, "first_name": "Alice", "username": "alice_doe" }, "can_be_edited": false, "can_change_info": false, "can_delete_messages": false } ``` #### 24. Get Chat Member Count **Tool**: `telegram_get_chat_member_count` **Purpose**: Get the number of members in a chat ```json { "name": "telegram_get_chat_member_count", "arguments": { "chatId": "123456789" } } ``` **Response**: ```json { "result": 157 } ``` #### 25. Get File **Tool**: `telegram_get_file` **Purpose**: Get file information for downloads ```json { "name": "telegram_get_file", "arguments": { "fileId": "BAADBAADrwADBREAAeYMbgQWTKKyAg" } } ``` **Response**: ```json { "file_id": "BAADBAADrwADBREAAeYMbgQWTKKyAg", "file_unique_id": "AgADrwADBREAAQ", "file_size": 2048, "file_path": "documents/file_123.pdf" } ``` **Download URL Format**: ``` https://api.telegram.org/file/bot<token>/<file_path> ``` --- ## Integration Patterns ### Pattern 1: AI Assistant Integration **Use Case**: Add Telegram messaging to AI assistants ```javascript class TelegramAI { constructor(rapidApiKey, botToken) { this.rapidApiKey = rapidApiKey; this.botToken = botToken; this.sessionId = null; } async initialize() { const response = await fetch('https://telegram-mcp.p.rapidapi.com/config', { method: 'POST', headers: { 'X-RapidAPI-Key': this.rapidApiKey, 'X-Telegram-Bot-Token': this.botToken, 'Content-Type': 'application/json' } }); const config = await response.json(); this.sessionId = config.sessionId; return config.tools; } async sendMessage(chatId, text) { return await this.callTool('telegram_send_message', { chatId, text }); } async getUpdates() { return await this.callTool('telegram_get_updates', { timeout: 30, allowedUpdates: ['message'] }); } async callTool(toolName, arguments) { const response = await fetch('https://telegram-mcp.p.rapidapi.com/mcp', { method: 'POST', headers: { 'X-RapidAPI-Key': this.rapidApiKey, 'Mcp-Session-Id': this.sessionId, 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: "2.0", method: "tools/call", params: { name: toolName, arguments }, id: Date.now() }) }); return await response.json(); } } // Usage const ai = new TelegramAI('your-rapidapi-key', 'your-bot-token'); await ai.initialize(); await ai.sendMessage('123456789', 'Hello from AI! 🤖'); ``` ### Pattern 2: Automation Workflow **Use Case**: n8n/Make.com workflow integration ```javascript // Webhook handler for n8n async function handleWebhook(data) { // Initialize session const config = await initializeSession(); // Process workflow data if (data.trigger === 'order_completed') { await sendOrderConfirmation(config.sessionId, data.userId, data.order); } else if (data.trigger === 'support_ticket') { await notifySupport(config.sessionId, data.ticket); } } async function sendOrderConfirmation(sessionId, userId, order) { const message = ` 🎉 Order Confirmed! Order #${order.id} Total: $${order.total} Items: ${order.items.length} Thank you for your purchase! `; await callMCPTool(sessionId, 'telegram_send_message', { chatId: userId, text: message }); } ``` ### Pattern 3: No-Code Integration **Use Case**: Bubble.io or similar platforms ```javascript // Bubble.io custom code block async function sendTelegramNotification(chatId, message) { try { // Step 1: Get session const configResponse = await fetch('https://telegram-mcp.p.rapidapi.com/config', { method: 'POST', headers: { 'X-RapidAPI-Key': bubble.api_key, 'X-Telegram-Bot-Token': bubble.bot_token, 'Content-Type': 'application/json' } }); const config = await configResponse.json(); // Step 2: Send message const messageResponse = await fetch('https://telegram-mcp.p.rapidapi.com/mcp', { method: 'POST', headers: { 'X-RapidAPI-Key': bubble.api_key, 'Mcp-Session-Id': config.sessionId, 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: "2.0", method: "tools/call", params: { name: "telegram_send_message", arguments: { chatId, text: message } }, id: 1 }) }); return await messageResponse.json(); } catch (error) { console.error('Telegram notification failed:', error); return { success: false, error: error.message }; } } ``` ### Pattern 4: Real-time Chat Bot **Use Case**: Customer support or interactive bot ```javascript class TelegramBot { constructor(rapidApiKey, botToken) { this.rapidApiKey = rapidApiKey; this.botToken = botToken; this.sessionId = null; this.isRunning = false; this.lastUpdateId = 0; } async start() { await this.initialize(); this.isRunning = true; this.poll(); } async initialize() { const response = await fetch('https://telegram-mcp.p.rapidapi.com/config', { method: 'POST', headers: { 'X-RapidAPI-Key': this.rapidApiKey, 'X-Telegram-Bot-Token': this.botToken, 'Content-Type': 'application/json' } }); const config = await response.json(); this.sessionId = config.sessionId; } async poll() { while (this.isRunning) { try { const updates = await this.getUpdates(); if (updates.result && updates.result.length > 0) { for (const update of updates.result) { await this.handleUpdate(update); this.lastUpdateId = update.update_id + 1; } } } catch (error) { console.error('Polling error:', error); await new Promise(resolve => setTimeout(resolve, 5000)); } } } async getUpdates() { const response = await fetch('https://telegram-mcp.p.rapidapi.com/mcp', { method: 'POST', headers: { 'X-RapidAPI-Key': this.rapidApiKey, 'Mcp-Session-Id': this.sessionId, 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: "2.0", method: "tools/call", params: { name: "telegram_get_updates", arguments: { offset: this.lastUpdateId, timeout: 30 } }, id: Date.now() }) }); return await response.json(); } async handleUpdate(update) { if (update.message) { const message = update.message; const chatId = message.chat.id; const text = message.text; // Simple command handling if (text === '/start') { await this.sendMessage(chatId, 'Welcome! How can I help you?'); } else if (text === '/help') { await this.sendMessage(chatId, 'Available commands:\n/start - Start conversation\n/help - Show this help'); } else { // Echo the message await this.sendMessage(chatId, `You said: ${text}`); } } } async sendMessage(chatId, text) { const response = await fetch('https://telegram-mcp.p.rapidapi.com/mcp', { method: 'POST', headers: { 'X-RapidAPI-Key': this.rapidApiKey, 'Mcp-Session-Id': this.sessionId, 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: "2.0", method: "tools/call", params: { name: "telegram_send_message", arguments: { chatId: chatId.toString(), text } }, id: Date.now() }) }); return await response.json(); } stop() { this.isRunning = false; } } // Usage const bot = new TelegramBot('your-rapidapi-key', 'your-bot-token'); bot.start(); ``` --- ## Error Handling ### Common Error Scenarios #### 1. Authentication Errors **Invalid RapidAPI Key**: ```json { "message": "You are not subscribed to this API.", "status": 403 } ``` **Invalid Bot Token**: ```json { "jsonrpc": "2.0", "error": { "code": -1, "message": "Unauthorized: Invalid bot token", "data": { "telegram_error_code": 401 } } } ``` **Session Expired**: ```json { "jsonrpc": "2.0", "error": { "code": -2, "message": "Session not found or expired", "data": { "details": "Please create a new session using /config endpoint" } } } ``` #### 2. Parameter Errors **Invalid Chat ID**: ```json { "jsonrpc": "2.0", "error": { "code": -1, "message": "Bad Request: chat not found", "data": { "telegram_error_code": 400, "parameter": "chat_id" } } } ``` **Message Too Long**: ```json { "jsonrpc": "2.0", "error": { "code": -1, "message": "Bad Request: message is too long", "data": { "telegram_error_code": 400, "max_length": 4096, "current_length": 5000 } } } ``` #### 3. Rate Limit Errors **Too Many Requests**: ```json { "jsonrpc": "2.0", "error": { "code": -1, "message": "Too Many Requests: retry after 30", "data": { "telegram_error_code": 429, "retry_after": 30 } } } ``` ### Error Handling Best Practices ```javascript async function robustTelegramCall(sessionId, toolName, arguments) { const maxRetries = 3; let attempt = 0; while (attempt < maxRetries) { try { const response = await fetch('https://telegram-mcp.p.rapidapi.com/mcp', { method: 'POST', headers: { 'X-RapidAPI-Key': rapidApiKey, 'Mcp-Session-Id': sessionId, 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: "2.0", method: "tools/call", params: { name: toolName, arguments }, id: Date.now() }) }); const result = await response.json(); if (result.error) { // Handle specific errors if (result.error.code === -2) { // Session expired - reinitialize sessionId = await reinitializeSession(); attempt++; continue; } else if (result.error.data?.telegram_error_code === 429) { // Rate limit - wait and retry const retryAfter = result.error.data.retry_after || 30; await new Promise(resolve => setTimeout(resolve, retryAfter * 1000)); attempt++; continue; } else { // Other errors - don't retry throw new Error(`Telegram API error: ${result.error.message}`); } } return result; } catch (error) { attempt++; if (attempt >= maxRetries) { throw error; } // Exponential backoff await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000) ); } } } ``` --- ## Best Practices ### 1. Session Management **✅ Good Practices**: - Store session IDs securely - Implement session refresh logic - Handle session expiration gracefully - Reuse sessions for multiple operations **❌ Avoid**: - Creating new sessions for each request - Storing session IDs in client-side code - Ignoring session expiration errors ```javascript class SessionManager { constructor(rapidApiKey, botToken) { this.rapidApiKey = rapidApiKey; this.botToken = botToken; this.sessionId = null; this.sessionExpiry = null; } async getValidSession() { if (!this.sessionId || this.isSessionExpired()) { await this.createNewSession(); } return this.sessionId; } isSessionExpired() { return this.sessionExpiry && Date.now() > this.sessionExpiry; } async createNewSession() { const response = await fetch('https://telegram-mcp.p.rapidapi.com/config', { method: 'POST', headers: { 'X-RapidAPI-Key': this.rapidApiKey, 'X-Telegram-Bot-Token': this.botToken, 'Content-Type': 'application/json' } }); const config = await response.json(); this.sessionId = config.sessionId; this.sessionExpiry = Date.now() + (55 * 60 * 1000); // 55 minutes } } ``` ### 2. Rate Limiting **Telegram Rate Limits**: - Same chat: 1 message/second - Different chats: 30 messages/second - Group chats: 20 messages/minute **Implementation**: ```javascript class RateLimiter { constructor() { this.chatQueues = new Map(); this.globalQueue = []; this.globalLimit = 30; // messages per second this.chatLimit = 1; // message per second per chat } async sendMessage(chatId, text) { await this.waitForGlobalLimit(); await this.waitForChatLimit(chatId); return await this.actualSendMessage(chatId, text); } async waitForGlobalLimit() { const now = Date.now(); this.globalQueue = this.globalQueue.filter(time => now - time < 1000); if (this.globalQueue.length >= this.globalLimit) { const waitTime = 1000 - (now - this.globalQueue[0]); await new Promise(resolve => setTimeout(resolve, waitTime)); } this.globalQueue.push(now); } async waitForChatLimit(chatId) { const now = Date.now(); const lastSent = this.chatQueues.get(chatId) || 0; if (now - lastSent < 1000) { const waitTime = 1000 - (now - lastSent); await new Promise(resolve => setTimeout(resolve, waitTime)); } this.chatQueues.set(chatId, Date.now()); } } ``` ### 3. Input Validation **Message Text Validation**: ```javascript function validateMessageText(text) { if (!text || typeof text !== 'string') { throw new Error('Message text must be a non-empty string'); } if (text.length > 4096) { throw new Error(`Message too long: ${text.length}/4096 characters`); } return text.trim(); } function validateChatId(chatId) { if (!chatId) { throw new Error('Chat ID is required'); } // Can be a number or string starting with @ if (typeof chatId === 'number') { return chatId.toString(); } if (typeof chatId === 'string') { if (chatId.startsWith('@') || /^-?\d+$/.test(chatId)) { return chatId; } } throw new Error('Invalid chat ID format'); } ``` ### 4. Error Recovery **Automatic Retry Logic**: ```javascript async function withRetry(operation, maxRetries = 3) { for (let attempt = 1; attempt <= maxRetries; attempt++) { try { return await operation(); } catch (error) { if (attempt === maxRetries) { throw error; } // Check if error is retryable if (isRetryableError(error)) { const delay = Math.min(1000 * Math.pow(2, attempt - 1), 10000); await new Promise(resolve => setTimeout(resolve, delay)); } else { throw error; } } } } function isRetryableError(error) { const retryableErrors = [ 'Network error', 'Timeout', 'Too Many Requests', 'Internal Server Error' ]; return retryableErrors.some(msg => error.message.includes(msg) ); } ``` ### 5. Security Considerations **✅ Security Best Practices**: 1. **Never expose credentials in client-side code**: ```javascript // ❌ NEVER do this in frontend JavaScript const botToken = "123456:ABC-DEF..."; // Visible to everyone! // ✅ Use environment variables on server const botToken = process.env.TELEGRAM_BOT_TOKEN; ``` 2. **Validate all inputs**: ```javascript function sanitizeInput(input) { if (typeof input !== 'string') { throw new Error('Input must be a string'); } // Remove potential XSS attempts return input .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '') .replace(/javascript:/gi, '') .trim(); } ``` 3. **Use HTTPS only**: ```javascript // ✅ Always use HTTPS const baseUrl = 'https://telegram-mcp.p.rapidapi.com'; // ❌ Never use HTTP for API calls // const baseUrl = 'http://telegram-mcp.p.rapidapi.com'; ``` 4. **Implement request signing for sensitive operations**: ```javascript const crypto = require('crypto'); function signRequest(data, secret) { return crypto .createHmac('sha256', secret) .update(JSON.stringify(data)) .digest('hex'); } function verifySignature(data, signature, secret) { const expectedSignature = signRequest(data, secret); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expectedSignature) ); } ``` ### 6. Performance Optimization **Batch Operations**: ```javascript async function sendBulkMessages(messages) { const sessionId = await sessionManager.getValidSession(); // Group messages by chat to respect rate limits const messageGroups = groupMessagesByChat(messages); const results = []; for (const [chatId, chatMessages] of messageGroups) { for (const message of chatMessages) { await rateLimiter.waitForChatLimit(chatId); const result = await sendMessage(sessionId, chatId, message); results.push(result); } } return results; } function groupMessagesByChat(messages) { const groups = new Map(); for (const message of messages) { if (!groups.has(message.chatId)) { groups.set(message.chatId, []); } groups.get(message.chatId).push(message.text); } return groups; } ``` **Connection Pooling**: ```javascript class ConnectionPool { constructor(maxConnections = 10) { this.maxConnections = maxConnections; this.activeConnections = 0; this.queue = []; } async acquire() { return new Promise((resolve) => { if (this.activeConnections < this.maxConnections) { this.activeConnections++; resolve(); } else { this.queue.push(resolve); } }); } release() { this.activeConnections--; if (this.queue.length > 0) { const next = this.queue.shift(); this.activeConnections++; next(); } } } const pool = new ConnectionPool(5); async function apiCall(endpoint, data) { await pool.acquire(); try { return await fetch(endpoint, data); } finally { pool.release(); } } ``` --- ## Troubleshooting Guide ### Common Issues and Solutions #### Issue: "Session not found or expired" **Solution**: Recreate the session ```javascript if (error.code === -2) { sessionId = await createNewSession(); // Retry the operation } ``` #### Issue: "Chat not found" **Solution**: Verify chat ID format ```javascript // Ensure chat ID is properly formatted const chatId = typeof id === 'number' ? id.toString() : id; ``` #### Issue: "Message too long" **Solution**: Split long messages ```javascript function splitLongMessage(text, maxLength = 4096) { if (text.length <= maxLength) { return [text]; } const chunks = []; for (let i = 0; i < text.length; i += maxLength) { chunks.push(text.substring(i, i + maxLength)); } return chunks; } ``` #### Issue: Rate limiting **Solution**: Implement exponential backoff ```javascript async function handleRateLimit(retryAfter) { const delay = Math.max(retryAfter * 1000, 1000); await new Promise(resolve => setTimeout(resolve, delay)); } ``` ### Getting Help 1. **Check error messages**: Error responses include specific guidance 2. **Review parameter formats**: Ensure all required parameters are provided 3. **Verify authentication**: Check RapidAPI key and bot token validity 4. **Test with simple operations**: Start with basic tools like `telegram_get_bot_info` 5. **Monitor rate limits**: Implement proper throttling for high-volume usage For additional support, contact RapidAPI support through the marketplace.