Chuyển đến nội dung

Nhập và xuất ​

Voxt không có nút "xuất cuộc trò chuyện" hay "nhập cuộc trò chuyện" để tạo hoặc đọc tệp. Dữ liệu được chuyển qua hai giao diện lập trình:

  • Xuất đọc tin nhắn, tệp đính kèm, thành viên và bản tóm tắt của một cuộc trò chuyện qua MCP hoặc RPC API.
  • Nhập thêm lịch sử cũ từ một dịch vụ khác vào một cuộc trò chuyện. Chủ sở hữu bắt đầu chế độ nhập, các thành viên đồng ý, và tin nhắn được gửi qua các công cụ nhập của MCP hoặc dịch vụ nhập của RPC API. Trong cả hai cách, chủ sở hữu có thể chạy toàn bộ quy trình từ một trợ lý.

Xuất một cuộc trò chuyện ​

Việc xuất cần khóa API hoặc đăng nhập OAuth. Trợ lý hoặc tập lệnh hành động thay bạn, nên nó đọc được đúng những cuộc trò chuyện bạn đọc được, và không hơn.

  1. Tạo khóa API, hoặc kết nối một trợ lý bằng quy trình OAuth, như mô tả trong MCP.
  2. Yêu cầu trợ lý của bạn xuất dữ liệu, ví dụ: "Đọc tất cả tin nhắn của cuộc trò chuyện Trip photos và lưu thành tệp Markdown kèm ngày tháng và tác giả." Trợ lý tự chọn công cụ; bạn không cần biết tên của chúng.
  3. Với tập lệnh, hãy gọi trực tiếp các công cụ. Tài liệu tham khảo công cụ liệt kê chúng cùng các đối số.

Những gì có thể đọc:

Dữ liệuCông cụGhi chú
Tin nhắnlist_messages, get_id_rangeCũ nhất trước, tối đa 1.024 tin nhắn mỗi lần gọi. Tiếp tục từ ID của tin nhắn cuối cùng cho đến khi không còn gì trả về. Tin nhắn đã bị xóa sẽ bị bỏ qua.
Tin nhắn đã ghim và biểu cảmlist_pinned_messages, list_reactions
Ảnh, video, tệp và liên kếtlist_media, list_files, list_linksNhóm theo tháng, tháng mới nhất trước. Mỗi tệp đính kèm có một URL nội dung.
Thành viênlist_members, list_place_members
Cuộc trò chuyện và địa điểmlist_group_chats, list_peer_chats, list_places, list_place_chats, list_archived_chats, get_chat, get_placeDùng để tìm cái cần xuất. Các cuộc trò chuyện bạn đã lưu trữ chỉ được liệt kê bởi list_archived_chats.
Bản tóm tắtlist_conversations, get_conversationCác đoạn của cuộc trò chuyện đã được tóm tắt, chẳng hạn một phiên giọng nói.
Kết quả tìm kiếmsearch_messages, search_contacts

Những điều cần biết trước khi xuất một cuộc trò chuyện lớn:

  • Các công cụ trả về từng trang, không phải một tệp. Trợ lý hoặc tập lệnh ghép kết quả lại.
  • Một tin nhắn vẫn đang được truyền trực tiếp chưa có văn bản. Hãy đọc lại phần đó sau.
  • Việc chỉnh sửa và xóa các tin nhắn bạn đã đọc không được báo cáo. Hãy đọc lại khoảng đó nếu cuộc trò chuyện vẫn còn hoạt động.

Nhập lịch sử vào một cuộc trò chuyện ​

Dùng chế độ nhập để đưa một cuộc trò chuyện từ dịch vụ khác vào nhóm trò chuyện hoặc địa điểm của Voxt. Tin nhắn được lưu dưới tên tác giả gốc và ngày gốc, nên cuộc trò chuyện trông như thể luôn có trong Voxt.

