导入与导出
Voxt 没有会生成或读取文件的“导出聊天”或“导入聊天”按钮。数据通过两种编程接口流动:
- 导出通过 MCP 或 RPC API 读取聊天的消息、附件、成员和摘要。
- 导入把来自其他服务的早期历史添加到聊天中。所有者启动导入模式,成员表示同意,然后消息通过 MCP 导入工具或 RPC API 的导入服务发送。在这两种方式中,所有者都可以通过助手运行整个过程。
导出聊天
导出需要 API 密钥或 OAuth 登录。助手或脚本以你的身份操作,因此它能读取的恰好是你能读取的聊天,不会更多。
- 创建 API 密钥,或按 MCP 中的说明用 OAuth 流程连接助手。
- 向你的助手提出导出请求,例如:“读取聊天 Trip photos 的所有消息,并保存为带有日期和作者的 Markdown 文件。”由助手选择工具;你不需要知道它们的名称。
- 对于脚本,直接调用这些工具。工具参考列出了它们及其参数。
可以读取的内容:
| 数据 | 工具 | 说明 |
|---|---|---|
| 消息 | list_messages、get_id_range | 从旧到新,每次调用最多 1,024 条消息。从最后一条消息的 ID 继续,直到不再返回内容。已删除的消息会被省略。 |
| 置顶消息和表情回应 | list_pinned_messages、list_reactions | |
| 照片、视频、文件和链接 | list_media、list_files、list_links | 按月分组,最新的月份在前。每个附件都带有内容 URL。 |
| 成员 | list_members、list_place_members | |
| 聊天和地点 | list_group_chats、list_peer_chats、list_places、list_place_chats、list_archived_chats、get_chat、get_place | 用它们找到要导出的内容。你归档的聊天只由 list_archived_chats 列出。 |
| 摘要 | list_conversations、get_conversation | 聊天中已总结的片段,例如一次语音会话。 |
| 搜索结果 | search_messages、search_contacts |
导出大型聊天之前需要了解:
- 这些工具返回的是分页内容,而不是文件。结果由助手或脚本组装。
- 仍在流式传输的消息还没有文字。请稍后再读取这一部分。
- 你已经读取过的消息的编辑和删除不会被报告。如果聊天仍然活跃,请重新读取该范围。
把历史导入聊天
使用导入模式,把另一个服务中的对话带入 Voxt 群聊或地点。消息以原作者和原日期保存,所以聊天看起来就像一直在 Voxt 中一样。
首先需要了解:
- 只有聊天或地点的所有者可以开始和结束导入。
- 它适用于群聊和地点。整个地点的导入涵盖该地点的每个聊天。不能向私聊导入。
- 每位作者都必须是聊天的当前成员,并且必须同意。未同意、已退出或不是成员的人的消息会被拒绝。
- 导入的消息必须是过去的日期,每条都晚于前一条,并且晚于聊天中已有的最新消息。系统消息也算在内,例如成员加入,所以在群聊中,历史的日期必须晚于其成员加入的时间。只有仍在聊天中的消息才算数,所以历史不能插入到仍在那里的消息之前,但可以腾出空间:导入期间,所有者可以清除聊天的历史,或删除单条消息,之后就可以导入与被清除的消息一样早的历史。导入期间的清除无法撤销,也不会发布“历史已清除”的提示。
- 导入模式开启时,任何人都不能发消息,包括所有者。整个地点的导入会停止该地点每个聊天的发言。
- 导入的消息不会发送通知。



