Telegram Bot技能使用说明

2026-03-27 新闻来源：网淘吧围观:22

电脑广告

手机广告

Telegram Bot API

通过托管的身份验证访问Telegram Bot API。通过您的Telegram机器人发送消息、照片、投票、位置等。

快速开始

# 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

基础URL

https://gateway.maton.ai/telegram/:token/{method}

占位符:token会自动替换为连接配置中的机器人令牌。将{method}替换为Telegram Bot API方法名称（例如，sendMessage、getUpdates）。

身份验证

所有请求都需要在Authorization头中包含Maton API密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：将您的API密钥设置为MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取您的API密钥

请登录或在maton.ai
前往maton.ai/settings
复制您的API密钥

连接管理

在以下地址管理您的Telegram机器人连接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))
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

响应：

{
  "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": {}
  }
}

在浏览器中打开返回的url以完成机器人令牌配置。

删除连接

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))
EOF

指定连接

如果您有多个Telegram连接（多个机器人），请使用Maton-Connection请求头来指定要使用哪一个：

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))
EOF

如果省略，网关将使用默认（最早创建的）活动连接。

API参考

机器人信息

获取机器人信息

GET /telegram/:token/getMe

返回关于机器人的信息。

响应：

{
  "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
}

参数	类型	必需	描述
offset	整数	否	要返回的第一个更新ID
limit	整数	否	更新数量（1-100，默认100）
timeout	整数	否	长轮询超时时间（秒）
allowed_updates	数组	否	要接收的更新类型

获取Webhook信息

GET /telegram/:token/getWebhookInfo

设置Webhook

POST /telegram/:token/setWebhook
Content-Type: application/json

{
  "url": "https://example.com/webhook",
  "allowed_updates": ["message", "callback_query"],
  "secret_token": "your_secret_token"
}

删除Webhook

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"
}

参数	类型	必需	描述
chat_id	整数/字符串	是	目标聊天ID或@用户名
text	字符串	是	消息文本（1-4096个字符）
parse_mode	字符串	否	HTML、Markdown或MarkdownV2
reply_markup	对象	否	内联键盘或回复键盘
reply_parameters	对象	否	回复特定消息

使用 HTML 格式：

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"
}

使用内联键盘：

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"
}

参数	类型	必需	描述
chat_id	整数/字符串	是	目标聊天 ID
photo	字符串	是	照片 URL 或 file_id
caption	字符串	否	标题（0-1024 个字符）
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
}

参数	类型	必需	描述
chat_id	整数/字符串	是	目标聊天ID
question	字符串	是	投票问题（1-300个字符）
options	数组	是	投票选项（2-10项）
is_anonymous	布尔值	否	匿名投票（默认值为真）
类型	字符串	否	常规或测验
允许多个答案	布尔值	否	允许多个答案
正确答案ID	整数	否	测验的正确答案

发送骰子

POST /telegram/:token/sendDice
Content-Type: application/json

{
  "chat_id": 6442870329,
  "emoji": "🎲"
}

支持的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..."
}

响应：

{
  "ok": true,
  "result": {
    "file_id": "AgACAgQAAxkDAAM...",
    "file_unique_id": "AQAD27ExGysnfVBy",
    "file_size": 7551,
    "file_path": "photos/file_0.jpg"
  }
}

从以下地址下载文件：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
}

代码示例

JavaScript

// 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);

Python

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())

Python (urllib)

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))

响应格式

所有Telegram Bot API的响应都遵循以下格式：

成功：

{
  "ok": true,
  "result": { ... }
}

错误：

{
  "ok": false,
  "error_code": 400,
  "description": "Bad Request: chat not found"
}

注意事项

:token会自动替换为连接中你的机器人令牌
私聊的聊天ID是整数，群组的聊天ID可能为负数
所有方法都支持GET和POST，但对于带参数的方法，建议使用POST
文本消息有4096个字符的限制
说明文字有1024个字符的限制
投票支持2到10个选项
文件上传需要multipart/form-data格式（为简便起见，可使用URL）
重要提示：当将curl输出传递给jq或其他命令时，在某些shell环境中，像$MATON_API_KEY这样的环境变量可能无法正确展开

错误处理

状态	含义
400	缺少Telegram连接或错误请求
401	Maton API密钥无效或缺失
429	请求频率受限（Telegram限制因方法而异）
4xx/5xx	来自Telegram Bot API的透传错误

故障排除：API密钥问题

检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

通过列出连接来验证API密钥是否有效：

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

故障排除：无效的应用名称

确保您的URL路径以telegram开头。例如：

正确示例：https://gateway.maton.ai/telegram/:token/sendMessage
错误示例：https://gateway.maton.ai/:token/sendMessage

资源

天猫隐藏优惠券

网淘吧

免责申明

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。

打赏

文章底部电脑广告

手机广告位-内容正文底部

标签

上一篇：Windows Control技能使用说明下一篇：Last 30 Days技能使用说明

Telegram Bot技能使用说明

Telegram Bot API

快速开始

基础URL

身份验证

获取您的API密钥

连接管理

列出连接

创建连接

获取连接

删除连接

指定连接

API参考

机器人信息

获取机器人信息

获取更新

获取更新（长轮询）

获取Webhook信息

设置Webhook

删除Webhook

发送消息

发送文本消息

发送照片

发送文档

发送视频

发送音频

发送位置

发送联系人

发送投票

发送骰子

编辑消息

编辑消息文本

编辑消息说明

编辑消息回复标记

删除消息

转发与复制

转发消息

复制消息

聊天信息

获取聊天

获取聊天管理员

获取聊天成员数量

获取聊天成员

机器人命令

设置我的命令

获取我的命令

删除我的命令

机器人资料

获取我的描述

设置我的描述

设置我的名称

文件

获取文件

回调查询

回复回调查询

代码示例

JavaScript

Python

Python (urllib)

响应格式

注意事项

错误处理

故障排除：API密钥问题

故障排除：无效的应用名称

资源

相关文章

推荐文章

热门浏览

标签列表