Getting Started and Telegram Setup

Getting Started and Telegram Setup

Unspool uses a Telegram user account through TDLib. A bot token is not a replacement for the API ID and API hash required by a Telegram client.

Before launching

You need:

• a Mac running macOS 26 or later;
• a local development build of Unspool;
• a Telegram account;
• an API ID and API hash created at my.telegram.org/apps.

Do not put the API hash, phone number, login code, password, or session database in source files, Xcode schemes, launch arguments, screenshots, issues, or commits.

Setup checklist

The first-run canvas keeps three steps visible:

1. Telegram API — enter the numeric API ID and API hash.
2. Telegram Account — complete the exact authorization step requested by Telegram.
3. Download Folder — choose a writable folder and decide whether to create one subfolder per chat.

The app is ready only after all three conditions are satisfied.

Credential validation and storage

TelegramAPICredentials.validated trims the entered values, requires a positive integer API ID, and rejects an empty API hash. Valid credentials are used to configure TDLib and then stored as one generic-password item in macOS Keychain.

The Keychain item uses:

• service: com.qenterra.unspool.telegram-api;
• account: telegram-api-credentials;
• accessibility: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly.

The Settings screen shows only the final two digits of the saved API ID and never displays the stored API hash.

Authorization states

Unspool renders the current TDLib authorization state rather than predicting which credential Telegram will request:

TDLib state	User action
Wait for phone number	Enter the account phone number
Wait for email address	Enter the requested email address
Wait for email code	Enter the code sent to the displayed email pattern
Wait for login code	Enter the current Telegram authorization code
Wait for registration	Enter first and last name and review supplied terms
Wait for password	Enter the Telegram two-step verification password
Wait for other device	Confirm the supplied link on another device
Ready	Continue to folder selection or Browse

Codes, passwords, email input, registration names, and phone numbers live in the setup coordinator while authorization is active. Unspool does not deliberately serialize them into its JSON stores.

Errors and retry behavior

Technical TDLib errors are translated into task-focused copy:

• check the phone number;
• check the code;
• check the password;
• wait when Telegram returns rate limiting;
• try again for an unclassified connection error.

Changing authorization state clears inputs that no longer belong to the active step. A failed submission keeps the current valid input so the user can correct only what is wrong.

Account actions

• Switch Account asks TDLib to log out but retains the API ID and API hash for the next account.
• Sign Out asks TDLib to log out and, after success, deletes the Keychain item and returns to setup.

Neither action deletes downloaded files. Sign out also does not automatically erase download history, attachment indexes, preferences, or the destination bookmark.

Related: Privacy and Security Model and Persistence and Local Data.