带有 MCP 导入工具的助手可以用 start_import 做同样的事。除非调用中说明你已确认,否则该工具什么也不做,因为它会让所有成员都不能发言。
开始导入模式
在应用中:
- 打开聊天的设置(在窄屏上,选择聊天标题栏中的三点按钮,然后选择编辑聊天;在宽屏上,打开右侧面板并选择其标题区中的编辑按钮),或整个地点的导入则打开地点的设置,然后选择开始导入。该入口只对所有者显示,话题中不显示。
- 确认开始导入模式?。Voxt 会进行几项最终检查,大约十秒(“正在进入导入模式”)。如果在启动期间有人发了消息,Voxt 会请你删除该消息并重新开始。
- 消息输入框对所有人都会被维护模式取代。
请成员允许导入
确认对话框、成员的同意和结束导入的说明见导入聊天历史。简要来说:
- 每位成员打开聊天,选择允许在本次导入期间导入我的消息和媒体,并确认允许导入?。对该次导入,同意无法撤销。所有者也要同意,才能导入自己的消息。
- 所有者可以看到已同意的成员比例(“已同意:100%(3 人中的 3 人)”)以及还缺少谁。
- 未同意的成员的消息会被拒绝,所以请等到所有你想导入其历史的人都同意。
导入期间成员不能在聊天中写字,所以所有者无法在那里提醒他们。请在你们的私聊中给他们发消息;私聊保持开放。助手可以做到这一点:get_import 列出尚未同意的成员,以及你与每个人的私聊,助手在那里发出提醒,并反复检查,直到同意的比例达到你想要的程度。
为更早的历史腾出空间
如果历史比聊天中已有的消息更早,例如记录成员加入的系统消息,请先删除这些消息。使用 MCP 工具时,wipe_history 会删除聊天中从所选消息开始的消息(默认是全部),只在导入进行期间可用,且只对所有者开放,并在消息删除完成后返回;remove_message 删除单条消息。两者都可以在导入期间使用。清除无法撤销,所以在执行之前请先向所有者确认。消息导入之后不要再清除:那样也会把它们删掉。
发送消息
导入模式开启期间,所有者的助手或程序发送历史:
- 读取当前的导入(
get_import);它带有每次调用都需要的导入 ID。 - 先为发送附件的成员上传附件;该成员必须已同意。每个上传只附加到一条消息。
- 以 1 到 100 条为一批发送消息,从旧到新。每条消息包含作者、原始时间、文字(最多 64 KB)、最多 10 个附件,以及可选的它所回复的消息。每一批都有自己的 ID:再次发送同一批会返回之前的结果,所以网络错误后的重试不会产生重复的消息。
- 回复只能指向聊天中已有的消息,所以请先在更早的一批中发送那条消息,并使用返回的 ID。
- 在整个地点的导入中,把每条消息发送到它所属的该地点的具体聊天。检查每条消息的结果。一批消息可能部分成功:被拒绝的消息会连同原因一起返回(例如“该成员未同意导入。”),其余的会被保存。
这些步骤的 MCP 工具在导入历史中说明。程序也可以通过 RPC API 使用同一服务,数据类型见导入数据类型。MCP 的 post_message 不是导入:它以你的身份发消息,日期是现在。
结束导入模式
所有消息发送完毕后,所有者在应用中选择结束导入,或助手调用 end_import。成员可以再次发言,导入的历史位于第一条新消息之上。从未同意的成员就是没有消息被导入。
导入之后,请滚动浏览聊天进行检查:消息显示原作者和原日期,第一条新消息紧随其后。把几条消息与来源进行对比,如果你的助手保留了被拒绝消息的列表,也请阅读它。更好的做法是在结束导入模式之前把导入的消息读回来,这样你还能发送缺少的那些。

