Telegram Bot API integration with managed authentication. Send messages, manage chats, handle updates, and interact with users through your Telegram bot. Use this skill when users want to send message
Real data. Real impact.
Emerging
Developers
Per week
Open source
Skills give you superpowers. Install in 30 seconds.
Access the Telegram Bot API with managed authentication. Send messages, photos, polls, locations, and more through your Telegram bot.
# Get bot info python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/telegram/:token/getMe') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF
https://gateway.maton.ai/telegram/:token/{method}
The
:token{method}sendMessagegetUpdatesAll requests require the Maton API key in the Authorization header:
Authorization: Bearer $MATON_API_KEY
Environment Variable: Set your API key as
MATON_API_KEYexport MATON_API_KEY="YOUR_API_KEY"
Manage your Telegram bot connections at
https://ctrl.maton.aipython <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=telegram&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF
python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'telegram'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF
python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF
Response:
{ "connection": { "connection_id": "e8f5078d-e507-4139-aabe-1615181ea8fc", "status": "ACTIVE", "creation_time": "2026-02-07T10:37:21.053942Z", "last_updated_time": "2026-02-07T10:37:59.881901Z", "url": "https://connect.maton.ai/?session_token=...", "app": "telegram", "metadata": {} } }
Open the returned
urlpython <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF
If you have multiple Telegram connections (multiple bots), specify which one to use with the
Maton-Connectionpython <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/telegram/:token/getMe') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', 'e8f5078d-e507-4139-aabe-1615181ea8fc') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF
If omitted, the gateway uses the default (oldest) active connection.
GET /telegram/:token/getMe
Returns information about the bot.
Response:
{ "ok": true, "result": { "id": 8523474253, "is_bot": true, "first_name": "Maton", "username": "maton_bot", "can_join_groups": true, "can_read_all_group_messages": true, "supports_inline_queries": true } }
POST /telegram/:token/getUpdates Content-Type: application/json{ "limit": 100, "timeout": 30, "offset": 625435210 }
| Parameter | Type | Required | Description |
|---|---|---|---|
| offset | Integer | No | First update ID to return |
| limit | Integer | No | Number of updates (1-100, default 100) |
| timeout | Integer | No | Long polling timeout in seconds |
| allowed_updates | Array | No | Update types to receive |
GET /telegram/:token/getWebhookInfo
POST /telegram/:token/setWebhook Content-Type: application/json{ "url": "https://example.com/webhook", "allowed_updates": ["message", "callback_query"], "secret_token": "your_secret_token" }
POST /telegram/:token/deleteWebhook Content-Type: application/json{ "drop_pending_updates": true }
POST /telegram/:token/sendMessage Content-Type: application/json{ "chat_id": 6442870329, "text": "Hello, World!", "parse_mode": "HTML" }
| Parameter | Type | Required | Description |
|---|---|---|---|
| chat_id | Integer/String | Yes | Target chat ID or @username |
| text | String | Yes | Message text (1-4096 characters) |
| parse_mode | String | No | |
| reply_markup | Object | No | Inline keyboard or reply keyboard |
| reply_parameters | Object | No | Reply to a specific message |
With HTML Formatting:
POST /telegram/:token/sendMessage Content-Type: application/json{ "chat_id": 6442870329, "text": "<b>Bold</b> and <i>italic</i> with <a href="https://example.com\">link</a>", "parse_mode": "HTML" }
With Inline Keyboard:
POST /telegram/:token/sendMessage Content-Type: application/json{ "chat_id": 6442870329, "text": "Choose an option:", "reply_markup": { "inline_keyboard": [ [ {"text": "Option 1", "callback_data": "opt1"}, {"text": "Option 2", "callback_data": "opt2"} ], [ {"text": "Visit Website", "url": "https://example.com"} ] ] } }
POST /telegram/:token/sendPhoto Content-Type: application/json{ "chat_id": 6442870329, "photo": "https://example.com/image.jpg", "caption": "Image caption" }
| Parameter | Type | Required | Description |
|---|---|---|---|
| chat_id | Integer/String | Yes | Target chat ID |
| photo | String | Yes | Photo URL or file_id |
| caption | String | No | Caption (0-1024 characters) |
| parse_mode | String | No | Caption parse mode |
POST /telegram/:token/sendDocument Content-Type: application/json{ "chat_id": 6442870329, "document": "https://example.com/file.pdf", "caption": "Document caption" }
POST /telegram/:token/sendVideo Content-Type: application/json{ "chat_id": 6442870329, "video": "https://example.com/video.mp4", "caption": "Video caption" }
POST /telegram/:token/sendAudio Content-Type: application/json{ "chat_id": 6442870329, "audio": "https://example.com/audio.mp3", "caption": "Audio caption" }
POST /telegram/:token/sendLocation Content-Type: application/json{ "chat_id": 6442870329, "latitude": 37.7749, "longitude": -122.4194 }
POST /telegram/:token/sendContact Content-Type: application/json{ "chat_id": 6442870329, "phone_number": "+1234567890", "first_name": "John", "last_name": "Doe" }
POST /telegram/:token/sendPoll Content-Type: application/json{ "chat_id": 6442870329, "question": "What is your favorite color?", "options": [ {"text": "Red"}, {"text": "Blue"}, {"text": "Green"} ], "is_anonymous": false }
| Parameter | Type | Required | Description |
|---|---|---|---|
| chat_id | Integer/String | Yes | Target chat ID |
| question | String | Yes | Poll question (1-300 characters) |
| options | Array | Yes | Poll options (2-10 items) |
| is_anonymous | Boolean | No | Anonymous poll (default true) |
| type | String | No | |
| allows_multiple_answers | Boolean | No | Allow multiple answers |
| correct_option_id | Integer | No | Correct answer for quiz |
POST /telegram/:token/sendDice Content-Type: application/json{ "chat_id": 6442870329, "emoji": "🎲" }
Supported emoji: 🎲 🎯 🎳 🏀 ⚽ 🎰
POST /telegram/:token/editMessageText Content-Type: application/json{ "chat_id": 6442870329, "message_id": 123, "text": "Updated message text" }
POST /telegram/:token/editMessageCaption Content-Type: application/json{ "chat_id": 6442870329, "message_id": 123, "caption": "Updated caption" }
POST /telegram/:token/editMessageReplyMarkup Content-Type: application/json{ "chat_id": 6442870329, "message_id": 123, "reply_markup": { "inline_keyboard": [ [{"text": "New Button", "callback_data": "new"}] ] } }
POST /telegram/:token/deleteMessage Content-Type: application/json{ "chat_id": 6442870329, "message_id": 123 }
POST /telegram/:token/forwardMessage Content-Type: application/json{ "chat_id": 6442870329, "from_chat_id": 6442870329, "message_id": 123 }
POST /telegram/:token/copyMessage Content-Type: application/json{ "chat_id": 6442870329, "from_chat_id": 6442870329, "message_id": 123 }
POST /telegram/:token/getChat Content-Type: application/json{ "chat_id": 6442870329 }
POST /telegram/:token/getChatAdministrators Content-Type: application/json{ "chat_id": -1001234567890 }
POST /telegram/:token/getChatMemberCount Content-Type: application/json{ "chat_id": -1001234567890 }
POST /telegram/:token/getChatMember Content-Type: application/json{ "chat_id": -1001234567890, "user_id": 6442870329 }
POST /telegram/:token/setMyCommands Content-Type: application/json{ "commands": [ {"command": "start", "description": "Start the bot"}, {"command": "help", "description": "Get help"}, {"command": "settings", "description": "Open settings"} ] }
GET /telegram/:token/getMyCommands
POST /telegram/:token/deleteMyCommands Content-Type: application/json{}
GET /telegram/:token/getMyDescription
POST /telegram/:token/setMyDescription Content-Type: application/json{ "description": "This bot helps you manage tasks." }
POST /telegram/:token/setMyName Content-Type: application/json{ "name": "Task Bot" }
POST /telegram/:token/getFile Content-Type: application/json{ "file_id": "AgACAgQAAxkDAAM..." }
Response:
{ "ok": true, "result": { "file_id": "AgACAgQAAxkDAAM...", "file_unique_id": "AQAD27ExGysnfVBy", "file_size": 7551, "file_path": "photos/file_0.jpg" } }
Download files from:
https://api.telegram.org/file/bot<token>/<file_path>POST /telegram/:token/answerCallbackQuery Content-Type: application/json{ "callback_query_id": "12345678901234567", "text": "Button clicked!", "show_alert": false }
// Send a message const response = await fetch( 'https://gateway.maton.ai/telegram/:token/sendMessage', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ chat_id: 6442870329, text: 'Hello from JavaScript!' }) } ); const data = await response.json(); console.log(data);
import os import requestsSend a message
response = requests.post( 'https://gateway.maton.ai/telegram/:token/sendMessage', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, json={ 'chat_id': 6442870329, 'text': 'Hello from Python!' } ) print(response.json())
import urllib.request, os, jsondata = json.dumps({ 'chat_id': 6442870329, 'text': 'Hello from Python!' }).encode() req = urllib.request.Request( 'https://gateway.maton.ai/telegram/:token/sendMessage', data=data, method='POST' ) req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') response = json.load(urllib.request.urlopen(req)) print(json.dumps(response, indent=2))
All Telegram Bot API responses follow this format:
Success:
{ "ok": true, "result": { ... } }
Error:
{ "ok": false, "error_code": 400, "description": "Bad Request: chat not found" }
:tokenjq$MATON_API_KEY| Status | Meaning |
|---|---|
| 400 | Missing Telegram connection or bad request |
| 401 | Invalid or missing Maton API key |
| 429 | Rate limited (Telegram limits vary by method) |
| 4xx/5xx | Passthrough error from Telegram Bot API |
MATON_API_KEYecho $MATON_API_KEY
python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF
telegramhttps://gateway.maton.ai/telegram/:token/sendMessagehttps://gateway.maton.ai/:token/sendMessageNo automatic installation available. Please visit the source repository for installation instructions.
View Installation Instructions
1,500+ AI skills, agents & workflows. Install in 30 seconds. Part of the Torly.ai family.
© 2026 Torly.ai. All rights reserved.