Ir para o conteúdo

Importação e exportação ​

O Voxt não tem um botão "exportar chat" ou "importar chat" que gere ou leia um arquivo. Os dados circulam pelas duas interfaces programáticas:

  • Exportar lê as mensagens, os anexos, os membros e os resumos de um chat por meio do MCP ou da API RPC.
  • Importar adiciona a um chat o histórico anterior de outro serviço. O proprietário inicia o modo de importação, os membros concordam e as mensagens são enviadas pelas ferramentas de importação do MCP ou pelo serviço de importação da API RPC. Nos dois casos, o proprietário pode executar todo o processo a partir de um assistente.

Exportar um chat ​

Exportar exige uma chave de API ou um login por OAuth. O assistente ou script age como você, portanto pode ler exatamente os chats que você pode ler, e nenhum outro.

  1. Crie uma chave de API, ou conecte um assistente com o fluxo OAuth, conforme descrito em MCP.
  2. Peça a exportação ao assistente, por exemplo: "Leia todas as mensagens do chat Trip photos e salve-as em um arquivo Markdown com datas e autores." O assistente escolhe as ferramentas; você não precisa saber os nomes delas.
  3. Para um script, chame as ferramentas diretamente. A referência de ferramentas as lista com seus argumentos.

O que pode ser lido:

DadosFerramentasObservações
Mensagenslist_messages, get_id_rangeDa mais antiga para a mais recente, até 1.024 mensagens por chamada. Continue a partir do ID da última mensagem até que nada seja retornado. Mensagens removidas são omitidas.
Mensagens fixadas e reaçõeslist_pinned_messages, list_reactions
Fotos, vídeos, arquivos e linkslist_media, list_files, list_linksAgrupados por mês, do mês mais recente ao mais antigo. Todo anexo traz uma URL de conteúdo.
Membroslist_members, list_place_members
Chats e Lugareslist_group_chats, list_peer_chats, list_places, list_place_chats, list_archived_chats, get_chat, get_placeUse-os para encontrar o que exportar. Os chats que você arquivou são listados apenas por list_archived_chats.
Resumoslist_conversations, get_conversationTrechos resumidos de um chat, como uma sessão de voz.
Resultados de pesquisasearch_messages, search_contacts

O que saber antes de exportar um chat grande:

  • As ferramentas retornam páginas, não um arquivo. O assistente ou script monta o resultado.
  • Uma mensagem que ainda está sendo transmitida ainda não tem texto. Leia essa parte novamente mais tarde.
  • Edições e remoções de mensagens que você já leu não são informadas. Leia o intervalo novamente se o chat ainda estiver ativo.

Importar o histórico para um chat ​

Use o modo de importação para trazer uma conversa de outro serviço para um chat em grupo do Voxt ou para um Lugar. As mensagens são armazenadas com seus autores e datas originais, de modo que o chat parece ter estado sempre no Voxt.

O que saber primeiro:

  • Somente o proprietário do chat ou do Lugar pode iniciar e encerrar uma importação.
  • Funciona para chats em grupo e para Lugares. Uma importação em todo o Lugar abrange todos os chats dele. Não é possível importar para chats diretos.
  • Todo autor precisa ser membro atual do chat e precisa concordar. As mensagens de alguém que não concordou, que saiu ou que não é membro são rejeitadas.
  • As mensagens importadas devem ter data no passado, cada uma posterior à anterior e posterior à mensagem mais recente que o chat já tem. As mensagens do sistema contam, como a entrada de membros, portanto em um chat em grupo o histórico deve ter data posterior à entrada dos membros. Só contam as mensagens que ainda estão no chat; por isso não é possível inserir histórico antes de mensagens que estão lá, mas dá para ajustar: durante a importação o proprietário pode apagar o histórico do chat ou remover mensagens isoladas, e então um histórico tão antigo quanto as mensagens apagadas pode ser importado. Um apagamento durante a importação não pode ser desfeito e não publica nenhum aviso de "histórico apagado".
  • Ninguém pode publicar enquanto o modo de importação estiver ativo, nem o proprietário. Uma importação em todo o Lugar impede a publicação em todos os chats do Lugar.
  • As mensagens importadas não enviam notificações.

