如何使用Telethon实现监听联系人加入Telegram的事件处理器

核心触发事件定位 #

Telegram客户端收到的“联系人加入Telegram”推送，对应原生更新类型为UpdateContactRegistered，Telethon已在底层支持对该类型更新的捕获，不需要手动轮询联系人列表匹配状态变化。

具体实现代码 #

• 实现逻辑需要借助Telethon的原始更新监听器，匹配指定的原生更新类型即可

from telethon import TelegramClient, events
from telethon.tl.types import UpdateContactRegistered

# 按Telethon常规配置初始化客户端
client = TelegramClient('your_session_name', api_id, api_hash)

@client.on(events.Raw(types=UpdateContactRegistered))
async def on_contact_registered(event):
    # 解析触发事件的用户实体
    target_user = await client.get_entity(event.user_id)
    # 在此处编写自定义业务逻辑，比如触发通知、记录日志等
    print(f"检测到联系人加入Telegram：{target_user.full_name}，用户ID：{target_user.id}")

if __name__ == '__main__':
    client.start()
    client.run_until_disconnected()

关键注意事项 #

• 事件触发范围和官方客户端的推送逻辑完全一致：只有已经存在于你联系人列表中的用户，在完成Telegram账号注册时才会触发该事件，非联系人的注册行为不会产生对应回调。
• 重点区分相似事件：events.NewMessage、events.UserUpdate等封装事件仅覆盖消息收发、用户基础资料变更等场景，不会标记“首次注册平台”的动作，不需要在这些事件的过滤规则上反复尝试匹配。
• 常见收不到事件的排查方向：
  • 确认客户端初始化时未手动关闭全量更新接收（该配置默认开启，只有手动设置receive_updates=False才会拦截所有非消息类更新）
  • 检查全局更新路由的过滤规则，避免过强的拦截逻辑把这类低优先级的更新请求提前阻断

内容的提问来源于stack exchange，提问作者Alex