gramdocs.tech
Документация

CloudStorage API: хранение данных пользователя

Сохранишь и прочитаешь данные пользователя через CloudStorage Mini App без своего бэкенда.

CloudStorage

CloudStorage (Bot API 6.9+) — ключ-значение хранилище в инфраструктуре Telegram: до 1024 ключей на пользователя на бота, значение до 4096 символов. Данные привязаны к паре «пользователь + бот», доступны с любого устройства, где открыт тот же Mini App.

Это не замена серверной БД для платежей и прав доступа: пользователь или клиент теоретически может влиять на клиентский контекст. Для секретов и балансов — свой бэкенд + валидный initData.

setItem / getItem

typescript
// Telegram WebApp CloudStorage — Bot API 6.9+
// script: https://telegram.org/js/telegram-web-app.js

type CloudStorage = {
  setItem: (
    key: string,
    value: string,
    callback?: (error: string | null, ok?: boolean) => void,
  ) => CloudStorage;
  getItem: (
    key: string,
    callback: (error: string | null, value?: string) => void,
  ) => CloudStorage;
  getItems: (
    keys: string[],
    callback: (error: string | null, values?: Record<string, string>) => void,
  ) => CloudStorage;
  removeItem: (
    key: string,
    callback?: (error: string | null, ok?: boolean) => void,
  ) => CloudStorage;
  getKeys: (
    callback: (error: string | null, keys?: string[]) => void,
  ) => CloudStorage;
};

const storage = window.Telegram.WebApp.CloudStorage as CloudStorage;

function setPreference(key: string, value: string): Promise<void> {
  return new Promise((resolve, reject) => {
    storage.setItem(key, value, (error, ok) => {
      if (error || !ok) {
        reject(new Error(error ?? "setItem failed"));
        return;
      }
      resolve();
    });
  });
}

function getPreference(key: string): Promise<string | undefined> {
  return new Promise((resolve, reject) => {
    storage.getItem(key, (error, value) => {
      if (error) {
        reject(new Error(error));
        return;
      }
      resolve(value);
    });
  });
}

window.Telegram.WebApp.ready();

await setPreference("theme_override", "system");
await setPreference("onboarding_done", "1");

const done = await getPreference("onboarding_done");
console.log(done); // "1"

storage.getKeys((error, keys) => {
  if (!error) console.log(keys);
});

Ограничения ключей: 1–128 символов, только A-Z a-z 0-9 _ -.

Как это работает

  • Привязка — данные живут у Telegram в контексте бота и user.id, не в localStorage устройства.
  • Колбэки — API асинхронный через callback; оберни в Promise для async/await.
  • Лимиты — 1024 ключа, 4096 символов на значение; для больших данных — свой storage.
  • Не для секретов — токены сессий и приватные ключи сюда не клади.

Частые ошибки

Кладёшь JSON > 4096 символов → setItem падает. Сократи payload или храни на сервере.

Ключ с точкой или пробелом → недопустимые символы. Используй snake_case / kebab-case.

Считаешь CloudStorage источником правды для баланса → легко рассинхронизировать с сервером. Деньги и доступы — только бэкенд после валидации initData.

Что дальше

Материалы gramdocs.tech носят образовательный характер и не являются финансовой, юридической или инвестиционной рекомендацией. Работа с блокчейном TON и токеном Gram связана с рисками потери средств. Правовая информация