Iniciar o modo de importação ​

No app:

  1. Abra as configurações do chat (em uma tela estreita, selecione o botão de três pontos no cabeçalho do chat e depois Editar chat; em uma tela larga, abra o painel direito e selecione o botão de edição no cabeçalho dele), ou do Lugar para uma importação em todo o Lugar, e selecione Iniciar importação. A opção é mostrada apenas aos proprietários, e não em tópicos.
  2. Confirme Iniciar o modo de importação?. O Voxt executa algumas verificações finais por cerca de dez segundos ("Entrando no modo de importação"). Se alguém publicou uma mensagem enquanto o modo iniciava, o Voxt pede que você remova essa mensagem e comece de novo.
  3. O campo de mensagem é substituído por Modo de manutenção para todos.
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.

Um assistente com as ferramentas de importação do MCP pode fazer o mesmo com start_import. A ferramenta não faz nada a menos que a chamada informe que você confirmou, porque ela impede a publicação para todos os membros.

Pedir aos membros que permitam a importação ​

A caixa de diálogo de confirmação, o consentimento dos membros e o encerramento da importação são mostrados em Importar o histórico de um chat. Em resumo:

  1. Cada membro abre o chat, seleciona Permitir a importação das minhas mensagens e mídias durante esta sessão e confirma Permitir a importação?. Um consentimento não pode ser revogado durante essa importação. O proprietário também consente, para importar as próprias mensagens.
  2. O proprietário vê a proporção de membros que concordaram ("Consentiram: 100% (3 de 3)") e quem ainda falta.
  3. As mensagens de membros que não concordaram são rejeitadas, portanto espere até que todos cujo histórico você quer tenham concordado.

Os membros não podem escrever no chat durante a importação, então o proprietário não pode lembrá-los ali. Envie mensagem a eles nos seus chats diretos; esses continuam abertos. Um assistente pode fazer isso: get_import lista os membros que não concordaram, cada um com o chat direto que você tem com ele, e o assistente publica um lembrete ali e verifica de novo até que a proporção desejada tenha concordado.

Abrir espaço para um histórico mais antigo ​

Se o histórico for mais antigo que mensagens que já estão no chat, por exemplo as mensagens do sistema que registram a entrada de membros, remova-as primeiro. Com as ferramentas do MCP, wipe_history remove as mensagens do chat a partir de uma mensagem escolhida (por padrão, todas), somente enquanto a importação está em andamento e somente para proprietários, e retorna quando elas já foram excluídas; remove_message remove uma única mensagem. As duas funcionam durante uma importação. O apagamento não pode ser desfeito, portanto confirme-o com o proprietário antes de executá-lo. Não apague de novo depois que as mensagens forem importadas: isso removeria as importadas também.

Enviar as mensagens ​

Enquanto o modo de importação está ativo, o assistente ou programa do proprietário envia o histórico:

  1. Leia a importação atual (get_import); ela traz o ID da importação, que toda chamada exige.
  2. Envie primeiro os anexos, em nome do membro que os enviou; esse membro deve ter concordado. Cada envio é anexado a uma mensagem.
  3. Envie as mensagens em lotes de 1 a 100, da mais antiga para a mais recente. Cada mensagem tem o autor, o horário original, o texto (até 64 KB), até 10 anexos e, opcionalmente, a mensagem à qual responde. Um lote tem o próprio ID: enviar o mesmo lote de novo retorna o resultado anterior, portanto uma nova tentativa após um erro de rede não duplica mensagens.
  4. Uma resposta só pode apontar para uma mensagem que já está no chat; portanto envie a mensagem primeiro, em um lote anterior, e use o ID retornado.
  5. Em uma importação em todo o Lugar, envie cada mensagem ao chat específico do Lugar a que ela pertence. Verifique o resultado de cada mensagem. Um lote pode ter sucesso parcial: uma mensagem rejeitada volta com o motivo (por exemplo, "Este membro não consentiu com a importação."), e as outras são armazenadas.