示例:导入 Telegram 导出文件
整个导入可以由助手完成,只要它通过 MCP 连接到 Voxt,并且能读取你电脑上的导出文件夹,例如 Claude Code 或其他有文件访问权限的助手。你不需要自己的程序。无法读取你文件的纯聊天助手做不到这一点。
开始之前:
- 在 Telegram Desktop 中导出聊天:打开聊天,选择Export chat history,选择 Machine-readable JSON,如果需要,也包含照片和文件。导出文件夹包含
result.json以及photos、files等文件夹。 - 创建 Voxt 群聊,并添加在 Telegram 聊天中发过言的人。每个人都需要有 Voxt 账号并且是成员。没有对应 Voxt 成员的 Telegram 名称无法导入。
- 决定助手如何登录:用 API 密钥,或通过 OAuth 用你的 Voxt 账号(见下文)。
- 把 Voxt 作为 MCP 服务器添加到你的助手(见下文)。
把 Voxt 添加为 MCP 服务器
服务器地址是 https://voxt.ai/mcp。有两种登录方式。两种方式中,助手都以你的身份操作。
使用 API 密钥。 在 Voxt 中创建密钥(设置 → API 与应用 → 创建 API 密钥),并通过 Authorization: Bearer 标头传递。在 Claude Code 中运行:
claude mcp add --transport http voxt https://voxt.ai/mcp --header "Authorization: Bearer $VOXT_API_KEY"请先在终端中设置 VOXT_API_KEY,这样密钥就不会出现在提示词或文件中。
使用 OAuth。 省略标头和密钥:
claude mcp add --transport http voxt https://voxt.ai/mcp然后启动 Claude Code,运行 /mcp,选择 voxt,选择进行身份验证。浏览器窗口会打开 Voxt 的授权页面;批准访问后助手就连接好了,不需要创建或保存密钥。
其他助手有用于远程 MCP 服务器或连接器的设置页面,在那里输入同样的地址,以及标头或登录方式之一。MCP 说明了这两种方式。请助手列出你的 Voxt 聊天,以检查连接是否正常。
给出指令
给助手一条类似下面的指令。请替换文件夹和聊天名称。
I want to import a Telegram chat export into a Voxt group chat. I am its owner.
Read these pages first. They describe the import tools and the rules:
- https://docs.voxt.ai/users/import-export/
- https://docs.voxt.ai/developers/mcp/tools
Inputs:
- The Telegram export is in the folder D:\exports\trip-chat (result.json, photos, files).
- The target is my Voxt group chat "Trip photos", which the Voxt MCP server can see.
Do this, and stop to ask me where it says so:
1. Read result.json. List the distinct senders (the "from" field) with their message counts, and give the date range. Skip service messages (type "service").
2. Use the Voxt MCP server to find "Trip photos" and list its members. Propose a mapping from Telegram senders to Voxt members and ask me to confirm it. Messages of senders without a Voxt member will be left out.
3. Call get_import to check that no import is running. Tell me that starting the import stops posting for every member of the chat until it ends, and ask me to confirm. Then call start_import with confirm true.
4. Compare the date of the earliest message with the chat. Imported messages must be later than the chat's newest message, system messages such as "joined" included. If the history starts earlier, tell me; if I confirm (it cannot be undone), call wipe_history with the importId from start_import to remove what is in the way, and wait until it reports isPurged.
5. Call get_import to see who has not consented. Post a short reminder to each of them in their direct chat (peerChatId), asking them to open "Trip photos" and allow the import. Call consent_to_import for me. Check get_import every minute and tell me the consented share; ask me when to go on.
6. Convert the messages: author = the mapped member's userId, sentAt = the message date in Unix milliseconds (ask me which time zone the export used; Telegram stores local time without a zone), text = the message text (join the pieces when "text" is a list), replyToId = the Voxt ID of the message that reply_to_message_id points to, if that one was imported in an earlier batch.
7. Send the photos and files named in "photo" and "file" first: begin_import_upload, append_upload in chunks of at most 1 MB, finish_import_upload, and put the upload IDs into the message. If there are many large files, import the text first and ask me about the files.
8. Import with import_messages in batches of at most 100, oldest first, with a different batchId for every batch. Check the result of every message and keep a list of the ones that were rejected, with the reason.
9. Read the imported messages back with list_messages and check the count, the authors and the dates against the export. Show me the result and the rejected messages.
10. Do not call end_import until I say so.示例说明:
- Telegram 保存的消息时间不带时区。在发送其余消息之前,请对照原聊天检查最先导入的几条消息。
- 被拒绝的消息不会中断整批。修复原因(缺少成员、发送者未允许导入、时间顺序不对),然后在新的一批中重新发送。
- 无法对应的消息会被省略,所以如果需要完整记录,请保留 Telegram 导出文件。
- 每个文件通过助手以 1 MB 的块传输,所以含有许多大文件的聊天需要很多次调用。只有文字的话很快。