Exportar e Importar Filtros do Mastodon: Guia Passo a Passo

Você gastou tempo criando filtros no Mastodon para ocultar postagens, palavras-chave e hashtags indesejadas. Ao mudar para uma nova conta ou instância, é preciso recriar esses filtros manualmente. O Mastodon não oferece uma ferramenta nativa de exportação ou importação de filtros em sua interface web padrão. Este artigo explica como exportar seus filtros usando a API do Mastodon e importá-los em outra conta usando ferramentas baseadas no navegador.

Como os Filtros do Mastodon Funcionam e Por Que a Exportação Não é Nativa

Os filtros do Mastodon permitem ocultar ou exibir avisos sobre postagens que contenham palavras, frases ou hashtags específicas. Você pode aplicar filtros à linha do tempo inicial, notificações ou linhas do tempo públicas. Cada filtro possui um título, um conjunto de palavras-chave, uma data de expiração e uma lista de contextos. Os filtros são armazenados por conta no banco de dados do Mastodon. A interface web oficial do Mastodon não fornece um botão Exportar ou Importar para filtros, pois o recurso é considerado de baixa prioridade pela equipe de desenvolvimento. A API expõe os dados dos filtros, o que permite usar soluções técnicas para transferir filtros entre contas.

Antes de começar, você precisa de uma conta no Mastodon na instância de origem onde seus filtros existem e uma segunda conta na instância de destino onde deseja que os filtros apareçam. O processo de exportação e importação usa a API REST do Mastodon. Você não precisa de experiência em programação, mas deve se sentir confortável usando as ferramentas do desenvolvedor do navegador e copiando texto JSON. As etapas abaixo funcionam tanto no Windows 10 quanto no Windows 11 com qualquer navegador moderno, como Chrome, Edge ou Firefox.

Etapas para Exportar Filtros da Sua Conta de Origem no Mastodon

1. Faça login na conta de origem do Mastodon
   Abra seu navegador e entre na instância do Mastodon onde seus filtros estão salvos. Vá em Preferências > Filtros para confirmar que seus filtros existem.
2. Abra as Ferramentas do Desenvolvedor do Navegador
   Pressione Ctrl+Shift+I no Windows 10 ou Windows 11 para abrir as Ferramentas do Desenvolvedor. Clique na aba Network. Certifique-se de que o botão de gravação está vermelho, indicando que está capturando requisições de rede.
3. Envie uma requisição para o endpoint da API de filtros
   Na barra de endereços do navegador, digite a seguinte URL e pressione Enter: https://[dominio-da-sua-instancia]/api/v1/filters. Substitua [dominio-da-sua-instancia] pelo domínio da sua instância do Mastodon, por exemplo mastodon.social. Esta URL envia uma requisição GET para recuperar todos os seus filtros como JSON.
4. Localize a resposta da API na aba Network
   Na aba Network, procure por uma linha chamada filters com o método GET e status 200. Clique nessa linha. Em seguida, clique na aba Response. Você verá um array JSON contendo seus filtros. Cada objeto de filtro inclui campos como id, title, context, filter_action, keywords e expires_at.
5. Copie a resposta JSON para um arquivo
   Selecione todo o texto JSON na aba Response. Pressione Ctrl+A e depois Ctrl+C para copiar. Abra um editor de texto simples, como o Bloco de Notas no Windows. Pressione Ctrl+V para colar o JSON. Salve o arquivo como mastodon-filters-export.json na sua área de trabalho. Mantenha este arquivo seguro, pois contém os dados necessários para a importação.

Etapas para Importar Filtros na Sua Conta de Destino no Mastodon

1. Faça login na conta de destino do Mastodon
   Entre na instância do Mastodon onde você deseja adicionar os filtros. Pode ser a mesma instância com uma conta diferente ou uma instância completamente diferente.
2. Abra novamente as Ferramentas do Desenvolvedor e a aba Network
   Pressione Ctrl+Shift+I e clique na aba Network. Mantenha-a aberta.
3. Crie um novo filtro manualmente para capturar o formato da requisição da API
   Vá em Preferências > Filtros. Clique no botão Adicionar novo filtro. Preencha um título temporário como teste e adicione uma palavra-chave como testepalavra. Não clique em Salvar ainda.