As ferramentas do MCP para essas etapas estão descritas em Importar histórico. O mesmo serviço está disponível para programas pela API RPC, com os tipos de dados em Tipos de dados de importação. O post_message do MCP não é uma importação: ele publica como você, com a data de agora.

Encerrar o modo de importação ​

Quando todas as mensagens forem enviadas, o proprietário seleciona Encerrar importação no app, ou o assistente chama end_import. Os membros podem publicar de novo, e o histórico importado fica acima da primeira mensagem nova. Os membros que nunca concordaram simplesmente não têm mensagens importadas.

Depois da importação, percorra o chat para conferi-lo: as mensagens mostram os autores e as datas originais, e a primeira mensagem nova vem logo depois delas. Compare algumas mensagens com a origem e leia a lista de mensagens rejeitadas, se o seu assistente mantiver uma. Melhor ainda, leia as mensagens importadas de volta antes de encerrar o modo de importação, enquanto você ainda pode enviar as que faltam.

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

Exemplo: importar uma exportação do Telegram ​

A importação inteira pode ser feita por um assistente conectado ao Voxt por MCP e capaz de ler a pasta da exportação no seu computador, como o Claude Code ou outro assistente com acesso a arquivos. Não é preciso um programa próprio. Um assistente somente de chat, que não consegue ler seus arquivos, não consegue fazer isso.

Antes de começar:

  1. No Telegram Desktop, exporte o chat: abra o chat, escolha Export chat history, selecione Machine-readable JSON e inclua fotos e arquivos se quiser. A pasta da exportação contém result.json e pastas como photos e files.
  2. Crie o chat em grupo do Voxt e adicione as pessoas que escreveram no chat do Telegram. Cada uma precisa ter uma conta do Voxt e ser membro. Nomes do Telegram sem um membro correspondente no Voxt não podem ser importados.
  3. Decida como o assistente fará login: com uma chave de API ou com sua conta do Voxt por OAuth (veja abaixo).
  4. Adicione o Voxt ao seu assistente como servidor MCP (veja abaixo).

Adicionar o Voxt como servidor MCP ​

O endereço do servidor é https://voxt.ai/mcp. Há duas formas de fazer login. Nas duas, o assistente age como você.

Com uma chave de API. Crie uma chave no Voxt (Configurações → API e apps → Criar chave de API) e passe-a em um cabeçalho Authorization: Bearer. No Claude Code, execute:

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

Defina VOXT_API_KEY primeiro no seu terminal, para que a chave não apareça em um prompt nem em um arquivo.

Com OAuth. Omita o cabeçalho e a chave:

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

Depois inicie o Claude Code, execute /mcp, selecione voxt e escolha autenticar. Uma janela do navegador abre com a página de consentimento do Voxt; aprove o acesso e o assistente fica conectado, sem chave para criar nem salvar.

Outros assistentes têm uma página de configurações para servidores MCP remotos ou conectores, onde você digita o mesmo endereço e o cabeçalho ou o login. O MCP descreve as duas formas. Peça ao assistente que liste seus chats do Voxt para verificar se a conexão funciona.

Dar a instrução ​

Dê ao assistente uma instrução como esta. Troque a pasta e o nome do chat.

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.

Observações sobre o exemplo:

  • O Telegram salva o horário de uma mensagem sem fuso horário. Confira as primeiras mensagens importadas com o chat original antes de enviar o restante.
  • Mensagens rejeitadas não interrompem o lote. Corrija a causa (um membro ausente, um remetente que não permitiu a importação, um horário fora de ordem) e envie-as de novo em um novo lote.
  • As mensagens que não podem ser associadas ficam de fora, portanto salve a exportação do Telegram se precisar do registro completo.
  • Cada arquivo viaja em pedaços de 1 MB pelo assistente, portanto um chat com muitos arquivos grandes exige muitas chamadas. Só o texto é rápido.