Telegram Data Centers: _MIGRATE Errors and Switching DCs

Telegram's servers are split across data centers

Telegram's servers are divided among data centers (DCs) in several regions, each identified by a number. Every account belongs to one data center, its "home", and every file carries the number of the data center where it is stored (dc_id). The official apps and TDLib handle this for you; if you work with MTProto directly, it is your job.

Getting the list of data centers

Your app first connects to any data center, then calls help.getConfig. The data center list inside it (dcOptions) gives each one's number, address and port, plus flags such as "media only" and "CDN". Do not hard-code addresses; store this list and use it. The server address on your app's page at my.telegram.org is only the place to make that first connection; see getting an api_id.

Errors that say "go somewhere else"

When a request goes to the wrong data center, a 303 error comes back with the destination number at the end of its name; see reading API errors.

Each data center has its own key

The authorization key used for encryption does not carry over between data centers. The first time you connect to a new one, you create a new key for it; see creating an authorization key. Store keys and sessions separately for each data center.

Moving without logging in again

If the user is logged in on their home data center and you need a file stored on another one, you do not have to make them log in again.

1. On the current data center, call auth.exportAuthorization with the target data center's number and receive a one-time authorization value.
2. Connect to the target data center (with a new key) and pass that value to auth.importAuthorization.
3. You can now make requests there as the same user.

One authorization key can have several sessions (connections) open at once, so apps often keep one connection for messages and another for large files; see uploading and downloading files.