4. Intercepte a requisição POST para a API de filtros
   Na aba Network, limpe as entradas existentes clicando no botão de limpar. Em seguida, clique em Salvar no formulário de criação do filtro. Na aba Network, procure por uma linha chamada filters com o método POST. Clique nessa linha e depois na aba Headers. Observe a URL da requisição: https://[dominio-da-sua-instancia]/api/v1/filters. Observe também o cabeçalho Authorization, que contém seu token de acesso. Este token é enviado automaticamente pela interface web.
5. Envie uma requisição POST com os dados do filtro exportado
   Abra uma nova aba no navegador. Use uma ferramenta como a Fetch API no console do navegador, ou um cliente REST online como Postman ou Hoppscotch. Para um método rápido, abra o console do navegador pressionando Ctrl+Shift+J. Cole o seguinte modelo JavaScript, substituindo os valores de espaço reservado pelos seus dados reais:
   fetch('https://[dominio-da-sua-instancia]/api/v1/filters', {
method: 'POST',
headers: {
'Authorization': 'Bearer SEU_TOKEN_DE_ACESSO',
'Content-Type': 'application/json'
},
body: JSON.stringify(SEU_OBJETO_DE_FILTRO_EXPORTADO)
});
   Substitua SEU_TOKEN_DE_ACESSO pelo token do cabeçalho Headers que você viu na etapa 4. Substitua SEU_OBJETO_DE_FILTRO_EXPORTADO pelo primeiro objeto de filtro do seu arquivo JSON salvo. Pressione Enter para executar. Você deve ver uma resposta com status 200 e o objeto de filtro criado.
6. Repita para cada filtro no seu arquivo de exportação
   Abra seu arquivo JSON salvo. Copie cada objeto de filtro um de cada vez e execute o comando fetch para cada um. Após enviar todos os filtros, vá em Preferências > Filtros na conta de destino. Todos os seus filtros devem aparecer agora.

Problemas Comuns ao Exportar e Importar Filtros do Mastodon

Filtros Não Aparecem Após a Importação

A causa mais comum é um token de acesso incorreto. O token que você copia da aba Network está vinculado à sessão atual do navegador. Se você sair e entrar novamente, o token muda. Sempre copie o token da mesma sessão em que está realizando a importação. Outra causa é uma estrutura JSON inválida. A API do Mastodon espera um objeto de filtro com campos como title, context e keywords. Se você enviar o array inteiro em vez de um único objeto, a API retorna um erro 422. Extraia um objeto de cada vez do array.

Palavras-chave do Filtro Estão Faltando Após a Importação

O JSON exportado inclui um array keywords dentro de cada objeto de filtro. Ao importar, você deve incluir o array keywords no corpo da requisição POST. Se você omitir o campo keywords, o filtro será criado com zero palavras-chave e não bloqueará nada. Verifique se seu JSON exportado contém um array keywords com pelo menos uma entrada. O objeto de palavra-chave tem campos como id, keyword e whole_word. O campo id é opcional e pode ser definido como null.

Datas de Expiração do Filtro Estão Incorretas

O campo expires_at no JSON exportado usa o formato ISO 8601 com offset de fuso horário. Ao importar o filtro, a API aceita o mesmo formato. Se a data já estiver no passado, o filtro será criado, mas expirará imediatamente. Você pode definir expires_at como null para criar um filtro sem expiração. Edite o JSON antes de enviar a requisição POST para remover o campo expires_at ou defini-lo como null.

Item	Processo de Exportação	Processo de Importação
Método da API	GET	POST
Endpoint	/api/v1/filters	/api/v1/filters
Formato dos dados	Array JSON de objetos de filtro	Objeto JSON de filtro único por requisição
Autenticação	Cookie de sessão do navegador	Token Bearer do cabeçalho Authorization
Ferramenta utilizada	Barra de endereços do navegador ou aba Network	Console do navegador (fetch) ou cliente REST
Erro se token ausente	Redirecionamento para página de login	HTTP 401 Não Autorizado

Agora você pode transferir seus filtros do Mastodon entre contas usando o método de exportação e importação pela API. O processo requer copiar dados JSON e enviar requisições POST a partir do console do navegador. Após a importação, verifique cada filtro acessando a página de Filtros nas preferências da sua conta de destino. Para contas com muitos filtros, considere escrever um pequeno script que percorra o array exportado e envie cada filtro automaticamente usando o mesmo padrão fetch descrito acima.