Device Storage

DeviceStorage provides local persistent storage on the device. Data is stored only on the current device and is not synced across devices. Accessed via Telegram.WebApp.DeviceStorage. Bot API 8.0+

Limits

Item	Limit
Maximum storage capacity	5 MB
Maximum key length	128 characters
Key characters	A-Z, a-z, 0-9, _, -

Methods

setItem

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

Stores a key-value pair in device storage.

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

Telegram.WebApp.DeviceStorage.setItem('cache_data', JSON.stringify({
  timestamp: Date.now(),
  data: largeDataSet
}), (error, success) => {
  if (error) {
    console.error('Storage failed:', error);
  }
});

getItem

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

Reads the value of a specified key from device storage.

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

removeItem

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

Removes a specified key from device storage.

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

clear

Telegram.WebApp.DeviceStorage.clear(callback)

Clears all data in device storage.

Parameter	Type	Required	Description
callback	Function	No	Callback with (error, success) parameters

Comparison with Cloud Storage

Feature	CloudStorage	DeviceStorage
Data sync	Cross-device sync	Local only
Capacity	1024 keys × 4KB values	5 MB total
Use cases	User preferences, small data	Cache, large local data
Min version	—	Bot API 8.0+

Usage Example

const deviceStorage = Telegram.WebApp.DeviceStorage;

// Cache API response
function cacheResponse(endpoint, data) {
  const cacheEntry = JSON.stringify({
    data: data,
    cachedAt: Date.now()
  });
  deviceStorage.setItem('cache_' + endpoint, cacheEntry);
}

// Read cache
function getCachedResponse(endpoint, maxAge, callback) {
  deviceStorage.getItem('cache_' + endpoint, (error, value) => {
    if (error || !value) {
      callback(null);
      return;
    }
    const entry = JSON.parse(value);
    if (Date.now() - entry.cachedAt > maxAge) {
      callback(null); // Cache expired
    } else {
      callback(entry.data);
    }
  });
}