Điều cần biết trước:

  • Chỉ chủ sở hữu của cuộc trò chuyện hoặc địa điểm mới có thể bắt đầu và kết thúc việc nhập.
  • Chế độ này dùng được cho nhóm trò chuyện và địa điểm. Nhập toàn địa điểm bao gồm mọi cuộc trò chuyện trong địa điểm đó. Không thể nhập vào cuộc trò chuyện trực tiếp.
  • Mỗi tác giả phải là thành viên hiện tại của cuộc trò chuyện và phải đồng ý. Tin nhắn của người chưa đồng ý, đã rời đi hoặc không phải là thành viên sẽ bị từ chối.
  • Tin nhắn nhập phải có ngày trong quá khứ, mỗi tin muộn hơn tin trước nó, và muộn hơn tin nhắn mới nhất mà cuộc trò chuyện đã có. Tin nhắn hệ thống cũng được tính, chẳng hạn khi thành viên tham gia, nên trong nhóm trò chuyện lịch sử phải có ngày sau khi các thành viên tham gia. Chỉ những tin nhắn vẫn còn trong cuộc trò chuyện mới được tính, nên không thể chèn lịch sử vào trước các tin nhắn đang có, nhưng có thể điều chỉnh cho khớp: trong lúc nhập, chủ sở hữu có thể xóa sạch lịch sử của cuộc trò chuyện, hoặc xóa từng tin nhắn, và sau đó có thể nhập lịch sử cũ như các tin nhắn đã xóa. Việc xóa sạch trong lúc nhập không thể hoàn tác và không đăng ghi chú "đã xóa lịch sử".
  • Không ai có thể đăng tin khi chế độ nhập đang bật, kể cả chủ sở hữu. Nhập toàn địa điểm sẽ ngừng việc đăng tin trong mọi cuộc trò chuyện của địa điểm.
  • Tin nhắn được nhập không gửi thông báo.

Bắt đầu chế độ nhập ​

Trong ứng dụng:

  1. Mở cài đặt của cuộc trò chuyện (trên màn hình hẹp, chọn nút ba chấm ở phần đầu cuộc trò chuyện, rồi Chỉnh sửa cuộc trò chuyện; trên màn hình rộng, mở bảng bên phải và chọn nút chỉnh sửa trong phần đầu của nó), hoặc của địa điểm nếu nhập toàn địa điểm, và chọn Bắt đầu nhập. Mục này chỉ hiển thị với chủ sở hữu, và không hiển thị trong các chủ đề.
  2. Xác nhận Start import mode?. Voxt chạy vài bước kiểm tra cuối cùng trong khoảng mười giây ("Đang vào chế độ nhập"). Nếu có người đăng tin nhắn khi chế độ đang bắt đầu, Voxt sẽ yêu cầu bạn xóa tin nhắn đó và bắt đầu lại.
  3. Hộp soạn tin nhắn được thay bằng Chế độ bảo trì với mọi người.
The header of the group chat Trip photos with the three-dot menu button.
The chat header menu of Trip photos with the Edit chat entry.
The chat settings of an owner with the Start import entry marked.

Một trợ lý có các công cụ nhập của MCP có thể làm điều tương tự bằng start_import. Công cụ không làm gì trừ khi lệnh gọi nêu rõ rằng bạn đã xác nhận, vì nó ngừng việc đăng tin của mọi thành viên.

Đề nghị các thành viên cho phép nhập ​

Hộp thoại xác nhận, sự đồng ý của các thành viên và việc kết thúc nhập được trình bày trong Nhập lịch sử của một cuộc trò chuyện. Tóm tắt:

  1. Mỗi thành viên mở cuộc trò chuyện, chọn Cho phép nhập tin nhắn và nội dung đa phương tiện của tôi trong phiên này và xác nhận Allow import?. Sự đồng ý không thể thu hồi trong lần nhập đó. Chủ sở hữu cũng đồng ý, để nhập tin nhắn của chính mình.
  2. Chủ sở hữu thấy tỷ lệ thành viên đã đồng ý ("Consented: 100% (3 out of 3)") và những ai còn thiếu.
  3. Tin nhắn của thành viên chưa đồng ý sẽ bị từ chối, vì vậy hãy đợi đến khi tất cả những người bạn muốn nhập lịch sử đã đồng ý.

