telegram-apiTelegram 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 messages, create polls, manage bot commands, or interact with Telegram chats. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
Install via ClawdBot CLI:
clawdbot install byungkyu/telegram-apiAccess 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))
EOFhttps://gateway.maton.ai/telegram/:token/{method}The :token placeholder is automatically replaced with your bot token from the connection configuration. Replace {method} with the Telegram Bot API method name (e.g., sendMessage, getUpdates).
All requests require the Maton API key in the Authorization header:
Authorization: Bearer $MATON_API_KEYEnvironment Variable: Set your API key as MATON_API_KEY:
export MATON_API_KEY="YOUR_API_KEY"Manage your Telegram bot connections at https://ctrl.maton.ai.
python <<'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))
EOFpython <<'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))
EOFpython <<'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))
EOFResponse:
{
"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 url in a browser to complete the bot token configuration.
python <<'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))
EOFIf you have multiple Telegram connections (multiple bots), specify which one to use with the Maton-Connection header:
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"]}')
req.add_header('Maton-Connection', 'e8f5078d-e507-4139-aabe-1615181ea8fc')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFIf omitted, the gateway uses the default (oldest) active connection.
GET /telegram/:token/getMeReturns 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/getWebhookInfoPOST /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 | HTML, Markdown, or MarkdownV2 |
| 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 | regular or quiz |
| 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/getMyCommandsPOST /telegram/:token/deleteMyCommands
Content-Type: application/json
{}GET /telegram/:token/getMyDescriptionPOST /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
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 requests
# Send 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, json
data = 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"
}:token is automatically replaced with your bot token from the connectionjq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments| 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_KEY environment variable is set:echo $MATON_API_KEYpython <<'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))
EOFtelegram. For example:https://gateway.maton.ai/telegram/:token/sendMessagehttps://gateway.maton.ai/:token/sendMessageGenerated Mar 1, 2026
Businesses can use this skill to automate customer support via Telegram bots, handling common queries, sending automated responses, and escalating complex issues to human agents. It integrates with existing CRM systems to provide real-time updates and notifications to customers.
Media companies and content creators can leverage this skill to send newsletters, updates, and interactive polls to Telegram subscribers. It enables targeted messaging based on user preferences, increasing engagement and driving traffic to websites or apps.
Event organizers can use this skill to manage registrations, send reminders, and broadcast live updates to participants via Telegram. It supports sending photos and locations, making it ideal for conferences, workshops, and community events.
Companies can deploy Telegram bots for internal communication, automating task assignments, sending alerts, and facilitating group chats. It integrates with project management tools to streamline workflows and improve team collaboration.
Educational institutions and online learning platforms can use this skill to deliver course materials, quizzes, and feedback to students through Telegram. It supports interactive elements like polls and messages, enhancing remote learning experiences.
Offer this skill as part of a subscription-based service where businesses pay monthly or annually for access to Telegram bot automation. Revenue is generated through tiered pricing based on usage limits, features, and support levels.
Provide basic Telegram bot functionality for free to attract users, then charge for advanced features like analytics, custom integrations, or higher message limits. This model encourages adoption and upsells to paying customers.
License this skill to agencies or developers who rebrand and resell it as part of their own services. Revenue comes from licensing fees, setup charges, and ongoing maintenance contracts for customized bot solutions.
💬 Integration Tip
Ensure the MATON_API_KEY is securely stored as an environment variable and test connections via the control panel before deploying in production to avoid authentication issues.
iMessage/SMS CLI for listing chats, history, watch, and sending.
Use when you need to control Discord from Clawdbot via the discord tool: send messages, react, post or upload stickers, upload emojis, run polls, manage threads/pins/search, fetch permissions or member/role/channel info, or handle moderation actions in Discord DMs or channels.
Use when you need to control Slack from Clawdbot via the slack tool, including reacting to messages or pinning/unpinning items in Slack channels or DMs.
Send WhatsApp messages to other people or search/sync WhatsApp history via the wacli CLI (not for normal user chats).
Build or update the BlueBubbles external channel plugin for Clawdbot (extension package, REST send/probe, webhook inbound).
OpenClaw skill for designing Telegram Bot API workflows and command-driven conversations using direct HTTPS requests (no SDKs).