# Server templates and TeamTalk XML import

Use this guide when you set up a VoiceLink server or optionally bring over the
room layout of a TeamTalk server. Only a signed-in server owner can apply a
template pack or use a detected importer plugin.

## Start with a template pack

The first-owner wizard offers a template choice, and the same choice is
available later in Server Administration. Choose one of these packs, or choose
**Blank** to start with no prefilled rooms:

- **Community hangout** — welcoming social rooms and newcomer guidance.
- **Radio and streaming** — listener, host, and studio-style defaults.
- **Workshop and classroom** — instruction and small-group work defaults.
- **Office and team** — meeting, team, and staff-room defaults.

A pack is a prefill, not a policy lock. It supplies a flat list of rooms and
starting values for room topics, the message of the day, roles, pre-join alerts,
and default audio/room settings. Owners can change or remove every supplied
item after setup. VoiceLink rooms are flat; an import or template pack does not
create nested rooms.

### Whose starter layouts appear

The central VoiceLink API serves the current catalogue. A verified owner of a
TeamTalk server on this host sees only that owner's personal layouts, including
their existing room names, topics, and room settings. Dom's layouts are limited
to the three approved Dom sources and Walter's layout is limited to Walter's
verified account and `walterharper.com`. No other owner can request either.

Everyone else can choose **Blank** or a blank-placeholder starter with the same
flat layout and suggested settings, but no copied names, topics or MOTD. When a
placeholder is applied, its generated slots include the destination server name
(for example, `Room 1 — My server`) so separate servers do not publish
indistinguishable rooms. The standard packs use a read-only aggregate of the room kinds,
capacity, visibility balance and flat-list approach of the main and community
VoiceLink servers. They do not contain or reuse either server's room names,
topics, IDs, people, links or other server data, so each new server starts with
distinct federation room names.

## Optional TeamTalk rooms-only import

The TeamTalk importer is an optional plugin. If it is not detected on the
server, its controls are unavailable; a server still works normally without it.
It is deliberately a rooms-only conversion, not a TeamTalk server migration.

1. In Server Administration, choose **Import TeamTalk XML** and select an XML
   export from your computer.
2. Review every proposed room, one at a time: its name, topic/description,
   public/private/hidden visibility, maximum users, and audio quality. Keep a
   suggestion or edit it, then choose which imported room should be the first
   room people join.
3. Confirm the import only after that review. The apply request reparses the
   selected file and accepts only those VoiceLink room choices, so no preview
   data or source XML has to be kept on the server.

Work from a copy of the export. VoiceLink never changes the original TeamTalk
file.

### What VoiceLink imports

| TeamTalk content | VoiceLink result |
| --- | --- |
| Root channel | Suggested, editable VoiceLink server name; its topic suggests description/welcome text. Root is not imported as a room. |
| Non-Root channel names and topics | Flat rooms and their topics |
| Protected room | Private access-request room; its password is not copied or stored |

The importer does not copy TeamTalk users, credentials, account names,
passwords, room passwords, bans, quotas, or account placeholders. It does not
retain XML after handling it. Preview and apply reports contain only room totals.

The importer leaves all user, moderation, ban, quota, bandwidth, file-storage,
and account settings alone. Configure those as new VoiceLink settings if needed.

## Links, domains, and trust

VoiceLink's public, personal, and room links are resolved by the central
VoiceLink API. The central service is also responsible for directory approval,
domain requests, verified ownership checks, and domain trust lists. A template
pack or TeamTalk import does not enable these services and does not create a
per-server token resolver or trust list.

When the central integration is available, clients use it to resolve links such
as `my.voicelinkapp.app/srv/<server-code>` and room links under that server.
Their public/private/hidden behavior is decided by the central service and the
room's access policy. Until then, use the normal server connection and room
access flow; do not treat a local server as an authority for central links or
domain trust.

## Accessibility notes

The preview must be readable before the confirmation control is offered. Each
room's editable controls have labels, and the default-room choice is explicit.
Errors stay next to the file or setting that needs attention and are announced
once. The preview deliberately excludes imported account or moderation data.
## Owner-detected TeamTalk starter

When a verified owner’s known domain is linked to a TeamTalk server on this host,
VoiceLink checks only that owner’s configured source. It shows the owner the
room and account counts, suggested server name, and converted message of the
day before any change. The owner can choose **Use it**, **Start blank**, or a
template, and can edit every suggested value before confirmation. No other
owner can detect, preview, or use that source.

### Optional account migration

TeamTalk account import is never the default and is separate from the rooms
flow. VoiceLink recommends personal join links, sign-up codes, Mastodon, or an
existing VoiceLink account instead. An owner may choose **Optional account
import** only after selecting the acknowledgement and typing **Are you sure?**.

That creates pending accounts using only a username and mapped role. VoiceLink
does not read, copy, retain, or compare a TeamTalk password. The owner receives
one claim link per pending account and must send each link privately; the person
uses it to choose their own new password and claim the account. The account
panel does not import bans. Bans are always a separate moderation decision and
are never included in an account or room import.

Windows and macOS show an **Open optional account import in web admin** button
next to the TeamTalk setup controls. It opens this same signed-in, owner-only
confirmation flow; the desktop rooms importer never handles accounts itself.

## Federation and starter packs

Starter packs are modelled on the room kinds and flat layouts used by the main
and community VoiceLink servers, but each generated generic or placeholder room
name includes the new server name. They never copy the live servers' exact room
names.

During setup, choose whether this server broadcasts no rooms, all eligible
rooms, or selected rooms. The choice is applied immediately and is also
available in Admin > Federation. Federation uses a stable `serverId:roomId`
identity and presents every entry as **Room name, on Server name**, so equal
room names from different servers never merge.