Thành viên không thể viết trong cuộc trò chuyện khi đang nhập, nên chủ sở hữu không thể nhắc họ ở đó. Hãy nhắn cho họ trong các cuộc trò chuyện trực tiếp của bạn; những cuộc đó vẫn mở. Một trợ lý có thể làm việc này: get_import liệt kê các thành viên chưa đồng ý, mỗi người kèm cuộc trò chuyện trực tiếp của bạn với họ, và trợ lý đăng lời nhắc ở đó rồi kiểm tra lại cho đến khi tỷ lệ bạn muốn đã đồng ý.

Dọn chỗ cho lịch sử cũ hơn ​

Nếu lịch sử cũ hơn các tin nhắn đã có trong cuộc trò chuyện, chẳng hạn các tin nhắn hệ thống ghi lại việc thành viên tham gia, hãy xóa chúng trước. Với các công cụ MCP, wipe_history xóa các tin nhắn của cuộc trò chuyện từ một tin nhắn được chọn trở đi (mặc định là tất cả), chỉ trong lúc nhập đang chạy và chỉ dành cho chủ sở hữu, và trả về khi các tin nhắn đã bị xóa; remove_message xóa một tin nhắn. Cả hai đều dùng được trong lúc nhập. Việc xóa sạch không thể hoàn tác, nên hãy xác nhận với chủ sở hữu trước khi chạy. Đừng xóa sạch lần nữa sau khi các tin nhắn đã được nhập: nó sẽ xóa cả chúng.

Gửi tin nhắn ​

Khi chế độ nhập đang bật, trợ lý hoặc chương trình của chủ sở hữu gửi lịch sử:

  1. Đọc lần nhập hiện tại (get_import); nó chứa ID nhập mà mọi lệnh gọi đều cần.
  2. Tải tệp đính kèm lên trước, cho thành viên đã gửi chúng; thành viên đó phải đã đồng ý. Mỗi tệp tải lên được gắn vào một tin nhắn.
  3. Gửi tin nhắn theo lô từ 1 đến 100, cũ nhất trước. Mỗi tin nhắn có tác giả, thời gian gốc, văn bản (tối đa 64 KB), tối đa 10 tệp đính kèm và, tùy chọn, tin nhắn mà nó trả lời. Mỗi lô có ID riêng: gửi lại cùng một lô sẽ trả về kết quả trước đó, nên thử lại sau lỗi mạng không tạo tin nhắn trùng.
  4. Một câu trả lời chỉ có thể trỏ đến tin nhắn đã có trong cuộc trò chuyện, vì vậy hãy gửi tin nhắn đó trước, ở lô trước, và dùng ID được trả về.
  5. Trong nhập toàn địa điểm, hãy gửi từng tin nhắn đến đúng cuộc trò chuyện của địa điểm mà nó thuộc về. Kiểm tra kết quả của từng tin nhắn. Một lô có thể thành công một phần: tin nhắn bị từ chối được trả về kèm lý do (ví dụ "This member has not consented to import."), còn các tin nhắn khác được lưu.

Các công cụ MCP cho những bước này được mô tả trong Nhập lịch sử. Cùng dịch vụ này có sẵn cho các chương trình qua RPC API, với các kiểu dữ liệu trong Kiểu dữ liệu nhập. post_message của MCP không phải là nhập: nó đăng dưới tên bạn, với ngày là hiện tại.

Kết thúc chế độ nhập ​

Khi đã gửi hết tin nhắn, chủ sở hữu chọn Kết thúc nhập trong ứng dụng, hoặc trợ lý gọi end_import. Các thành viên lại có thể đăng tin, và lịch sử đã nhập nằm phía trên tin nhắn mới đầu tiên. Những thành viên chưa bao giờ đồng ý đơn giản là không có tin nhắn nào được nhập.

Sau khi nhập, hãy cuộn qua cuộc trò chuyện để kiểm tra: các tin nhắn hiển thị tác giả và ngày gốc, và tin nhắn mới đầu tiên nằm ngay sau chúng. So sánh vài tin nhắn với nguồn, và đọc danh sách tin nhắn bị từ chối nếu trợ lý của bạn có giữ. Tốt hơn nữa, hãy đọc lại các tin nhắn đã nhập trước khi kết thúc chế độ nhập, khi bạn vẫn có thể gửi những tin còn thiếu.

