终极入门教程：使用python-telegram开发Telegram机器人的完整步骤

郎沙圣Sebastian

399人浏览 · 2026-07-27 08:26:11

郎沙圣Sebastian · 2026-07-27 08:26:11 发布

终极入门教程：使用python-telegram开发Telegram机器人的完整步骤

【免费下载链接】python-telegram Python client for the Telegram's tdlib 项目地址: https://gitcode.com/gh_mirrors/py/python-telegram

python-telegram是一个基于tdlib库的Python客户端，它帮助开发者构建自己的Telegram客户端，通过MTProto协议与Telegram通信，支持以手机号登录完整账号或使用bot_token登录机器人账号。本教程将带你快速掌握使用python-telegram开发Telegram机器人的核心步骤，从环境搭建到功能实现，让你轻松开启Telegram机器人开发之旅。

准备工作：环境与账号配置

安装python-telegram库

python-telegram支持Python 3.10+及Linux、MacOS系统，Windows暂不支持。通过pip即可完成安装：

pip install python-telegram

获取Telegram API凭证

访问my.telegram.org/apps注册新应用
记录生成的api_id和api_hash（开发必备）

tdlib库配置

python-telegram提供预编译的tdlib库，但建议自行编译以确保兼容性：

系统级安装后可自动识别
自定义路径需在初始化时指定：

tg = Telegram(
    # 其他参数...
    library_path="/usr/local/lib/libtdjson.so",  # Linux示例
)

快速上手：创建第一个机器人

初始化客户端

使用获取的API凭证初始化Telegram客户端，支持普通账号或机器人账号登录：

from telegram.client import Telegram

tg = Telegram(
    api_id=123456,  # 替换为你的api_id
    api_hash="your_api_hash",  # 替换为你的api_hash
    phone="+31611111111",  # 普通账号登录（手机号）
    # bot_token="your_bot_token",  # 机器人账号登录（二选一）
    database_encryption_key="changeme1234",
    files_directory="/tmp/telegram_bot_data/",  # 数据存储目录
)

登录验证

调用login()方法完成登录，首次登录需验证：

tg.login()
# 程序将提示输入Telegram发送的验证码
# 若启用两步验证，还需输入密码

核心功能实现：构建回声机器人

消息处理机制

通过添加消息处理器监听并响应消息：

def new_message_handler(update):
    # 提取消息内容与元数据
    message_content = update['message']['content'].get('text', {})
    message_text = message_content.get('text', '').lower()
    is_outgoing = update['message']['is_outgoing']
    
    # 仅响应非自己发送的"ping"消息
    if not is_outgoing and message_text == 'ping':
        chat_id = update['message']['chat_id']
        tg.send_message(chat_id=chat_id, text='pong')  # 发送回复

# 注册消息处理器
tg.add_message_handler(new_message_handler)

启动机器人

使用idle()方法阻塞程序并等待消息：

tg.idle()  # 保持运行直到接收停止信号(CTRL+C)

完整代码示例

from telegram.client import Telegram

# 初始化客户端
tg = Telegram(
    api_id=123456,
    api_hash="your_api_hash",
    phone="+31611111111",
    database_encryption_key="changeme1234",
)
tg.login()

# 消息处理函数
def new_message_handler(update):
    message_content = update['message']['content'].get('text', {})
    message_text = message_content.get('text', '').lower()
    is_outgoing = update['message']['is_outgoing']
    
    if not is_outgoing and message_text == 'ping':
        chat_id = update['message']['chat_id']
        tg.send_message(chat_id=chat_id, text='pong')

# 注册处理器并启动
tg.add_message_handler(new_message_handler)
tg.idle()

进阶操作：Docker部署与示例扩展

Docker快速部署

项目提供官方Docker镜像，简化部署流程：

docker run -i -t --rm \
    -v /tmp/docker-python-telegram/:/tmp/ \
    akhmetov/python-telegram \
    python3 /app/examples/send_message.py $API_ID $API_HASH $PHONE $CHAT_ID $TEXT