Telegram机器人将用户数据写入Google Sheets的方法

在日常运营和项目开发中，我们经常需要收集用户输入的信息，例如反馈、报名、订单等。手动整理这些数据既耗时又容易出错，而Telegram机器人可以自动接收消息，再配合Google Sheets的API，就能实现数据的实时同步，让每一份提交都自动落入电子表格，方便分析与协作。本文将从零开始，手把手教你配置Telegram机器人和Google Sheets，并编写代码实现数据的自动写入。

一、准备工作概览

在动手写代码之前，我们需要准备以下内容：

一个Telegram机器人Token（通过BotFather创建）
一个Google Cloud项目，并启用Google Sheets API
一个Google Sheets表格（用于接收数据）
Python 3.7+环境，以及相关依赖库

整个过程分为三步：先取得机器人Token，再配置Google Sheets的访问权限，最后编写Python脚本将两者连接起来。

二、获取Telegram机器人Token

首先，在Telegram中搜索@BotFather，发送/newbot，按照提示设置机器人名称和用户名。创建成功后，BotFather会返回一个HTTP API Token，形如123456789:ABCdefGhIJKlmNoPQRsTuvWxYz。保存好这个Token，后续代码中需要用到。

如果已有机器人，可以发送/token获取现有Token。

三、配置Google Sheets API与访问权限

要让程序操作Google Sheets，必须通过Google Cloud平台创建服务账号，并授权给目标表格。

创建项目并启用API：访问Google Cloud Console，新建项目（或选择现有项目）。在“API和服务”中点击“启用API和服务”，搜索并启用Google Sheets API。
创建服务账号：在“凭据”页面点击“创建凭据”，选择“服务账号”。填写名称后，点击“创建并继续”。在“角色”中可暂时不选，因为我们会单独授予表格权限。创建完成后，进入该服务账号，点击“添加密钥”选择“JSON”，下载密钥文件（如service_account.json）。
共享表格给服务账号：在Google Sheets中打开目标表格，点击右上角“共享”，将服务账号的邮箱（在服务账号详情中可见，形如xxx@xxx.iam.gserviceaccount.com）添加为“编辑者”。只有这样，程序才能写入数据。

请妥善保管下载的JSON密钥文件，切勿泄露到公共仓库。

四、编写Python代码

我们使用python-telegram-bot库处理Telegram消息，用gspread库操作Google Sheets。首先安装依赖：

pip install python-telegram-bot gspread oauth2client

然后创建Python文件，例如bot_to_sheets.py。下面是一个完整示例，机器人接收用户发来的文本消息，并将其作为一行数据写入Google Sheets。

import asyncio
from telegram.ext import Application, MessageHandler, filters
import gspread
from oauth2client.service_account import ServiceAccountCredentials

# ---------- Google Sheets 配置 ------------
SCOPE = ["https://spreadsheets.google.com/feeds", "https://www.googleapis.com/auth/drive"]
creds = ServiceAccountCredentials.from_json_keyfile_name("service_account.json", SCOPE)
client = gspread.authorize(creds)
# 请替换为你的表格名称或URL
sheet = client.open("用户数据收集").sheet1  # 默认第一个工作表

# ---------- Telegram 机器人处理函数 ----------
async def handle_message(update, context):
    """处理用户发来的文本消息，写入Google Sheets"""
    user = update.effective_user
    text = update.message.text

    # 将数据追加为一行：时间、用户名、用户ID、消息内容
    import datetime
    row = [datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
           user.full_name,
           user.id,
           text]
    try:
        sheet.append_row(row)
        await update.message.reply_text("✅ 已成功写入Google Sheets！")
    except Exception as e:
        await update.message.reply_text(f"❌ 写入失败：")

def main():
    # 请输入你的Bot Token
    app = Application.builder().token("YOUR_BOT_TOKEN").build()
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, handle_message))
    print("机器人已启动...")
    app.run_polling(allowed_updates=["message"])

if __name__ == "__main__":
    main()

代码说明：

ServiceAccountCredentials负责使用JSON密钥完成Google认证。
sheet.append_row()方法会在表格最后一行追加数据，每次用户发送消息就会新增一行。
我们使用了异步函数处理消息，这是python-telegram-bot v20+的推荐写法。
写入内容包含提交时间、用户全名、用户ID和消息文本，你可以根据实际需求自由调整。

五、运行与测试

将代码中的YOUR_BOT_TOKEN替换为真实的机器人Token。
确保service_account.json与Python脚本在同一目录，或者修改代码中的路径。
在终端运行python bot_to_sheets.py。
打开Telegram，找到你的机器人，发送任意文本消息。
稍等片刻，打开Google Sheets，即可看到新写入的行数据。

如果出现错误，请检查服务账号邮箱是否已正确添加为编辑者，以及JSON密钥是否有效。

六、进阶应用与注意事项

1. 写入特定工作表

如果你想写入指定的工作表（不是第一个），可以使用client.open("表格名").worksheet("工作表名")来选择。

2. 处理不同类型的数据

用户可以发送图片、文件等，这时需要先调用update.message.document或update.message.photo获取文件对象，再通过get_file方法下载到本地，然后将文件路径或元数据写入表格。但本文聚焦于文本数据，其他类型可自行扩展。

3. 错误处理与重试

网络波动或API限制可能导致写入失败。建议在代码中加入重试机制，例如使用tenacity库，或捕获异常后延迟2秒再尝试。

4. 数据安全与隐私

用户数据敏感，务必遵守相关隐私法规。在收集个人信息前需明确告知，并可提供清除数据的命令。服务账号密钥一定要保密，避免泄露在公开代码中。

七、总结

通过本文，你已经掌握了Telegram机器人接Google Sheets的核心方法。这一组合能轻松实现表单收集、自动备份、用户反馈聚合等场景。你只需要扩展消息处理函数，即可应对多样化的业务需求。未来还可以结合Google Forms、Apps Script等工具，打造更强大的自动化工作流。如果遇到问题，欢迎查阅官方文档或加入社区讨论。