A chat with older imported messages followed by a new message.

Ví dụ: nhập bản xuất từ Telegram ​

Trợ lý có thể thực hiện toàn bộ việc nhập nếu nó được kết nối với Voxt qua MCP và đọc được thư mục xuất trên máy tính của bạn, chẳng hạn Claude Code hoặc một trợ lý khác có quyền truy cập tệp. Bạn không cần chương trình riêng. Trợ lý chỉ trò chuyện mà không đọc được tệp của bạn thì không làm được.

Trước khi bắt đầu:

  1. Trong Telegram Desktop, xuất cuộc trò chuyện: mở cuộc trò chuyện, chọn Export chat history, chọn Machine-readable JSON và bao gồm ảnh và tệp nếu bạn muốn. Thư mục xuất chứa result.json và các thư mục như photos và files.
  2. Tạo nhóm trò chuyện Voxt và thêm những người đã viết trong cuộc trò chuyện Telegram. Mỗi người cần có tài khoản Voxt và phải là thành viên. Tên Telegram không có thành viên Voxt tương ứng thì không thể nhập.
  3. Quyết định trợ lý đăng nhập như thế nào: bằng khóa API, hoặc bằng tài khoản Voxt của bạn qua OAuth (bên dưới).
  4. Thêm Voxt vào trợ lý của bạn như một máy chủ MCP (bên dưới).

Thêm Voxt làm máy chủ MCP ​

Địa chỉ máy chủ là https://voxt.ai/mcp. Có hai cách đăng nhập. Trong cả hai, trợ lý hành động thay bạn.

Bằng khóa API. Tạo khóa trong Voxt (Cài đặt → API & ứng dụng → Tạo khóa API) và truyền nó trong tiêu đề Authorization: Bearer. Trong Claude Code, chạy:

bash
claude mcp add --transport http voxt https://voxt.ai/mcp --header "Authorization: Bearer $VOXT_API_KEY"

Hãy đặt VOXT_API_KEY trong terminal của bạn trước, để khóa không xuất hiện trong lời nhắc hay trong tệp.

Bằng OAuth. Bỏ tiêu đề và khóa:

bash
claude mcp add --transport http voxt https://voxt.ai/mcp

Sau đó khởi động Claude Code, chạy /mcp, chọn voxt và chọn xác thực. Một cửa sổ trình duyệt mở ra với trang đồng ý của Voxt; hãy chấp thuận quyền truy cập và trợ lý được kết nối, không cần tạo hay lưu khóa.

Các trợ lý khác có trang cài đặt cho máy chủ MCP từ xa hoặc trình kết nối, nơi bạn nhập cùng địa chỉ đó, kèm tiêu đề hoặc đăng nhập. MCP mô tả cả hai cách. Hãy yêu cầu trợ lý liệt kê các cuộc trò chuyện Voxt của bạn để kiểm tra kết nối hoạt động.

Đưa ra chỉ dẫn ​

Đưa cho trợ lý một chỉ dẫn như sau. Hãy thay thư mục và tên cuộc trò chuyện.

text
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.

Ghi chú về ví dụ:

  • Telegram lưu thời gian của tin nhắn không kèm múi giờ. Hãy kiểm tra những tin nhắn nhập đầu tiên với cuộc trò chuyện gốc trước khi gửi phần còn lại.
  • Tin nhắn bị từ chối không làm dừng lô. Hãy sửa nguyên nhân (thiếu thành viên, người gửi chưa cho phép nhập, thời gian sai thứ tự) và gửi lại chúng trong một lô mới.
  • Tin nhắn không thể ghép tương ứng sẽ bị bỏ qua, vì vậy hãy giữ bản xuất Telegram nếu bạn cần bản ghi đầy đủ.
  • Mỗi tệp được truyền qua trợ lý theo từng phần 1 MB, nên cuộc trò chuyện có nhiều tệp lớn cần nhiều lệnh gọi. Chỉ văn bản thì nhanh.