Cloud Storage

CloudStorage provides cloud-based key-value storage that syncs across all of the user's devices. Accessed via Telegram.WebApp.CloudStorage.

Limits

Item	Limit
Maximum number of keys	1024
Maximum key length	128 characters
Maximum value length	4096 characters
Key characters	A-Z, a-z, 0-9, _, -

Methods

setItem

Telegram.WebApp.CloudStorage.setItem(key, value, callback)

Stores a key-value pair in cloud storage.

Parameter	Type	Required	Description
key	String	Yes	Key name, 1-128 characters
value	String	Yes	Value, 0-4096 characters
callback	Function	No	Callback with (error, success) parameters

Telegram.WebApp.CloudStorage.setItem('user_settings', JSON.stringify({
  theme: 'dark',
  language: 'en'
}), (error, success) => {
  if (error) {
    console.error('Storage failed:', error);
  } else {
    console.log('Stored successfully');
  }
});

getItem

Telegram.WebApp.CloudStorage.getItem(key, callback)

Reads the value of a specified key from cloud storage.

Parameter	Type	Required	Description
key	String	Yes	Key name
callback	Function	Yes	Callback with (error, value) parameters

Telegram.WebApp.CloudStorage.getItem('user_settings', (error, value) => {
  if (error) {
    console.error('Read failed:', error);
  } else {
    const settings = JSON.parse(value);
    console.log('User settings:', settings);
  }
});

getItems

Telegram.WebApp.CloudStorage.getItems(keys, callback)

Reads values for multiple keys in batch.

Parameter	Type	Required	Description
keys	Array of String	Yes	Array of key names
callback	Function	Yes	Callback with (error, values) parameters, where values is a key-value object

Telegram.WebApp.CloudStorage.getItems(['key1', 'key2', 'key3'], (error, values) => {
  if (!error) {
    console.log('key1:', values.key1);
    console.log('key2:', values.key2);
  }
});

removeItem

Telegram.WebApp.CloudStorage.removeItem(key, callback)

Removes a specified key from cloud storage.

Parameter	Type	Required	Description
key	String	Yes	Key name
callback	Function	No	Callback with (error, success) parameters

removeItems

Telegram.WebApp.CloudStorage.removeItems(keys, callback)

Removes multiple keys in batch.

Parameter	Type	Required	Description
keys	Array of String	Yes	Array of key names
callback	Function	No	Callback with (error, success) parameters

getKeys

Telegram.WebApp.CloudStorage.getKeys(callback)

Gets all key names in cloud storage.

Parameter	Type	Required	Description
callback	Function	Yes	Callback with (error, keys) parameters, where keys is an array of key names

Telegram.WebApp.CloudStorage.getKeys((error, keys) => {
  if (!error) {
    console.log('All keys:', keys);
    console.log('Used:', keys.length, '/ 1024');
  }
});

Usage Example

const storage = Telegram.WebApp.CloudStorage;

// Save user preferences
function savePreferences(prefs) {
  storage.setItem('preferences', JSON.stringify(prefs), (err) => {
    if (err) console.error('Save failed:', err);
  });
}

// Load user preferences
function loadPreferences(callback) {
  storage.getItem('preferences', (err, value) => {
    if (err || !value) {
      callback(null);
    } else {
      callback(JSON.parse(value));
    }
  });
}

// Clear all data
function clearAll() {
  storage.getKeys((err, keys) => {
    if (!err && keys.length > 0) {
      storage.removeItems(keys, (err) => {
        if (!err) console.log('All data cleared');
      });
    }
  });
}